3 SCons - a software construction tool
5 Welcome to the SCons development tree. The real purpose of this tree
6 is to package SCons for production distribution in a variety of formats,
7 not just to hack SCons code.
9 If all you want to do is install and run SCons, it will be easier for you
10 to download and install the scons-{version}.tar.gz or scons-{version}.zip
11 package rather than to work with the packaging logic in this tree.
13 To the extent that this tree is about building SCons packages, the
14 *full* development cycle (enforced by Aegis) is not to test the code
15 directly, but to package SCons, unpack the package, "install" SCons in
16 a test subdirectory, and then to run the tests against the unpacked and
17 installed software. This helps eliminate problems caused by, for example,
18 failure to update the list of files to be packaged.
20 For just working on making an individual change to the SCons source,
21 however, you don't actually need to build or install SCons; you
22 *can* actually edit and execute SCons in-place. See the following
23 sections below for more information:
26 How to edit and executing SCons in-place.
29 Tips for debugging problems in SCons.
32 How to use the automated regression tests.
35 An example of how to put the edit/execute/test pieces
36 together in a reasonable development workflow.
42 Before going further, you can check that this package you have is the
43 latest version at the SCons download page:
45 http://www.scons.org/download.html
48 EXECUTION REQUIREMENTS
49 ======================
51 Running SCons requires Python version 1.5.2 or later. There should be
52 no other dependencies or requirements to run SCons.
54 The default SCons configuration assumes use of the Microsoft Visual C++
55 compiler suite on WIN32 systems, and assumes a C compiler named 'cc',
56 a C++ compiler named 'c++', and a Fortran compiler named 'g77' (such
57 as found in the GNU C compiler suite) on any other type of system.
58 You may, of course, override these default values by appropriate
59 configuration of Environment construction variables.
61 By default, SCons knows how to search for available programming tools
62 on various systems--see the SCons man page for details. You may,
63 of course, override the default SCons choices made by appropriate
64 configuration of Environment construction variables.
67 INSTALLATION REQUIREMENTS
68 =========================
70 Building and installing SCons from this package requires the Python
71 distutils package. The distutils package was not shipped as a standard
72 part of Python until Python version 1.6, so if your system is running
73 Python 1.5.2, you may not have distutils installed. If you are running
74 Python version 1.6 or later, you should be fine.
76 NOTE TO RED HAT USERS: Red Hat shipped Python 1.5.2 as the default all
77 the way up to Red Hat Linux 7.3, so you probably do *not* have distutils
78 installed, unless you have already done so manually or are running Red
81 In this case, your options are:
83 -- (Optional.) Install from a pre-packaged SCons package that
84 does not require distutils:
86 Red Hat Linux scons-0.96.noarch.rpm
88 Debian GNU/Linux scons_0.96_all.deb
91 Windows scons-0.96.win32.exe
93 -- (Recommended.) Download the latest distutils package from the
96 http://www.python.org/sigs/distutils-sig/download.html
98 Install the distutils according to the instructions on the page.
99 You can then proceed to the next section to install SCons from
106 NOTE: You don't need to build SCons packages or install SCons if
107 you just want to work on developing a patch. See the sections
108 about MAKING CHANGES and TESTING below if you just want to submit
109 a bug fix or some new functionality. See the sections below about
110 BUILDING PACKAGES and TESTING PACKAGES if your enhancement involves
111 changing the way in which SCons is packaged and/or installed on an
114 Assuming your system satisfies the installation requirements in the
115 previous section, install SCons from this package by first populating
116 the build/scons/ subdirectory. (For an easier way to install SCons,
117 without having to populate this directory, use the scons-{version}.tar.gz
118 or scons-{version}.zip package.)
120 If you already have an appropriate version of SCons installed on your
121 system, populate the build/scons/ directory by running:
125 If you don't have SCons version 0.96 or later already installed on your
126 system, you can use SCons itself to populate the build/scons/ directory
127 with a little more typing. You must first set the SCONS_LIB_DIR
128 environment variable to the local src/engine subdirectory, and then
129 execute the local src/script/scons.py script to populate the build/scons/
130 subdirectory. You would do this as follows on a Linux or UNIX system
131 (using sh or a derivative like bash or ksh):
133 $ export SCONS_LIB_DIR=`pwd`/src/engine
134 $ python src/script/scons.py build/scons
136 Or as follows on Windows:
138 C:\scons\>set SCONS_LIB_DIR=%cd%\src\engine
139 C:\scons\>python src/script/scons.py build/scons
141 Either command will populate the build/scons/ directory with the necessary
142 files and directory structure to use the Python-standard setup script
143 as follows on Linux or UNIX:
146 # python setup.py install
150 C:\scons\>cd build\scons
151 C:\scons\build\scons>python setup.py install
153 By default, the above commands will do the following:
155 -- Install the version-numbered "scons-0.96" and "sconsign-0.96"
156 scripts in the default system script directory (/usr/bin or
157 C:\Python*\Scripts, for example). This can be disabled by
158 specifying the "--no-version-script" option on the command
161 -- Install scripts named "scons" and "sconsign" scripts in the
162 default system script directory (/usr/bin or C:\Python*\Scripts,
163 for example). This can be disabled by specifying the
164 "--no-scons-script" option on the command line, which is useful
165 if you want to install and experiment with a new version before
166 making it the default on your system. On UNIX or Linux systems,
167 you can have the "scons" and "sconsign" scripts be hard links or
168 symbolic links to the "scons-0.96" and "sconsign-0.96" scripts
169 by specifying the "--hardlink-scons" or "--symlink-scons"
170 options on the command line.
172 -- Install "scons-0.96.bat" and "scons.bat" wrapper scripts in the
173 Python prefix directory on Windows (C:\Python*, for example).
174 This can be disabled by specifying the "--no-install-bat" option
175 on the command line. On UNIX or Linux systems, the
176 "--install-bat" option may be specified to have "scons-0.96.bat"
177 and "scons.bat" files installed in the default system script
178 directory, which is useful if you want to install SCons in a
179 shared file system directory that can be used to execute SCons
180 from both UNIX/Linux and Windows systems.
182 -- Install the SCons build engine (a Python module) in an
183 appropriate version-numbered SCons library directory
184 (/usr/lib/scons-0.96 or C:\Python*\scons-0.96, for example).
185 See below for more options related to installing the build
188 -- Install the troff-format man pages in an appropriate directory
189 on UNIX or Linux systems (/usr/share/man/man1 or /usr/man/man1,
190 for example). This can be disabled by specifying the
191 "--no-install-man" option on the command line. The man pages
192 can be installed on Windows systems by specifying the
193 "--install-man" option on the command line.
195 Note that, by default, SCons does not install its build engine library
196 in the standard Python library directories. If you want to be able to
197 use the SCons library modules (the build engine) in other Python
198 scripts, specify the "--standard-lib" option on the command line, as
201 # python setup.py install --standard-lib
203 This will install the build engine in the standard Python library
204 directory (/usr/lib/python*/site-packages or
205 C:\Python*\Lib\site-packages).
207 Alternatively, you can have SCons install its build engine library in a
208 hard-coded standalone library directory, instead of the default
209 version-numbered directory, by specifying the "--standalone-lib" option
210 on the command line, as follows:
212 # python setup.py install --standalone-lib
214 This is usually not recommended, however.
216 Note that, to install SCons in any of the above system directories,
217 you should have system installation privileges (that is, "root" or
218 "Administrator") when running the setup.py script. If you don't have
219 system installation privileges, you can use the --prefix option to
220 specify an alternate installation location, such as your home directory:
222 $ python setup.py install --prefix=$HOME
224 This will install SCons in the appropriate locations relative to
225 $HOME--that is, the scons script itself $HOME/bin and the associated
226 library in $HOME/lib/scons, for example.
232 Because SCons is implemented in a scripting language, you don't need to
233 build it in order to make changes and test them.
235 Virtually all of the SCons functionality exists in the "build engine,"
236 the src/engine/SCons subdirectory hierarchy that contains all of the
237 modules that make up SCons. The src/script/scons.py wrapper script exists
238 mainly to find the appropriate build engine library and then execute it.
240 In order to make your own change locally and test them by hand, simply
241 edit modules in the local src/engine/SCons and set the SCONS_LIB_DIR
242 to point to that directory. Here is one way you can set up environment
243 variables to do this on a UNIX or Linux system:
245 $ setenv MYSCONS=`pwd`/src
246 $ setenv SCONS_LIB_DIR=$MYSCONS
247 $ python $MYSCONS/script/scons.py [arguments]
251 C:\scons>set MYSCONS=%cd%\src
252 C:\scons>set SCONS_LIB_DIR=%MYSCONS%
253 C:\scons>python %MYSCONS%\script\scons.py [arguments]
255 You can use the -C option to have SCons change directory to another
256 location where you already have a build configuration set up (for example,
257 if the SCons configuration for your project seems to be blocked by
258 an SCons bug, and you want to see if a patch you make actually fixes
261 $ python $MYSCONS/script/scons.py -C /some/other/location [arguments]
263 Lastly, if you want to be able to just execute your modified version
264 of SCons from the command line, you can make it executable and add its
265 directory to your $PATH like so:
267 $ chmod 755 src/script/scons.py
268 $ export PATH=$PATH:`pwd`/src/script
270 You should then be able to run this version of SCons by just typing
271 "scons.py" at your UNIX or Linux command line.
273 Note that the regular SCons development process makes heavy use of
274 automated testing. See the TESTING and DEVELOPMENT WORKFLOW sections
275 below for more information about the automated regression tests and how
276 they can be used in a development cycle to validate that your changes
277 don't break existing functionality.
283 Python comes with a good interactive debugger. When debugging changes
284 by hand (i.e., when not using the automated tests), you can invoke SCons
285 under control of the Python debugger by specifying the --debug=pdb option:
287 $ scons --debug=pdb [arguments]
288 > /home/knight/SCons/src/engine/SCons/Script/Main.py(927)_main()
289 -> default_warnings = [ SCons.Warnings.CorruptSConsignWarning,
292 Once in the debugger, you can set breakpoints at lines in files in the
293 build engine modules by providing the path name of the file relative to
294 the src/engine subdirectory (that is, including the SCons/ as the first
295 directory component):
297 (Pdb) b SCons/Tool/msvc.py:158
299 The debugger also supports single stepping, stepping into functions,
300 printing variables, etc.
302 Trying to debug problems found by running the automated tests (see the
303 TESTING section, below) is more difficult, because the test automation
304 harness re-invokes SCons and captures output. Consequently, there isn't an
305 easy way to invoke the Python debugger in a useful way on any particular
306 SCons call within a test script.
308 The most effective technique for debugging problems that occur during an
309 automated test is to use the good old tried-and-true technique of adding
310 statements to print tracing information. But note that you can't just use
311 "print" statement, or even "sys.stdout.write()," because those change the
312 SCons output, and the automated tests usually look for matches of specific
313 output strings to decide if a given SCons invocations passes the test.
315 To deal with this, SCons supports a Trace() function that (by default)
316 will print messages to your console screen ("/dev/tty" on UNIX or Linux,
317 "con" on Windows). By adding Trace() calls to the SCons source code:
319 def sample_method(self, value):
320 fromn SCons.Debug import Trace
321 Trace('called sample_method(%s, %s)\n' % (self, value))
323 You can then run automated tests that print any arbitrary information
324 you wish about what's going on inside SCons, without interfering with
327 The Trace() function can also redirect its output to a file, rather than
330 def sample_method(self, value):
331 fromn SCons.Debug import Trace
332 Trace('called sample_method(%s, %s)\n' % (self, value),
335 Where the Trace() function sends its output is stateful: once you use the
336 "file=" argument, all subsequent calls to Trace() send their output to
337 the same file, until another call with a "file=" argument is reached.
343 Tests are run by the runtest.py script in this directory.
345 There are two types of tests in this package:
347 Unit tests for individual SCons modules live underneath the
348 src/engine/ subdirectory and are the same base name as the module
349 with "Tests.py" appended--for example, the unit test for the
350 Builder.py module is the BuilderTests.py script.
352 End-to-end tests of SCons live in the test/ subdirectory.
354 You may specifically list one or more tests to be run:
356 $ python runtest.py src/engine/SCons/BuilderTests.py
358 $ python runtest.py test/option-j.py test/Program.py
360 You also use the -f option to execute just the tests listed in a specified
366 $ python runtest.py -f testlist.txt
368 One test must be listed per line, and any lines that begin with '#'
369 will be ignored (allowing you, for example, to comment out tests that
370 are currently passing and then uncomment all of the tests in the file
371 for a final validation run).
373 The runtest.py script also takes a -a option that searches the tree for
374 all of the tests and runs them:
376 $ python runtest.py -a
378 If more than one test is run, the runtest.py script prints a summary
379 of how many tests passed, failed, or yielded no result, and lists any
382 The above invocations all test directly the files underneath the src/
383 subdirectory, and do not require that a build be performed first. The
384 runtest.py script supports additional options to run tests against
385 unpacked packages in the build/test-*/ subdirectories. See the "TESTING
386 PACKAGES" section below.
392 CAVEAT: The point of this section isn't to describe one dogmatic
393 workflow. Just running the test suite can be time-consuming, and
394 getting a patch to pass all of the tests can be more so. If you're
395 genuinely blocked, it may make more sense to submit a patch with
396 a note about which tests still fail, and how. Someone else may be
397 able to take your "initial draft" and figure out how to improve it
398 to fix the rest of the tests. So there's plenty of room for use of
401 The various techniques described in the above sections can be combined
402 to create simple and effective workflows that allow you to validate
403 that patches you submit to SCons don't break existing functionality and
404 have adequate testing, thereby increasing the speed with which they can
407 For example, suppose your project's SCons configuration is blocked by
408 an SCons bug, and you decide you want to fix it and submit the patch.
409 Here's one possible way to go about doing that (using UNIX/Linux as the
410 development platform, Windows users can translate as appropriate)):
412 -- Change to the top of your checked-out SCons tree and set
413 $SCONS_LIB_DIR to point to its build engine:
415 $ setenv SCONS_LIB_DIR=`pwd`/src
417 -- Confirm that the bug still exists in this version of SCons
418 by using the -C option to run the broken build:
420 $ python script/scons.py -C /home/me/broken_project .
422 -- Fix the bug in SCons by editing appropriate module files
423 underneath src/engine/SCons.
425 -- Confirm that you've fixed the bug affecting your project:
427 $ python script/scons.py -C /home/me/broken_project .
429 -- Test to see if your fix had any unintended side effects
430 that break existing functionality:
432 $ python runtest.py -a
434 Be patient, there are more than 500 test scripts in the
437 If any test scripts fail, they will be listed in a summary at
438 the end of the run. Some test scripts may also report NO RESULT
439 because (for example) your local system is the wrong type or
440 doesn't have some installed utilities necessary to run the
441 script. In general, you can ignore the NO RESULT list.
443 -- Cut-and-paste the list of failed tests into a file:
446 test/failed-test-1.py
447 test/failed-test-2.py
448 test/failed-test-3.py
452 -- Now debug the test failures and fix them, either by changing
453 SCons, or by making necessary changes to the tests (if, for
454 example, you have a strong reason to change functionality, or
455 if you find that the bug really is in the test script itself).
456 After each change, use the runtest.py -f option to examine the
457 effects of the change on the subset of tests that originally
461 $ python runtest.py -f failed.txt
463 Repeat this until all of the tests that originally failed
466 -- Now you need to go back and validate that any changes you
467 made while getting the tests to pass didn't break the fix you
468 originally put in, or introduce any *additional* unintended side
469 effects that broke other tests:
471 $ python script/scons.py -C /home/me/broken_project .
472 $ python runtest.py -a
474 If you find any newly-broken tests, add them to your "failed.txt"
475 file and go back to the previous step.
477 Of course, the above is only one suggested workflow. In practice, there's
478 a lot of room for judgment and experience to make things go quicker.
479 For example, if you're making a change to just the Java support, you
480 might start looking for regressions by just running the test/Java/*.py
481 tests instead of running all of "runtest.py -a".
487 We use SCons (version 0.96 or later) to build its own packages. If you
488 already have an appropriate version of SCons installed on your system,
489 you can build everything by simply running it:
493 If you don't have SCons version 0.96 or later already installed on your
494 system, you can build this version of SCons with itself with a little more
495 typing. On UNIX or Linux (using sh or a derivative like bash or ksh):
497 $ export SCONS_LIB_DIR=`pwd`/src/engine
498 $ python src/script/scons.py
502 C:\scons\>set SCONS_LIB_DIR=%cd%\src\engine
503 C:\scons\>python src/script/scons.py
505 Depending on the utilities installed on your system, any or all of the
506 following packages will be built:
508 build/dist/scons-0.96-1.noarch.rpm
509 build/dist/scons-0.96-1.src.rpm
510 build/dist/scons-0.96.linux-i686.tar.gz
511 build/dist/scons-0.96.tar.gz
512 build/dist/scons-0.96.win32.exe
513 build/dist/scons-0.96.zip
514 build/dist/scons-doc-0.96.tar.gz
515 build/dist/scons-local-0.96.tar.gz
516 build/dist/scons-local-0.96.zip
517 build/dist/scons-src-0.96.tar.gz
518 build/dist/scons-src-0.96.zip
519 build/dist/scons_0.96-1_all.deb
521 The SConstruct file is supposed to be smart enough to avoid trying to
522 build packages for which you don't have the proper utilities installed.
523 For example, if you don't have Debian packaging tools installed, it
524 should just not build the .deb package, not fail the build.
526 If you receive a build error, please report it to the scons-devel
527 mailing list and open a bug report on the SCons bug tracker.
529 Note that in addition to creating the above packages, the default build
530 will also unpack one or more of the packages for testing.
536 A full build will unpack and/or install any .deb, .rpm., .local.tar.gz,
537 .local.zip, .src.tar.gz, .src.zip, .tar.gz, and .zip packages into
538 separate build/test-*/ subdirectories. (Of course, if a package was
539 not built on your system, it should not try to install it.) The
540 runtest.py script supports a -p option that will run the specified tests
541 (individually or collectively via the -a option) against the unpacked
542 build/test-/* subdirectory:
544 $ python runtest.py -p deb
546 $ python runtest.py -p rpm
548 $ python runtest.py -p local-tar-gz
550 $ python runtest.py -p local-zip
552 $ python runtest.py -p src-tar-gz
554 $ python runtest.py -p src-zip
556 $ python runtest.py -p tar-gz
558 $ python runtest.py -p zip
560 (The canonical invocation is to also use the runtest.py -a option so
561 that all tests are run against the specified package.)
564 CONTENTS OF THIS PACKAGE
565 ========================
567 Not guaranteed to be up-to-date (but better than nothing):
570 A subdirectory for benchmarking scripts, used to perform timing
571 tests to decide what specific idioms are most efficient for
572 various parts of the code base. We check these in so they're
573 available in case we have to revisit any of these decisions in
577 Miscellaneous utilities used in SCons development. Right now,
578 some of the stuff here includes:
580 -- a copy of the script we use to translate an Aegis change
582 -- a script that runs pychecker on our source tree
583 -- a script that counts source and test files and numbers
585 -- a script for synchronizing the Aegis tree to SourceForge
586 -- a prototype script for capturing sample SCons output
588 -- a script that can profile and time a packaging build of
590 -- a copy of xml_export, which can retrieve project data
594 A build script for use with Aegis. This collects a current copy
595 of SCons from the Aegis baseline directories in a bootstrap/
596 subdirectory, and then executes SCons with the supplied
597 command-line arguments.
600 This doesn't exist yet if you're looking at a vanilla source
601 tree. This is generated as part of our build process, and it's
602 where, believe it or not, we *build* everything.
605 The Aegis configuration, governing much of how we use Aegis to
606 build, test, control source, etc.
609 Files needed to construct a Debian package. The contents of this
610 directory are dictated by the Debian Policy Manual
611 (http://www.debian.org/doc/debian-policy). The package will not be
612 accepted into the Debian distribution unless the contents of this
613 directory satisfy the relevant Debian policies.
616 SCons documentation. A variety of things here, in various
617 stages of (in)completeness.
620 A subdirectory for miscellaneous things that we need. Right
621 now, it has copies of Python modules that we use for testing,
622 and which we don't want to force people to have to install on
623 their own just to help out with SCons development.
626 Stuff to generate files for Gentoo Linux.
629 Documentation of SCons administrative procedures (making a
630 change, releasing a new version). Maybe other administrative
634 A copy of the copyright and terms under which SCons is
635 distributed (the Open Source Initiative-approved MIT license).
638 A copy of the copyright and terms under which SCons is
639 distributed for inclusion in the scons-local-{version} packages.
640 This is the same as LICENSE with a preamble that specifies
641 the licensing terms are for SCons itself, not any other
642 package that includes SCons.
645 What you're looking at right now.
648 A README file for inclusion in the scons-local-{version}
649 packages. Similar to this file, but stripped down and modified
650 for people looking at including SCons in their shipped software.
653 The .spec file for building our RPM packages.
656 Script for running SCons tests. By default, this will run a
657 test against the code in the local src/ tree, so you don't
658 have to do a build before testing your changes. Aegis uses
659 it with an option that requires that you've done a build
660 (aeb) before running tests.
663 The "Makefile" for the SCons distribution.
665 (It has been pointed out that it's hard to find the SCons API
666 in this SConstruct file, and that it looks a lot more like a
667 pure Python script than a build configuration file. That's
668 mainly because all of the magick we have to perform to deal with
669 all of the different packaging formats requires a lot of pure
670 Python manipulation. In other words, don't look at this file
671 for an example of how easy it is to use SCons to build "normal"
675 Where the actual source code is kept, of course.
678 Template files, used by Aegis to give you a head start when you
679 aenf or aent a new file.
682 End-to-end tests of the SCons utility itself. These are
683 separate from the individual module unit tests, which live
684 side-by-side with the modules under src/.
690 See the src/RELEASE.txt file for notes about this specific release,
691 including known problems. See the src/CHANGES.txt file for a list of
692 changes since the previous release.
694 The doc/man/scons.1 man page is included in this package, and contains a
695 section of small examples for getting started using SCons.
697 Additional documentation for SCons is available at:
699 http://www.scons.org/doc.html
705 SCons is distributed under the MIT license, a full copy of which is
706 available in the LICENSE file. The MIT license is an approved Open
707 Source license, which means:
709 This software is OSI Certified Open Source Software. OSI
710 Certified is a certification mark of the Open Source Initiative.
712 More information about OSI certifications and Open Source software is
715 http://www.opensource.org/
721 Please report bugs by following the "Tracker - Bugs" link on the SCons
722 project page and filling out the form:
724 http://sourceforge.net/projects/scons/
726 You can also send mail to the SCons developers mailing list:
728 scons-devel@lists.sourceforge.net
730 But please make sure that you also submit a bug report to the project
731 page bug tracker, because bug reports in email can sometimes get lost
732 in the general flood of messages.
738 An active mailing list for developers of SCons is available. You may
739 send questions or comments to the list at:
743 You may request a subscription to the developer's mailing list by sending
746 dev-subscribe@scons.tigris.org
748 Subscription to the developer's mailing list is by approval. In practice,
749 no one is refused list membership, but we reserve the right to limit
750 membership in the future and/or weed out lurkers.
752 There is also a low-volume mailing list available for announcements
753 about SCons. Subscribe by sending email to:
755 announce-subscribe@scons.tigris.org
757 There are other mailing lists available for SCons users, for notification
758 of SCons code changes, and for notification of updated bug reports and
759 project documents. Please see our mailing lists page for details.
765 If you find SCons helpful, please consider making a donation (of cash,
766 software, or hardware) to support continued work on the project.
767 Information is available at:
769 http://www.scons.org/donate.html
775 Check the SCons web site at:
777 http://www.scons.org/
784 knight at baldmt dot com
785 http://www.baldmt.com/~knight/
787 With plenty of help from the SCons Development team: