-Welcome to the SCons development tree. Here's a brief guide (not
-guaranteed to be up-to-date) to what you'll find herein:
+# __COPYRIGHT__
-admin/
- Documentation of SCons administrative procedures. Maybe
- other administrative stuff in the future.
+ SCons - a software construction tool
-build/
- This doesn't exist if you're looking at a vanilla source tree.
- This is generated as part of our build process, and it's where,
- believe it or not, we *build* everything.
+Welcome to the SCons development tree. The real purpose of this tree is
+to package SCons for production distribution in a variety of formats,
+not just to hack SCons code.
+
+To that extent, the normal development cycle (enforced by Aegis) is not
+to test the code directly, but to package SCons, unpack the package,
+"install" SCons in a test subdirectory, and then to run the tests
+against the unpacked and installed software. This helps eliminate
+problems caused by, for example, failure to update the list of files to
+be packaged.
+
+Note that if all you want to do is install and run SCons, it
+will probably be easier for you to download and install the
+scons-{version}.tar.gz or scons-{version}.zip package rather than to
+work with the packaging logic in this tree.
+
+
+LATEST VERSION
+==============
+
+Before going further, you can check that this package you have is the
+latest version at the SCons download page:
+
+ http://www.scons.org/download.html
+
+
+EXECUTION REQUIREMENTS
+======================
+
+Running SCons requires Python version 1.5.2 or later. There should be
+no other dependencies or requirements to run SCons.
+
+The default SCons configuration assumes use of the Microsoft Visual C++
+compiler suite on WIN32 systems, and assumes a C compiler named 'cc',
+a C++ compiler named 'c++', and a Fortran compiler named 'g77' (such
+as found in the GNU C compiler suite) on any other type of system.
+You may, of course, override these default values by appropriate
+configuration of Environment construction variables.
+
+By default, SCons knows how to search for available programming tools
+on various systems--see the SCons man page for details. You may,
+of course, override the default SCons choices made by appropriate
+configuration of Environment construction variables.
+
+
+INSTALLATION REQUIREMENTS
+=========================
+
+Building and installing SCons from this package requires the Python
+distutils package. The distutils package was not shipped as a standard
+part of Python until Python version 1.6, so if your system is running
+Python 1.5.2, you may not have distutils installed. If you are running
+Python version 1.6 or later, you should be fine.
+
+NOTE TO RED HAT USERS: All Red Hat Linux versions up to 7.3 still ship
+Python 1.5.2 as the default, so you probably do *not* have distutils
+installed, unless you have already done so manually or are running Red
+Hat 8.0 or later.
+
+In this case, your options are:
+
+ -- (Optional.) Install from a pre-packaged SCons package that
+ does not require distutils:
+
+ Red Hat Linux scons-0.12-1.noarch.rpm
+
+ Debian GNU/Linux scons_0.12-1_all.deb
+ (or use apt-get)
+
+ Windows scons-0.12.win32.exe
+
+ -- (Recommended.) Download the latest distutils package from the
+ following URL:
+
+ http://www.python.org/sigs/distutils-sig/download.html
+
+ Install the distutils according to the instructions on the page.
+ You can then proceed to the next section to install SCons from
+ this package.
+
+
+INSTALLATION
+============
+
+Assuming your system satisfies the installation requirements in
+the previous section, install SCons from this package by first
+populating the build/scons/ directory. (For an easier way to
+install SCons, without having to populate this directory, use the
+scons-{version}.tar.gz or scons-{version}.zip package.)
+
+If you already have an appropriate version of SCons installed on your
+system, populate the build/scons/ directory by running:
+
+ $ scons build/scons
+
+If you don't have SCons version 0.11 or later already installed on your
+system, you can use SCons itself to populate the build/scons/ directory
+with a little more typing:
+
+ $ SCONS_LIB_DIR=`pwd`/src/engine python src/script/scons.py build/scons
+
+Either command will populate the build/scons/ directory with the
+necessary files and directory structure to use the Python-standard setup
+script as follows:
+
+ # cd build/scons
+ # python setup.py install
+
+If this is the first time you are installing SCons on your system,
+the above command will install the scons script in the default system
+script directory (/usr/bin or C:\Python*\Scripts, for example) and the
+build engine in an appropriate stand-alone SCons library directory
+(/usr/lib/scons or C:\Python*\scons, for example).
+
+Note that, by default, SCons does not install its library in the
+standard Python library directories. If you want to be able to use the
+SCons library modules (the build engine) in other Python scripts, you
+can run the setup script as follows:
+
+ # cd build/scons
+ # python setup.py install --standard-lib
+
+This will install the build engine in the standard Python
+library directory (/usr/lib/python*/site-packages or
+C:\Python*\Lib\site-packages).
+
+Alternatively, you may want to install multiple versions of SCons
+side-by-side, which you can do as follows:
+
+ # cd build/scons
+ # python setup.py install --version-lib
+
+This will install the build engine in a version-specific library
+directory (/usr/lib/scons-__VERSION__ or C:\Python*\scons-__VERSION__).
+
+If this is not the first time you are installing SCons on your system,
+the setup script will, by default, search for where you have previously
+installed the SCons library, and install this version's library the
+same way--that is, if you previously installed the SCons library in
+the standard Python library, the setup script will install this one
+in the same location. You may, of course, specify one of the --*-lib
+options described above to select a specific library location, or use
+the following option to explicitly select installation into the default
+standalone library directory (/usr/lib/scons or C:\Python*\scons):
+
+ # cd build/scons
+ # python setup.py install --standalone-lib
+
+Note that, to install SCons in any of the above system directories,
+you should have system installation privileges (that is, "root" or
+"Administrator") when running the setup.py script. If you don't have
+system installation privileges, you can use the --prefix option to
+specify an alternate installation location, such as your home directory:
+
+ $ cd build/scons
+ $ python setup.py install --prefix=$HOME
+
+This will install SCons in the appropriate locations relative to
+$HOME--that is, the scons script itself $HOME/bin and the associated
+library in $HOME/lib/scons, for example.
+
+
+TESTING
+=======
+
+Tests are run by the runtest.py script in this directory.
+
+There are two types of tests in this package:
+
+ Unit tests for individual SCons modules live underneath the
+ src/engine/ subdirectory and are the same base name as the module
+ with "Tests.py" appended--for example, the unit test for the
+ Builder.py module is the BuilderTests.py script.
+
+ End-to-end tests of SCons live in the test/ subdirectory.
+
+You may specifically list one or more tests to be run:
+
+ $ python runtest.py src/engine/SCons/BuilderTests.py
+
+ $ python runtest.py test/option-j.py test/Program.py
+
+Alternatively, the runtest.py script takes a -a option that searches
+the tree for all of the tests and runs them:
+
+ $ python runtest.py -a
+
+If more than one test is run, the runtest.py script prints a summary
+of how many tests passed, failed, or yielded no result, and lists any
+unsuccessful tests.
+
+The above invocations all test directly the files underneath the src/
+subdirectory, and do not require that a build be performed first. The
+runtest.py script supports additional options to run tests against
+unpacked packages in the build/test-*/ subdirectories. See the "TESTING
+PACKAGES" section below.
+
+
+BUILDING PACKAGES
+=================
+
+We now use SCons (version 0.11 or later) to build its own packages.
+If you already have an appropriate version of SCons installed on your
+system, you can build everything by simply running it:
+
+ $ scons
+
+If you don't have SCons version 0.11 or later already installed on your
+system, you can build this version of SCons with itself with a little
+more typing:
+
+ $ SCONS_LIB_DIR=`pwd`/src/engine python src/script/scons.py
+
+Depending on the utilities installed on your system, any or all of the
+following packages will be built:
-Construct
- The "Makefile" for the SCons distribution. Yes, we're using
- Cons to build its improved stepchild. (Of course, this will
- change to an SConstruct file as soon as we have SCons to the
- point where it can handle the functionality we need...)
+ build/dist/scons-0.12-1.noarch.rpm
+ build/dist/scons-0.12-1.src.rpm
+ build/dist/scons-0.12.linux-i686.tar.gz
+ build/dist/scons-0.12.tar.gz
+ build/dist/scons-0.12.win32.exe
+ build/dist/scons-0.12.zip
+ build/dist/scons-doc-0.12.tar.gz
+ build/dist/scons-local-0.12.tar.gz
+ build/dist/scons-local-0.12.zip
+ build/dist/scons-src-0.12.tar.gz
+ build/dist/scons-src-0.12.zip
+ build/dist/scons_0.12-1_all.deb
+
+The SConstruct file is supposed to be smart enough to avoid trying to
+build packages for which you don't have the proper utilities installed.
+For example, if you don't have Debian packaging tools installed, it
+should just not build the .deb package, not fail the build.
+
+If you receive a build error, please report it to the scons-devel
+mailing list and open a bug report on the SCons bug tracker.
+
+Note that in addition to creating the above packages, the default build
+will also unpack one or more of the packages for testing.
+
+
+TESTING PACKAGES
+================
+
+A full build will unpack and/or install any .deb, .rpm., .local.tar.gz,
+.local.zip, .src.tar.gz, .src.zip, .tar.gz, and .zip packages into
+separate build/test-*/ subdirectories. (Of course, if a package was
+not built on your system, it should not try to install it.) The
+runtest.py script supports a -p option that will run the specified tests
+(individually or collectively via the -a option) against the unpacked
+build/test-/* subdirectory:
+
+ $ python runtest.py -p deb
+
+ $ python runtest.py -p rpm
+
+ $ python runtest.py -p local-tar-gz
+
+ $ python runtest.py -p local-zip
+
+ $ python runtest.py -p src-tar-gz
+
+ $ python runtest.py -p src-zip
+
+ $ python runtest.py -p tar-gz
+
+ $ python runtest.py -p zip
+
+(The canonical invocation is to also use the runtest.py -a option so
+that all tests are run against the specified package.)
+
+
+CONTENTS OF THIS PACKAGE
+========================
+
+Not guaranteed to be up-to-date (but better than nothing):
+
+bin/
+ Miscellaneous utilities used in SCons development. Right now,
+ there's a copy of the script we use to translate an Aegis change
+ into a CVS checkin.
+
+bootstrap.py
+ A build script for use with Aegis. This collects a current copy
+ of SCons from the Aegis baseline directories in a bootstrap/
+ subdirectory, and then executes SCons with the supplied
+ command-line arguments.
+
+build/
+ This doesn't exist yet if you're looking at a vanilla source
+ tree. This is generated as part of our build process, and it's
+ where, believe it or not, we *build* everything.
config
The Aegis configuration, governing much of how we use Aegis to
build, test, control source, etc.
debian/
- Files needed to construct a Debian package. The contents of this
- directory are dictated by the Debian Policy Manual
- (http://www.debian.org/doc/debian-policy). The package will not be
- accepted into the Debian distribution unless the contents of this
- directory satisfy the relevant Debian policies.
+ Files needed to construct a Debian package. The contents of this
+ directory are dictated by the Debian Policy Manual
+ (http://www.debian.org/doc/debian-policy). The package will not be
+ accepted into the Debian distribution unless the contents of this
+ directory satisfy the relevant Debian policies.
+
+doc/
+ SCons documentation. A variety of things here, in various
+ stages of (in)completeness.
etc/
A subdirectory for miscellaneous things that we need. Right
and which we don't want to force people to have to install on
their own just to help out with SCons development.
+HOWTO/
+ Documentation of SCons administrative procedures (making a
+ change, releasing a new version). Maybe other administrative
+ stuff in the future.
+
+LICENSE
+ A copy of the copyright and terms under which SCons is
+ distributed (the Open Source Initiative-approved MIT license).
+
+LICENSE-local
+ A copy of the copyright and terms under which SCons is
+ distributed for inclusion in the scons-local-{version} packages.
+ This is the same as LICENSE with a preamble that specifies
+ the licensing terms are for SCons itself, not any other
+ package that includes SCons.
+
+README
+ What you're looking at right now.
+
+README-local
+ A README file for inclusion in the scons-local-{version}
+ packages. Similar to this file, but stripped down and modified
+ for people looking at including SCons in their shipped software.
+
+rpm/
+ The .spec file for building our RPM packages.
+
runtest.py
- Script for running our tests. By default, this will run a
- test against the code in the local src/ tree, so you don't
- have to do a build before testing your changes. Aegis uses
- it with an option that requires that you've done a build
- (aeb) before running tests.
+ Script for running SCons tests. By default, this will run a
+ test against the code in the local src/ tree, so you don't
+ have to do a build before testing your changes. Aegis uses
+ it with an option that requires that you've done a build
+ (aeb) before running tests.
+
+SConstruct
+ The "Makefile" for the SCons distribution.
+
+ (It has been pointed out that it's hard to find the SCons API
+ in this SConstruct file, and that it looks a lot more like a
+ pure Python script than a build configuration file. That's
+ mainly because all of the magick we have to perform to deal with
+ all of the different packaging formats requires a lot of pure
+ Python manipulation. In other words, don't look at this file
+ for an example of how easy it is to use SCons to build "normal"
+ software.)
src/
- Where the actual source code is kept, of course.
+ Where the actual source code is kept, of course.
template/
Template files, used by Aegis to give you a head start when you
- aenf or aent a new file. I haven't been keeping these up to
- date...
+ aenf or aent a new file.
test/
End-to-end tests of the SCons utility itself. These are
separate from the individual module unit tests, which live
side-by-side with the modules under src/.
+
+
+DOCUMENTATION
+=============
+
+See the src/RELEASE.txt file for notes about this specific release,
+including known problems. See the src/CHANGES.txt file for a list of
+changes since the previous release.
+
+The doc/man/scons.1 man page is included in this package, and contains a
+section of small examples for getting started using SCons.
+
+Additional documentation for SCons is available at:
+
+ http://www.scons.org/doc.html
+
+
+LICENSING
+=========
+
+SCons is distributed under the MIT license, a full copy of which is
+available in the LICENSE file. The MIT license is an approved Open
+Source license, which means:
+
+ This software is OSI Certified Open Source Software. OSI
+ Certified is a certification mark of the Open Source Initiative.
+
+More information about OSI certifications and Open Source software is
+available at:
+
+ http://www.opensource.org/
+
+
+REPORTING BUGS
+==============
+
+You can report bugs either by following the "Tracker - Bugs" link
+on the SCons project page:
+
+ http://sourceforge.net/projects/scons/
+
+or by sending mail to the SCons developers mailing list:
+
+ scons-devel@lists.sourceforge.net
+
+
+MAILING LISTS
+=============
+
+A mailing list for developers of SCons is available. You may send
+questions or comments to the list at:
+
+ scons-devel@lists.sourceforge.net
+
+You may request a subscription to the scons-devel mailing list at:
+
+ http://lists.sourceforge.net/lists/listinfo/scons-devel
+
+Subscription to the list is by approval. In practice, no one is being
+refused list membership right now, but we reserve the right to limit
+membership in the future and/or weed out lurkers.
+
+
+FOR MORE INFORMATION
+====================
+
+Check the SCons web site at:
+
+ http://www.scons.org/
+
+
+AUTHOR INFO
+===========
+
+Steven Knight
+knight at baldmt dot com
+http://www.baldmt.com/~knight/
+
+With plenty of help from the SCons Development team:
+ Chad Austin
+ Charles Crain
+ Steve Leblanc
+ Anthony Roach
+ Terrel Shumway
+
projects / scons.git / blobdiff