3 SCons - a software construction tool
5 Welcome to the SCons development tree. The real purpose of this tree is
6 to package SCons for production distribution in a variety of formats,
7 not just to hack SCons code.
9 To that extent, the normal development cycle (enforced by Aegis) is not
10 to test the code directly, but to package SCons, unpack the package,
11 "install" SCons in a test subdirectory, and then to run the tests
12 against the unpacked and installed software. This helps eliminate
13 problems caused by, for example, failure to update the list of files to
16 Note that if all you want to do is install and run SCons, it
17 will probably be easier for you to download and install the
18 scons-{version}.tar.gz or scons-{version}.zip package rather than to
19 work with the packaging logic in this tree.
25 Before going further, you can check that this package you have is the
26 latest version at the SCons download page:
28 http://www.scons.org/download.html
31 EXECUTION REQUIREMENTS
32 ======================
34 Running SCons requires Python version 1.5.2 or later. There should be
35 no other dependencies or requirements to run SCons.
37 The default SCons configuration assumes use of the Microsoft Visual C++
38 compiler suite on WIN32 systems, and assumes a C compiler named 'cc',
39 a C++ compiler named 'c++', and a Fortran compiler named 'g77' (such
40 as found in the GNU C compiler suite) on any other type of system.
41 You may, of course, override these default values by appropriate
42 configuration of Environment construction variables.
44 By default, SCons knows how to search for available programming tools
45 on various systems--see the SCons man page for details. You may,
46 of course, override the default SCons choices made by appropriate
47 configuration of Environment construction variables.
50 INSTALLATION REQUIREMENTS
51 =========================
53 Building and installing SCons from this package requires the Python
54 distutils package. The distutils package was not shipped as a standard
55 part of Python until Python version 1.6, so if your system is running
56 Python 1.5.2, you may not have distutils installed. If you are running
57 Python version 1.6 or later, you should be fine.
59 NOTE TO RED HAT USERS: Red Hat shipped Python 1.5.2 as the default all
60 the way up to Red Hat Linux 7.3, so you probably do *not* have distutils
61 installed, unless you have already done so manually or are running Red
64 In this case, your options are:
66 -- (Optional.) Install from a pre-packaged SCons package that
67 does not require distutils:
69 Red Hat Linux scons-0.94-1.noarch.rpm
71 Debian GNU/Linux scons_0.94-1_all.deb
74 Windows scons-0.94.win32.exe
76 -- (Recommended.) Download the latest distutils package from the
79 http://www.python.org/sigs/distutils-sig/download.html
81 Install the distutils according to the instructions on the page.
82 You can then proceed to the next section to install SCons from
89 Assuming your system satisfies the installation requirements in
90 the previous section, install SCons from this package by first
91 populating the build/scons/ directory. (For an easier way to
92 install SCons, without having to populate this directory, use the
93 scons-{version}.tar.gz or scons-{version}.zip package.)
95 If you already have an appropriate version of SCons installed on your
96 system, populate the build/scons/ directory by running:
100 If you don't have SCons version 0.11 or later already installed on your
101 system, you can use SCons itself to populate the build/scons/ directory
102 with a little more typing:
104 $ SCONS_LIB_DIR=`pwd`/src/engine python src/script/scons.py build/scons
106 Either command will populate the build/scons/ directory with the
107 necessary files and directory structure to use the Python-standard setup
111 # python setup.py install
113 If this is the first time you are installing SCons on your system,
114 the above command will install the scons script in the default system
115 script directory (/usr/bin or C:\Python*\Scripts, for example) and the
116 build engine in an appropriate stand-alone SCons library directory
117 (/usr/lib/scons or C:\Python*\scons, for example).
119 Note that, by default, SCons does not install its library in the
120 standard Python library directories. If you want to be able to use the
121 SCons library modules (the build engine) in other Python scripts, you
122 can run the setup script as follows:
125 # python setup.py install --standard-lib
127 This will install the build engine in the standard Python
128 library directory (/usr/lib/python*/site-packages or
129 C:\Python*\Lib\site-packages).
131 Alternatively, you may want to install multiple versions of SCons
132 side-by-side, which you can do as follows:
135 # python setup.py install --version-lib
137 This will install the build engine in a version-specific library
138 directory (/usr/lib/scons-__VERSION__ or C:\Python*\scons-__VERSION__).
140 If this is not the first time you are installing SCons on your system,
141 the setup script will, by default, search for where you have previously
142 installed the SCons library, and install this version's library the
143 same way--that is, if you previously installed the SCons library in
144 the standard Python library, the setup script will install this one
145 in the same location. You may, of course, specify one of the --*-lib
146 options described above to select a specific library location, or use
147 the following option to explicitly select installation into the default
148 standalone library directory (/usr/lib/scons or C:\Python*\scons):
151 # python setup.py install --standalone-lib
153 Note that, to install SCons in any of the above system directories,
154 you should have system installation privileges (that is, "root" or
155 "Administrator") when running the setup.py script. If you don't have
156 system installation privileges, you can use the --prefix option to
157 specify an alternate installation location, such as your home directory:
160 $ python setup.py install --prefix=$HOME
162 This will install SCons in the appropriate locations relative to
163 $HOME--that is, the scons script itself $HOME/bin and the associated
164 library in $HOME/lib/scons, for example.
170 Tests are run by the runtest.py script in this directory.
172 There are two types of tests in this package:
174 Unit tests for individual SCons modules live underneath the
175 src/engine/ subdirectory and are the same base name as the module
176 with "Tests.py" appended--for example, the unit test for the
177 Builder.py module is the BuilderTests.py script.
179 End-to-end tests of SCons live in the test/ subdirectory.
181 You may specifically list one or more tests to be run:
183 $ python runtest.py src/engine/SCons/BuilderTests.py
185 $ python runtest.py test/option-j.py test/Program.py
187 Alternatively, the runtest.py script takes a -a option that searches
188 the tree for all of the tests and runs them:
190 $ python runtest.py -a
192 If more than one test is run, the runtest.py script prints a summary
193 of how many tests passed, failed, or yielded no result, and lists any
196 The above invocations all test directly the files underneath the src/
197 subdirectory, and do not require that a build be performed first. The
198 runtest.py script supports additional options to run tests against
199 unpacked packages in the build/test-*/ subdirectories. See the "TESTING
200 PACKAGES" section below.
206 We use SCons (version 0.11 or later) to build its own packages. If you
207 already have an appropriate version of SCons installed on your system,
208 you can build everything by simply running it:
212 If you don't have SCons version 0.11 or later already installed on your
213 system, you can build this version of SCons with itself with a little
216 $ SCONS_LIB_DIR=`pwd`/src/engine python src/script/scons.py
218 Depending on the utilities installed on your system, any or all of the
219 following packages will be built:
221 build/dist/scons-0.94-1.noarch.rpm
222 build/dist/scons-0.94-1.src.rpm
223 build/dist/scons-0.94.linux-i686.tar.gz
224 build/dist/scons-0.94.tar.gz
225 build/dist/scons-0.94.win32.exe
226 build/dist/scons-0.94.zip
227 build/dist/scons-doc-0.94.tar.gz
228 build/dist/scons-local-0.94.tar.gz
229 build/dist/scons-local-0.94.zip
230 build/dist/scons-src-0.94.tar.gz
231 build/dist/scons-src-0.94.zip
232 build/dist/scons_0.94-1_all.deb
234 The SConstruct file is supposed to be smart enough to avoid trying to
235 build packages for which you don't have the proper utilities installed.
236 For example, if you don't have Debian packaging tools installed, it
237 should just not build the .deb package, not fail the build.
239 If you receive a build error, please report it to the scons-devel
240 mailing list and open a bug report on the SCons bug tracker.
242 Note that in addition to creating the above packages, the default build
243 will also unpack one or more of the packages for testing.
249 A full build will unpack and/or install any .deb, .rpm., .local.tar.gz,
250 .local.zip, .src.tar.gz, .src.zip, .tar.gz, and .zip packages into
251 separate build/test-*/ subdirectories. (Of course, if a package was
252 not built on your system, it should not try to install it.) The
253 runtest.py script supports a -p option that will run the specified tests
254 (individually or collectively via the -a option) against the unpacked
255 build/test-/* subdirectory:
257 $ python runtest.py -p deb
259 $ python runtest.py -p rpm
261 $ python runtest.py -p local-tar-gz
263 $ python runtest.py -p local-zip
265 $ python runtest.py -p src-tar-gz
267 $ python runtest.py -p src-zip
269 $ python runtest.py -p tar-gz
271 $ python runtest.py -p zip
273 (The canonical invocation is to also use the runtest.py -a option so
274 that all tests are run against the specified package.)
277 CONTENTS OF THIS PACKAGE
278 ========================
280 Not guaranteed to be up-to-date (but better than nothing):
283 Miscellaneous utilities used in SCons development. Right now,
284 some of the stuff here includes:
286 -- a copy of the script we use to translate an Aegis change
288 -- a script that runs pychecker on our source tree
289 -- a script that counts source and test files and numbers
291 -- a script for synchronizing the Aegis tree to SourceForge
292 -- a prototype script for capturing sample SCons output
294 -- a script that can profile and time a packaging build of
296 -- a copy of xml_export, which can retrieve project data
300 A build script for use with Aegis. This collects a current copy
301 of SCons from the Aegis baseline directories in a bootstrap/
302 subdirectory, and then executes SCons with the supplied
303 command-line arguments.
306 This doesn't exist yet if you're looking at a vanilla source
307 tree. This is generated as part of our build process, and it's
308 where, believe it or not, we *build* everything.
311 The Aegis configuration, governing much of how we use Aegis to
312 build, test, control source, etc.
315 Files needed to construct a Debian package. The contents of this
316 directory are dictated by the Debian Policy Manual
317 (http://www.debian.org/doc/debian-policy). The package will not be
318 accepted into the Debian distribution unless the contents of this
319 directory satisfy the relevant Debian policies.
322 SCons documentation. A variety of things here, in various
323 stages of (in)completeness.
326 A subdirectory for miscellaneous things that we need. Right
327 now, it has copies of Python modules that we use for testing,
328 and which we don't want to force people to have to install on
329 their own just to help out with SCons development.
332 Stuff to generate files for Gentoo Linux.
335 Documentation of SCons administrative procedures (making a
336 change, releasing a new version). Maybe other administrative
340 A copy of the copyright and terms under which SCons is
341 distributed (the Open Source Initiative-approved MIT license).
344 A copy of the copyright and terms under which SCons is
345 distributed for inclusion in the scons-local-{version} packages.
346 This is the same as LICENSE with a preamble that specifies
347 the licensing terms are for SCons itself, not any other
348 package that includes SCons.
351 What you're looking at right now.
354 A README file for inclusion in the scons-local-{version}
355 packages. Similar to this file, but stripped down and modified
356 for people looking at including SCons in their shipped software.
359 The .spec file for building our RPM packages.
362 Script for running SCons tests. By default, this will run a
363 test against the code in the local src/ tree, so you don't
364 have to do a build before testing your changes. Aegis uses
365 it with an option that requires that you've done a build
366 (aeb) before running tests.
369 The "Makefile" for the SCons distribution.
371 (It has been pointed out that it's hard to find the SCons API
372 in this SConstruct file, and that it looks a lot more like a
373 pure Python script than a build configuration file. That's
374 mainly because all of the magick we have to perform to deal with
375 all of the different packaging formats requires a lot of pure
376 Python manipulation. In other words, don't look at this file
377 for an example of how easy it is to use SCons to build "normal"
381 Where the actual source code is kept, of course.
384 Template files, used by Aegis to give you a head start when you
385 aenf or aent a new file.
388 End-to-end tests of the SCons utility itself. These are
389 separate from the individual module unit tests, which live
390 side-by-side with the modules under src/.
396 See the src/RELEASE.txt file for notes about this specific release,
397 including known problems. See the src/CHANGES.txt file for a list of
398 changes since the previous release.
400 The doc/man/scons.1 man page is included in this package, and contains a
401 section of small examples for getting started using SCons.
403 Additional documentation for SCons is available at:
405 http://www.scons.org/doc.html
411 SCons is distributed under the MIT license, a full copy of which is
412 available in the LICENSE file. The MIT license is an approved Open
413 Source license, which means:
415 This software is OSI Certified Open Source Software. OSI
416 Certified is a certification mark of the Open Source Initiative.
418 More information about OSI certifications and Open Source software is
421 http://www.opensource.org/
427 You can report bugs either by following the "Tracker - Bugs" link
428 on the SCons project page:
430 http://sourceforge.net/projects/scons/
432 or by sending mail to the SCons developers mailing list:
434 scons-devel@lists.sourceforge.net
440 A mailing list for developers of SCons is available. You may send
441 questions or comments to the list at:
443 scons-devel@lists.sourceforge.net
445 You may request a subscription to the scons-devel mailing list at:
447 http://lists.sourceforge.net/lists/listinfo/scons-devel
449 Subscription to the list is by approval. In practice, no one is being
450 refused list membership right now, but we reserve the right to limit
451 membership in the future and/or weed out lurkers.
457 If you find SCons helpful, please consider making a donation (of cash,
458 software, or hardware) to support continued work on the project.
459 Information is available at:
461 http://www.scons.org/donate.html
467 Check the SCons web site at:
469 http://www.scons.org/
476 knight at baldmt dot com
477 http://www.baldmt.com/~knight/
479 With plenty of help from the SCons Development team: