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 *full*
14 development cycle is not just to test the code directly, but to package
15 SCons, unpack the package, "install" SCons in a test subdirectory,
16 and then to run the tests against the unpacked and installed software.
17 This helps eliminate problems caused by, for example, failure to update
18 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 execute 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-1.2.0.noarch.rpm
88 Debian GNU/Linux use apt-get to get the official package
90 Windows scons-1.2.0.win32.exe
92 -- (Recommended.) Download the latest distutils package from the
95 http://www.python.org/sigs/distutils-sig/download.html
97 Install the distutils according to the instructions on the page.
98 You can then proceed to the next section to install SCons from
105 NOTE: You don't need to build SCons packages or install SCons if
106 you just want to work on developing a patch. See the sections
107 about MAKING CHANGES and TESTING below if you just want to submit
108 a bug fix or some new functionality. See the sections below about
109 BUILDING PACKAGES and TESTING PACKAGES if your enhancement involves
110 changing the way in which SCons is packaged and/or installed on an
113 Assuming your system satisfies the installation requirements in the
114 previous section, install SCons from this package by first populating
115 the build/scons/ subdirectory. (For an easier way to install SCons,
116 without having to populate this directory, use the scons-{version}.tar.gz
117 or scons-{version}.zip package.)
119 If you already have an appropriate version of SCons installed on your
120 system, populate the build/scons/ directory by running:
124 You can also use this version of SCons to populate its own build directory
125 by using a supplied bootstrap.py script:
127 $ python bootstrap.py build/scons
129 The bootstrap.py keeps the src/ subdirectory free of compiled Python
130 (*.pyc or *.pyo) files by copying the necessary SCons files to a local
131 bootstrap/ subdirectory and executing it from there.
133 You can also execute the local SCons directly from the src/ subdirectory
134 by first setting the SCONS_LIB_DIR environment variable to the local
135 src/engine subdirectory, and then executing the local src/script/scons.py
136 script to populate the build/scons/ subdirectory. You would do this as
137 follows on a Linux or UNIX system (using sh or a derivative like bash
140 $ export SCONS_LIB_DIR=`pwd`/src/engine
141 $ python src/script/scons.py build/scons
143 Or as follows on Windows:
145 C:\scons\>set SCONS_LIB_DIR=%cd%\src\engine
146 C:\scons\>python src\script\scons.py build/scons
148 Any of the above commands will populate the build/scons/ directory with
149 the necessary files and directory structure to use the Python-standard
150 setup script as follows on Linux or UNIX:
153 # python setup.py install
157 C:\scons\>cd build\scons
158 C:\scons\build\scons>python setup.py install
160 By default, the above commands will do the following:
162 -- Install the version-numbered "scons-1.2.0" and "sconsign-1.2.0"
163 scripts in the default system script directory (/usr/bin or
164 C:\Python*\Scripts, for example). This can be disabled by
165 specifying the "--no-version-script" option on the command
168 -- Install scripts named "scons" and "sconsign" scripts in the
169 default system script directory (/usr/bin or C:\Python*\Scripts,
170 for example). This can be disabled by specifying the
171 "--no-scons-script" option on the command line, which is useful
172 if you want to install and experiment with a new version before
173 making it the default on your system.
175 On UNIX or Linux systems, you can have the "scons" and "sconsign"
176 scripts be hard links or symbolic links to the "scons-1.2.0" and
177 "sconsign-1.2.0" scripts by specifying the "--hardlink-scons" or
178 "--symlink-scons" options on the command line.
180 -- Install "scons-1.2.0.bat" and "scons.bat" wrapper scripts in the
181 Python prefix directory on Windows (C:\Python*, for example).
182 This can be disabled by specifying the "--no-install-bat" option
185 On UNIX or Linux systems, the "--install-bat" option may be
186 specified to have "scons-1.2.0.bat" and "scons.bat" files installed
187 in the default system script directory, which is useful if you
188 want to install SCons in a shared file system directory that can
189 be used to execute SCons from both UNIX/Linux and Windows systems.
191 -- Install the SCons build engine (a Python module) in an
192 appropriate version-numbered SCons library directory
193 (/usr/lib/scons-1.2.0 or C:\Python*\scons-1.2.0, for example).
194 See below for more options related to installing the build
197 -- Install the troff-format man pages in an appropriate directory
198 on UNIX or Linux systems (/usr/share/man/man1 or /usr/man/man1,
199 for example). This can be disabled by specifying the
200 "--no-install-man" option on the command line. The man pages
201 can be installed on Windows systems by specifying the
202 "--install-man" option on the command line.
204 Note that, by default, SCons does not install its build engine library
205 in the standard Python library directories. If you want to be able to
206 use the SCons library modules (the build engine) in other Python
207 scripts, specify the "--standard-lib" option on the command line, as
210 # python setup.py install --standard-lib
212 This will install the build engine in the standard Python library
213 directory (/usr/lib/python*/site-packages or
214 C:\Python*\Lib\site-packages).
216 Alternatively, you can have SCons install its build engine library in a
217 hard-coded standalone library directory, instead of the default
218 version-numbered directory, by specifying the "--standalone-lib" option
219 on the command line, as follows:
221 # python setup.py install --standalone-lib
223 This is usually not recommended, however.
225 Note that, to install SCons in any of the above system directories,
226 you should have system installation privileges (that is, "root" or
227 "Administrator") when running the setup.py script. If you don't have
228 system installation privileges, you can use the --prefix option to
229 specify an alternate installation location, such as your home directory:
231 $ python setup.py install --prefix=$HOME
233 This will install SCons in the appropriate locations relative to
234 $HOME--that is, the scons script itself $HOME/bin and the associated
235 library in $HOME/lib/scons, for example.
241 Because SCons is implemented in a scripting language, you don't need to
242 build it in order to make changes and test them.
244 Virtually all of the SCons functionality exists in the "build engine,"
245 the src/engine/SCons subdirectory hierarchy that contains all of the
246 modules that make up SCons. The src/script/scons.py wrapper script exists
247 mainly to find the appropriate build engine library and then execute it.
249 In order to make your own changes locally and test them by hand, simply
250 edit modules in the local src/engine/SCons subdirectory tree and either
251 use the local bootstrap.py script:
253 $ python bootstrap.py [arguments]
255 Or set the SCONS_LIB_DIR to point to the src/engine/SCons directory and
256 then execute the src/script/scons.py script. Here is one way you can
257 set up environment variables to do this on a UNIX or Linux system:
259 $ setenv MYSCONS=`pwd`/src
260 $ setenv SCONS_LIB_DIR=$MYSCONS/engine
261 $ python $MYSCONS/script/scons.py [arguments]
265 C:\scons>set MYSCONS=%cd%\src
266 C:\scons>set SCONS_LIB_DIR=%MYSCONS%\engine
267 C:\scons>python %MYSCONS%\script\scons.py [arguments]
269 You can use the -C option to have SCons change directory to another
270 location where you already have a build configuration set up (for example,
271 if the SCons configuration for your project seems to be blocked by
272 an SCons bug, and you want to see if a patch you make actually fixes
275 $ python bootstrap.py -C /some/other/location [arguments]
277 Lastly, if you want to be able to just execute your modified version
278 of SCons from the command line, you can make it executable and add its
279 directory to your $PATH like so:
281 $ chmod 755 src/script/scons.py
282 $ export PATH=$PATH:`pwd`/src/script
284 You should then be able to run this version of SCons by just typing
285 "scons.py" at your UNIX or Linux command line.
287 Note that the regular SCons development process makes heavy use of
288 automated testing. See the TESTING and DEVELOPMENT WORKFLOW sections
289 below for more information about the automated regression tests and how
290 they can be used in a development cycle to validate that your changes
291 don't break existing functionality.
297 Python comes with a good interactive debugger. When debugging changes
298 by hand (i.e., when not using the automated tests), you can invoke SCons
299 under control of the Python debugger by specifying the --debug=pdb option:
301 $ scons --debug=pdb [arguments]
302 > /home/knight/SCons/src/engine/SCons/Script/Main.py(927)_main()
303 -> default_warnings = [ SCons.Warnings.CorruptSConsignWarning,
306 Once in the debugger, you can set breakpoints at lines in files in the
307 build engine modules by providing the path name of the file relative to
308 the src/engine subdirectory (that is, including the SCons/ as the first
309 directory component):
311 (Pdb) b SCons/Tool/msvc.py:158
313 The debugger also supports single stepping, stepping into functions,
314 printing variables, etc.
316 Trying to debug problems found by running the automated tests (see the
317 TESTING section, below) is more difficult, because the test automation
318 harness re-invokes SCons and captures output. Consequently, there isn't an
319 easy way to invoke the Python debugger in a useful way on any particular
320 SCons call within a test script.
322 The most effective technique for debugging problems that occur during an
323 automated test is to use the good old tried-and-true technique of adding
324 statements to print tracing information. But note that you can't just use
325 "print" statement, or even "sys.stdout.write()," because those change the
326 SCons output, and the automated tests usually look for matches of specific
327 output strings to decide if a given SCons invocations passes the test.
329 To deal with this, SCons supports a Trace() function that (by default)
330 will print messages to your console screen ("/dev/tty" on UNIX or Linux,
331 "con" on Windows). By adding Trace() calls to the SCons source code:
333 def sample_method(self, value):
334 from SCons.Debug import Trace
335 Trace('called sample_method(%s, %s)\n' % (self, value))
337 You can then run automated tests that print any arbitrary information
338 you wish about what's going on inside SCons, without interfering with
341 The Trace() function can also redirect its output to a file, rather than
344 def sample_method(self, value):
345 from SCons.Debug import Trace
346 Trace('called sample_method(%s, %s)\n' % (self, value),
349 Where the Trace() function sends its output is stateful: once you use the
350 "file=" argument, all subsequent calls to Trace() send their output to
351 the same file, until another call with a "file=" argument is reached.
357 Tests are run by the runtest.py script in this directory.
359 There are two types of tests in this package:
361 Unit tests for individual SCons modules live underneath the
362 src/engine/ subdirectory and are the same base name as the module
363 with "Tests.py" appended--for example, the unit test for the
364 Builder.py module is the BuilderTests.py script.
366 End-to-end tests of SCons live in the test/ subdirectory.
368 You may specifically list one or more tests to be run:
370 $ python runtest.py src/engine/SCons/BuilderTests.py
372 $ python runtest.py test/option-j.py test/Program.py
374 You also use the -f option to execute just the tests listed in a specified
380 $ python runtest.py -f testlist.txt
382 One test must be listed per line, and any lines that begin with '#'
383 will be ignored (allowing you, for example, to comment out tests that
384 are currently passing and then uncomment all of the tests in the file
385 for a final validation run).
387 The runtest.py script also takes a -a option that searches the tree for
388 all of the tests and runs them:
390 $ python runtest.py -a
392 If more than one test is run, the runtest.py script prints a summary
393 of how many tests passed, failed, or yielded no result, and lists any
396 The above invocations all test directly the files underneath the src/
397 subdirectory, and do not require that a build be performed first. The
398 runtest.py script supports additional options to run tests against
399 unpacked packages in the build/test-*/ subdirectories. See the "TESTING
400 PACKAGES" section below.
406 CAVEAT: The point of this section isn't to describe one dogmatic
407 workflow. Just running the test suite can be time-consuming, and
408 getting a patch to pass all of the tests can be more so. If you're
409 genuinely blocked, it may make more sense to submit a patch with
410 a note about which tests still fail, and how. Someone else may be
411 able to take your "initial draft" and figure out how to improve it
412 to fix the rest of the tests. So there's plenty of room for use of
415 The various techniques described in the above sections can be combined
416 to create simple and effective workflows that allow you to validate
417 that patches you submit to SCons don't break existing functionality and
418 have adequate testing, thereby increasing the speed with which they can
421 For example, suppose your project's SCons configuration is blocked by
422 an SCons bug, and you decide you want to fix it and submit the patch.
423 Here's one possible way to go about doing that (using UNIX/Linux as the
424 development platform, Windows users can translate as appropriate)):
426 -- Change to the top of your checked-out SCons tree and set
427 $SCONS_LIB_DIR to point to its build engine:
429 $ setenv SCONS_LIB_DIR=`pwd`/src
431 -- Confirm that the bug still exists in this version of SCons
432 by using the -C option to run the broken build:
434 $ python script/scons.py -C /home/me/broken_project .
436 -- Fix the bug in SCons by editing appropriate module files
437 underneath src/engine/SCons.
439 -- Confirm that you've fixed the bug affecting your project:
441 $ python script/scons.py -C /home/me/broken_project .
443 -- Test to see if your fix had any unintended side effects
444 that break existing functionality:
446 $ python runtest.py -a
448 Be patient, there are more than 700 test scripts in the
451 If any test scripts fail, they will be listed in a summary at
452 the end of the run. Some test scripts may also report NO RESULT
453 because (for example) your local system is the wrong type or
454 doesn't have some installed utilities necessary to run the
455 script. In general, you can ignore the NO RESULT list.
457 -- Cut-and-paste the list of failed tests into a file:
460 test/failed-test-1.py
461 test/failed-test-2.py
462 test/failed-test-3.py
466 -- Now debug the test failures and fix them, either by changing
467 SCons, or by making necessary changes to the tests (if, for
468 example, you have a strong reason to change functionality, or
469 if you find that the bug really is in the test script itself).
470 After each change, use the runtest.py -f option to examine the
471 effects of the change on the subset of tests that originally
475 $ python runtest.py -f failed.txt
477 Repeat this until all of the tests that originally failed
480 -- Now you need to go back and validate that any changes you
481 made while getting the tests to pass didn't break the fix
482 you originally put in, and didn't introduce any *additional*
483 unintended side effects that broke other tests:
485 $ python script/scons.py -C /home/me/broken_project .
486 $ python runtest.py -a
488 If you find any newly-broken tests, add them to your "failed.txt"
489 file and go back to the previous step.
491 Of course, the above is only one suggested workflow. In practice, there
492 is a lot of room for judgment and experience to make things go quicker.
493 For example, if you're making a change to just the Java support, you
494 might start looking for regressions by just running the test/Java/*.py
495 tests instead of running all of "runtest.py -a".
501 We use SCons (version 0.96.93 later) to build its own packages. If you
502 already have an appropriate version of SCons installed on your system,
503 you can build everything by simply running it:
507 If you don't have SCons version 0.96.93 later already installed on your
508 system, you can use the supplied bootstrap.py script:
510 $ python bootstrap.py build/scons
512 The bootstrap.py keeps the src/ subdirectory free of compiled Python
513 (*.pyc or *.pyo) files by copying the necessary SCons files to a local
514 bootstrap/ subdirectory and executing it from there.
516 You can also build this version of SCons by hand with a little more
517 typing. On UNIX or Linux (using sh or a derivative like bash or ksh):
519 $ export SCONS_LIB_DIR=`pwd`/src/engine
520 $ python src/script/scons.py
524 C:\scons\>set SCONS_LIB_DIR=%cd%\src\engine
525 C:\scons\>python src/script/scons.py
527 Depending on the utilities installed on your system, any or all of the
528 following packages will be built:
530 build/dist/scons-1.2.0-1.noarch.rpm
531 build/dist/scons-1.2.0-1.src.rpm
532 build/dist/scons-1.2.0.linux-i686.tar.gz
533 build/dist/scons-1.2.0.tar.gz
534 build/dist/scons-1.2.0.win32.exe
535 build/dist/scons-1.2.0.zip
536 build/dist/scons-doc-1.2.0.tar.gz
537 build/dist/scons-local-1.2.0.tar.gz
538 build/dist/scons-local-1.2.0.zip
539 build/dist/scons-src-1.2.0.tar.gz
540 build/dist/scons-src-1.2.0.zip
541 build/dist/scons_1.2.0-1_all.deb
543 The SConstruct file is supposed to be smart enough to avoid trying to
544 build packages for which you don't have the proper utilities installed.
545 For example, if you don't have Debian packaging tools installed, it
546 should just not build the .deb package, not fail the build.
548 If you receive a build error, please report it to the scons-devel
549 mailing list and open a bug report on the SCons bug tracker.
551 Note that in addition to creating the above packages, the default build
552 will also unpack one or more of the packages for testing.
558 A full build will unpack and/or install any .deb, .rpm., .local.tar.gz,
559 .local.zip, .src.tar.gz, .src.zip, .tar.gz, and .zip packages into
560 separate build/test-*/ subdirectories. (Of course, if a package was
561 not built on your system, it should not try to install it.) The
562 runtest.py script supports a -p option that will run the specified tests
563 (individually or collectively via the -a option) against the unpacked
564 build/test-/* subdirectory:
566 $ python runtest.py -p deb
568 $ python runtest.py -p rpm
570 $ python runtest.py -p local-tar-gz
572 $ python runtest.py -p local-zip
574 $ python runtest.py -p src-tar-gz
576 $ python runtest.py -p src-zip
578 $ python runtest.py -p tar-gz
580 $ python runtest.py -p zip
582 (The canonical invocation is to also use the runtest.py -a option so
583 that all tests are run against the specified package.)
586 CONTENTS OF THIS PACKAGE
587 ========================
589 Not guaranteed to be up-to-date (but better than nothing):
592 A subdirectory for benchmarking scripts, used to perform timing
593 tests to decide what specific idioms are most efficient for
594 various parts of the code base. We check these in so they're
595 available in case we have to revisit any of these decisions in
599 Miscellaneous utilities used in SCons development. Right now,
600 some of the stuff here includes:
602 -- a copy of the script we use to translate an Aegis change
604 -- a script that runs pychecker on our source tree
605 -- a script that counts source and test files and numbers
607 -- a script for synchronizing the Aegis tree to SourceForge
608 -- a prototype script for capturing sample SCons output
610 -- a script that can profile and time a packaging build of
612 -- a copy of xml_export, which can retrieve project data
614 -- scripts and a Python module for translating the SCons
615 home-brew XML documentation tags into DocBook and
619 A build script for use with Aegis. This collects a current copy
620 of SCons from the Aegis baseline directories in a bootstrap/
621 subdirectory, and then executes SCons with the supplied
622 command-line arguments.
625 This doesn't exist yet if you're looking at a vanilla source
626 tree. This is generated as part of our build process, and it's
627 where, believe it or not, we *build* everything.
630 The Aegis configuration, governing much of how we use Aegis to
631 build, test, control source, etc.
634 Files needed to construct a Debian package. The contents of this
635 directory are dictated by the Debian Policy Manual
636 (http://www.debian.org/doc/debian-policy). The package will not be
637 accepted into the Debian distribution unless the contents of this
638 directory satisfy the relevant Debian policies.
641 SCons documentation. A variety of things here, in various
642 stages of (in)completeness.
645 Stuff to generate files for Gentoo Linux.
648 Documentation of SCons administrative procedures (making a
649 change, releasing a new version). Maybe other administrative
653 A copy of the copyright and terms under which SCons is
654 distributed (the Open Source Initiative-approved MIT license).
657 A copy of the copyright and terms under which SCons is
658 distributed for inclusion in the scons-local-{version} packages.
659 This is the same as LICENSE with a preamble that specifies
660 the licensing terms are for SCons itself, not any other
661 package that includes SCons.
664 The Python modules we use for testing, some generic modules
665 originating elsewhere and some specific to SCons.
668 What you're looking at right now.
671 A README file for inclusion in the scons-local-{version}
672 packages. Similar to this file, but stripped down and modified
673 for people looking at including SCons in their shipped software.
676 The .spec file for building our RPM packages.
679 Script for running SCons tests. By default, this will run a
680 test against the code in the local src/ tree, so you don't
681 have to do a build before testing your changes. Aegis uses
682 it with an option that requires that you've done a build
683 (aeb) before running tests.
686 The "Makefile" for the SCons distribution.
688 (It has been pointed out that it's hard to find the SCons API
689 in this SConstruct file, and that it looks a lot more like a
690 pure Python script than a build configuration file. That's
691 mainly because all of the magick we have to perform to deal with
692 all of the different packaging formats requires a lot of pure
693 Python manipulation. In other words, don't look at this file
694 for an example of how easy it is to use SCons to build "normal"
698 Where the actual source code is kept, of course.
701 Template files, used by Aegis to give you a head start when you
702 aenf or aent a new file.
705 End-to-end tests of the SCons utility itself. These are
706 separate from the individual module unit tests, which live
707 side-by-side with the modules under src/.
713 See the src/RELEASE.txt file for notes about this specific release,
714 including known problems. See the src/CHANGES.txt file for a list of
715 changes since the previous release.
717 The doc/man/scons.1 man page is included in this package, and contains a
718 section of small examples for getting started using SCons.
720 Additional documentation for SCons is available at:
722 http://www.scons.org/doc.html
728 SCons is distributed under the MIT license, a full copy of which is
729 available in the LICENSE file. The MIT license is an approved Open
730 Source license, which means:
732 This software is OSI Certified Open Source Software. OSI
733 Certified is a certification mark of the Open Source Initiative.
735 More information about OSI certifications and Open Source software is
738 http://www.opensource.org/
744 Please report bugs by following the detailed instructions on our Bug
747 http://scons.tigris.org/bug-submission.html
749 You can also send mail to the SCons developers' mailing list:
753 But even if you send email to the mailing list please make sure that you
754 ALSO submit a bug report to the project page bug tracker, because bug
755 reports in email often get overlooked in the general flood of messages.
761 An active mailing list for developers of SCons is available. You may
762 send questions or comments to the list at:
766 You may request a subscription to the developer's mailing list by sending
769 dev-subscribe@scons.tigris.org
771 Subscription to the developer's mailing list is by approval. In practice,
772 no one is refused list membership, but we reserve the right to limit
773 membership in the future and/or weed out lurkers.
775 There is also a low-volume mailing list available for announcements
776 about SCons. Subscribe by sending email to:
778 announce-subscribe@scons.tigris.org
780 There are other mailing lists available for SCons users, for notification
781 of SCons code changes, and for notification of updated bug reports and
782 project documents. Please see our mailing lists page for details.
788 If you find SCons helpful, please consider making a donation (of cash,
789 software, or hardware) to support continued work on the project.
790 Information is available at:
792 http://www.scons.org/donate.html
798 Check the SCons web site at:
800 http://www.scons.org/
807 knight at baldmt dot com
808 http://www.baldmt.com/~knight/
810 With plenty of help from the SCons Development team: