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.3.0.noarch.rpm
88 Debian GNU/Linux use apt-get to get the official package
90 Windows scons-1.3.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
102 EXECUTING SCONS WITHOUT INSTALLING
103 ==================================
105 You can execute the local SCons directly from the src/ subdirectory by
106 first setting the SCONS_LIB_DIR environment variable to the local
107 src/engine subdirectory, and then executing the local src/script/scons.py
108 script to populate the build/scons/ subdirectory. You would do this as
109 follows on a Linux or UNIX system (using sh or a derivative like bash or
112 $ setenv MYSCONS=`pwd`/src
113 $ setenv SCONS_LIB_DIR=$MYSCONS/engine
114 $ python $MYSCONS/script/scons.py [arguments]
118 C:\scons>set MYSCONS=%cd%\src
119 C:\scons>set SCONS_LIB_DIR=%MYSCONS%\engine
120 C:\scons>python %MYSCONS%\script\scons.py [arguments]
122 An alternative approach is to skip the above and use:
124 $ python bootstrap.py [arguments]
126 bootstrap.py keeps the src/ subdirectory free of compiled Python (*.pyc or
127 *.pyo) files by copying the necessary SCons files to a local bootstrap/
128 subdirectory and executing it from there.
130 You can use the -C option to have SCons change directory to another
131 location where you already have a build configuration set up.
133 $ python bootstrap.py -C /some/other/location [arguments]
135 For simplicity in the following examples, we will only show the
136 bootstrap.py approach.
142 NOTE: You don't need to build SCons packages or install SCons if
143 you just want to work on developing a patch. See the sections
144 about MAKING CHANGES and TESTING below if you just want to submit
145 a bug fix or some new functionality. See the sections below about
146 BUILDING PACKAGES and TESTING PACKAGES if your enhancement involves
147 changing the way in which SCons is packaged and/or installed on an
150 Assuming your system satisfies the installation requirements in the
151 previous section, install SCons from this package by first populating
152 the build/scons/ subdirectory. (For an easier way to install SCons,
153 without having to populate this directory, use the scons-{version}.tar.gz
154 or scons-{version}.zip package.)
156 Populate build/scons/ using a pre-installed SCons
157 -------------------------------------------------
159 If you already have an appropriate version of SCons installed on your
160 system, populate the build/scons/ directory by running:
164 Populate build/scons/ using the SCons source
165 --------------------------------------------
167 You can also use this version of SCons to populate its own build directory
168 by using a supplied bootstrap.py script (see the section above about
169 EXECUTING SCONS WITHOUT INSTALLING):
171 $ python bootstrap.py build/scons
173 Install the built SCons files
174 -----------------------------
176 Any of the above commands will populate the build/scons/ directory with
177 the necessary files and directory structure to use the Python-standard
178 setup script as follows on Linux or UNIX:
181 # python setup.py install
185 C:\scons\>cd build\scons
186 C:\scons\build\scons>python setup.py install
188 By default, the above commands will do the following:
190 -- Install the version-numbered "scons-1.3.0" and "sconsign-1.3.0"
191 scripts in the default system script directory (/usr/bin or
192 C:\Python*\Scripts, for example). This can be disabled by
193 specifying the "--no-version-script" option on the command
196 -- Install scripts named "scons" and "sconsign" scripts in the
197 default system script directory (/usr/bin or C:\Python*\Scripts,
198 for example). This can be disabled by specifying the
199 "--no-scons-script" option on the command line, which is useful
200 if you want to install and experiment with a new version before
201 making it the default on your system.
203 On UNIX or Linux systems, you can have the "scons" and "sconsign"
204 scripts be hard links or symbolic links to the "scons-1.3.0" and
205 "sconsign-1.3.0" scripts by specifying the "--hardlink-scons" or
206 "--symlink-scons" options on the command line.
208 -- Install "scons-1.3.0.bat" and "scons.bat" wrapper scripts in the
209 Python prefix directory on Windows (C:\Python*, for example).
210 This can be disabled by specifying the "--no-install-bat" option
213 On UNIX or Linux systems, the "--install-bat" option may be
214 specified to have "scons-1.3.0.bat" and "scons.bat" files installed
215 in the default system script directory, which is useful if you
216 want to install SCons in a shared file system directory that can
217 be used to execute SCons from both UNIX/Linux and Windows systems.
219 -- Install the SCons build engine (a Python module) in an
220 appropriate version-numbered SCons library directory
221 (/usr/lib/scons-1.3.0 or C:\Python*\scons-1.3.0, for example).
222 See below for more options related to installing the build
225 -- Install the troff-format man pages in an appropriate directory
226 on UNIX or Linux systems (/usr/share/man/man1 or /usr/man/man1,
227 for example). This can be disabled by specifying the
228 "--no-install-man" option on the command line. The man pages
229 can be installed on Windows systems by specifying the
230 "--install-man" option on the command line.
232 Note that, by default, SCons does not install its build engine library
233 in the standard Python library directories. If you want to be able to
234 use the SCons library modules (the build engine) in other Python
235 scripts, specify the "--standard-lib" option on the command line, as
238 # python setup.py install --standard-lib
240 This will install the build engine in the standard Python library
241 directory (/usr/lib/python*/site-packages or
242 C:\Python*\Lib\site-packages).
244 Alternatively, you can have SCons install its build engine library in a
245 hard-coded standalone library directory, instead of the default
246 version-numbered directory, by specifying the "--standalone-lib" option
247 on the command line, as follows:
249 # python setup.py install --standalone-lib
251 This is usually not recommended, however.
253 Note that, to install SCons in any of the above system directories,
254 you should have system installation privileges (that is, "root" or
255 "Administrator") when running the setup.py script. If you don't have
256 system installation privileges, you can use the --prefix option to
257 specify an alternate installation location, such as your home directory:
259 $ python setup.py install --prefix=$HOME
261 This will install SCons in the appropriate locations relative to
262 $HOME--that is, the scons script itself $HOME/bin and the associated
263 library in $HOME/lib/scons, for example.
269 Because SCons is implemented in a scripting language, you don't need to
270 build it in order to make changes and test them.
272 Virtually all of the SCons functionality exists in the "build engine,"
273 the src/engine/SCons subdirectory hierarchy that contains all of the
274 modules that make up SCons. The src/script/scons.py wrapper script exists
275 mainly to find the appropriate build engine library and then execute it.
277 In order to make your own changes locally and test them by hand, simply
278 edit modules in the local src/engine/SCons subdirectory tree and use the
279 local bootstrap.py script (see the section above about EXECUTING SCONS
282 $ python bootstrap.py [arguments]
284 If you want to be able to just execute your modified version of SCons from
285 the command line, you can make it executable and add its directory to your
288 $ chmod 755 src/script/scons.py
289 $ export PATH=$PATH:`pwd`/src/script
291 You should then be able to run this version of SCons by just typing
292 "scons.py" at your UNIX or Linux command line.
294 Note that the regular SCons development process makes heavy use of
295 automated testing. See the TESTING and DEVELOPMENT WORKFLOW sections
296 below for more information about the automated regression tests and how
297 they can be used in a development cycle to validate that your changes
298 don't break existing functionality.
304 Python comes with a good interactive debugger. When debugging changes
305 by hand (i.e., when not using the automated tests), you can invoke SCons
306 under control of the Python debugger by specifying the --debug=pdb option:
308 $ scons --debug=pdb [arguments]
309 > /home/knight/SCons/src/engine/SCons/Script/Main.py(927)_main()
310 -> default_warnings = [ SCons.Warnings.CorruptSConsignWarning,
313 Once in the debugger, you can set breakpoints at lines in files in the
314 build engine modules by providing the path name of the file relative to
315 the src/engine subdirectory (that is, including the SCons/ as the first
316 directory component):
318 (Pdb) b SCons/Tool/msvc.py:158
320 The debugger also supports single stepping, stepping into functions,
321 printing variables, etc.
323 Trying to debug problems found by running the automated tests (see the
324 TESTING section, below) is more difficult, because the test automation
325 harness re-invokes SCons and captures output. Consequently, there isn't an
326 easy way to invoke the Python debugger in a useful way on any particular
327 SCons call within a test script.
329 The most effective technique for debugging problems that occur during an
330 automated test is to use the good old tried-and-true technique of adding
331 statements to print tracing information. But note that you can't just use
332 "print" statement, or even "sys.stdout.write()," because those change the
333 SCons output, and the automated tests usually look for matches of specific
334 output strings to decide if a given SCons invocations passes the test.
336 To deal with this, SCons supports a Trace() function that (by default)
337 will print messages to your console screen ("/dev/tty" on UNIX or Linux,
338 "con" on Windows). By adding Trace() calls to the SCons source code:
340 def sample_method(self, value):
341 from SCons.Debug import Trace
342 Trace('called sample_method(%s, %s)\n' % (self, value))
344 You can then run automated tests that print any arbitrary information
345 you wish about what's going on inside SCons, without interfering with
348 The Trace() function can also redirect its output to a file, rather than
351 def sample_method(self, value):
352 from SCons.Debug import Trace
353 Trace('called sample_method(%s, %s)\n' % (self, value),
356 Where the Trace() function sends its output is stateful: once you use the
357 "file=" argument, all subsequent calls to Trace() send their output to
358 the same file, until another call with a "file=" argument is reached.
364 Tests are run by the runtest.py script in this directory.
366 There are two types of tests in this package:
368 Unit tests for individual SCons modules live underneath the
369 src/engine/ subdirectory and are the same base name as the module
370 with "Tests.py" appended--for example, the unit test for the
371 Builder.py module is the BuilderTests.py script.
373 End-to-end tests of SCons live in the test/ subdirectory.
375 You may specifically list one or more tests to be run:
377 $ python runtest.py src/engine/SCons/BuilderTests.py
379 $ python runtest.py test/option-j.py test/Program.py
381 You also use the -f option to execute just the tests listed in a specified
387 $ python runtest.py -f testlist.txt
389 One test must be listed per line, and any lines that begin with '#'
390 will be ignored (allowing you, for example, to comment out tests that
391 are currently passing and then uncomment all of the tests in the file
392 for a final validation run).
394 The runtest.py script also takes a -a option that searches the tree for
395 all of the tests and runs them:
397 $ python runtest.py -a
399 If more than one test is run, the runtest.py script prints a summary
400 of how many tests passed, failed, or yielded no result, and lists any
403 The above invocations all test directly the files underneath the src/
404 subdirectory, and do not require that a build be performed first. The
405 runtest.py script supports additional options to run tests against
406 unpacked packages in the build/test-*/ subdirectories. See the "TESTING
407 PACKAGES" section below.
413 CAVEAT: The point of this section isn't to describe one dogmatic
414 workflow. Just running the test suite can be time-consuming, and
415 getting a patch to pass all of the tests can be more so. If you're
416 genuinely blocked, it may make more sense to submit a patch with
417 a note about which tests still fail, and how. Someone else may be
418 able to take your "initial draft" and figure out how to improve it
419 to fix the rest of the tests. So there's plenty of room for use of
422 The various techniques described in the above sections can be combined
423 to create simple and effective workflows that allow you to validate
424 that patches you submit to SCons don't break existing functionality and
425 have adequate testing, thereby increasing the speed with which they can
428 For example, suppose your project's SCons configuration is blocked by
429 an SCons bug, and you decide you want to fix it and submit the patch.
430 Here's one possible way to go about doing that (using UNIX/Linux as the
431 development platform, Windows users can translate as appropriate)):
433 -- Change to the top of your checked-out SCons tree.
435 -- Confirm that the bug still exists in this version of SCons
436 by using the -C option to run the broken build:
438 $ python bootstrap.py -C /home/me/broken_project .
440 -- Fix the bug in SCons by editing appropriate module files
441 underneath src/engine/SCons.
443 -- Confirm that you've fixed the bug affecting your project:
445 $ python bootstrap.py -C /home/me/broken_project .
447 -- Test to see if your fix had any unintended side effects
448 that break existing functionality:
450 $ python runtest.py -a -o test.log
452 Be patient, there are more than 700 test scripts in the
453 whole suite. If you are on UNIX/Linux, you can use:
455 $ python runtest.py -a | tee test.log
457 instead so you can monitor progress from your terminal.
459 If any test scripts fail, they will be listed in a summary at
460 the end of the log file. Some test scripts may also report
461 NO RESULT because (for example) your local system is the wrong
462 type or doesn't have some installed utilities necessary to run
463 the script. In general, you can ignore the NO RESULT list.
465 -- Cut-and-paste the list of failed tests into a file:
468 test/failed-test-1.py
469 test/failed-test-2.py
470 test/failed-test-3.py
474 -- Now debug the test failures and fix them, either by changing
475 SCons, or by making necessary changes to the tests (if, for
476 example, you have a strong reason to change functionality, or
477 if you find that the bug really is in the test script itself).
478 After each change, use the runtest.py -f option to examine the
479 effects of the change on the subset of tests that originally
483 $ python runtest.py -f failed.txt
485 Repeat this until all of the tests that originally failed
488 -- Now you need to go back and validate that any changes you
489 made while getting the tests to pass didn't break the fix
490 you originally put in, and didn't introduce any *additional*
491 unintended side effects that broke other tests:
493 $ python bootstrap.py -C /home/me/broken_project .
494 $ python runtest.py -a -o test.log
496 If you find any newly-broken tests, add them to your "failed.txt"
497 file and go back to the previous step.
499 Of course, the above is only one suggested workflow. In practice, there
500 is a lot of room for judgment and experience to make things go quicker.
501 For example, if you're making a change to just the Java support, you
502 might start looking for regressions by just running the test/Java/*.py
503 tests instead of running all of "runtest.py -a".
509 We use SCons (version 0.96.93 later) to build its own packages. If you
510 already have an appropriate version of SCons installed on your system,
511 you can build everything by simply running it:
515 If you don't have SCons version 0.96.93 later already installed on your
516 system, you can use the supplied bootstrap.py script (see the section
517 above about EXECUTING SCONS WITHOUT INSTALLING):
519 $ python bootstrap.py build/scons
521 Depending on the utilities installed on your system, any or all of the
522 following packages will be built:
524 build/dist/scons-1.3.0-1.noarch.rpm
525 build/dist/scons-1.3.0-1.src.rpm
526 build/dist/scons-1.3.0.linux-i686.tar.gz
527 build/dist/scons-1.3.0.tar.gz
528 build/dist/scons-1.3.0.win32.exe
529 build/dist/scons-1.3.0.zip
530 build/dist/scons-doc-1.3.0.tar.gz
531 build/dist/scons-local-1.3.0.tar.gz
532 build/dist/scons-local-1.3.0.zip
533 build/dist/scons-src-1.3.0.tar.gz
534 build/dist/scons-src-1.3.0.zip
535 build/dist/scons_1.3.0-1_all.deb
537 The SConstruct file is supposed to be smart enough to avoid trying to
538 build packages for which you don't have the proper utilities installed.
539 For example, if you don't have Debian packaging tools installed, it
540 should just not build the .deb package, not fail the build.
542 If you receive a build error, please report it to the scons-devel
543 mailing list and open a bug report on the SCons bug tracker.
545 Note that in addition to creating the above packages, the default build
546 will also unpack one or more of the packages for testing.
552 A full build will unpack and/or install any .deb, .rpm., .local.tar.gz,
553 .local.zip, .src.tar.gz, .src.zip, .tar.gz, and .zip packages into
554 separate build/test-*/ subdirectories. (Of course, if a package was
555 not built on your system, it should not try to install it.) The
556 runtest.py script supports a -p option that will run the specified tests
557 (individually or collectively via the -a option) against the unpacked
558 build/test-/* subdirectory:
560 $ python runtest.py -p deb
562 $ python runtest.py -p rpm
564 $ python runtest.py -p local-tar-gz
566 $ python runtest.py -p local-zip
568 $ python runtest.py -p src-tar-gz
570 $ python runtest.py -p src-zip
572 $ python runtest.py -p tar-gz
574 $ python runtest.py -p zip
576 (The canonical invocation is to also use the runtest.py -a option so
577 that all tests are run against the specified package.)
580 CONTENTS OF THIS PACKAGE
581 ========================
583 Not guaranteed to be up-to-date (but better than nothing):
586 A subdirectory for benchmarking scripts, used to perform timing
587 tests to decide what specific idioms are most efficient for
588 various parts of the code base. We check these in so they're
589 available in case we have to revisit any of these decisions in
593 Miscellaneous utilities used in SCons development. Right now,
594 some of the stuff here includes:
596 -- a copy of the script we use to translate an Aegis change
598 -- a script that runs pychecker on our source tree
599 -- a script that counts source and test files and numbers
601 -- a script for synchronizing the Aegis tree to SourceForge
602 -- a prototype script for capturing sample SCons output
604 -- a script that can profile and time a packaging build of
606 -- a copy of xml_export, which can retrieve project data
608 -- scripts and a Python module for translating the SCons
609 home-brew XML documentation tags into DocBook and
613 A build script for use with Aegis. This collects a current copy
614 of SCons from the Aegis baseline directories in a bootstrap/
615 subdirectory, and then executes SCons with the supplied
616 command-line arguments.
619 This doesn't exist yet if you're looking at a vanilla source
620 tree. This is generated as part of our build process, and it's
621 where, believe it or not, we *build* everything.
624 The Aegis configuration, governing much of how we use Aegis to
625 build, test, control source, etc.
628 Files needed to construct a Debian package. The contents of this
629 directory are dictated by the Debian Policy Manual
630 (http://www.debian.org/doc/debian-policy). The package will not be
631 accepted into the Debian distribution unless the contents of this
632 directory satisfy the relevant Debian policies.
635 SCons documentation. A variety of things here, in various
636 stages of (in)completeness.
639 Stuff to generate files for Gentoo Linux.
642 Documentation of SCons administrative procedures (making a
643 change, releasing a new version). Maybe other administrative
647 A copy of the copyright and terms under which SCons is
648 distributed (the Open Source Initiative-approved MIT license).
651 A copy of the copyright and terms under which SCons is
652 distributed for inclusion in the scons-local-{version} packages.
653 This is the same as LICENSE with a preamble that specifies
654 the licensing terms are for SCons itself, not any other
655 package that includes SCons.
658 The Python modules we use for testing, some generic modules
659 originating elsewhere and some specific to SCons.
662 What you're looking at right now.
665 A README file for inclusion in the scons-local-{version}
666 packages. Similar to this file, but stripped down and modified
667 for people looking at including SCons in their shipped software.
670 The .spec file for building our RPM packages.
673 Script for running SCons tests. By default, this will run a
674 test against the code in the local src/ tree, so you don't
675 have to do a build before testing your changes. Aegis uses
676 it with an option that requires that you've done a build
677 (aeb) before running tests.
680 The "Makefile" for the SCons distribution.
682 (It has been pointed out that it's hard to find the SCons API
683 in this SConstruct file, and that it looks a lot more like a
684 pure Python script than a build configuration file. That's
685 mainly because all of the magick we have to perform to deal with
686 all of the different packaging formats requires a lot of pure
687 Python manipulation. In other words, don't look at this file
688 for an example of how easy it is to use SCons to build "normal"
692 Where the actual source code is kept, of course.
695 Template files, used by Aegis to give you a head start when you
696 aenf or aent a new file.
699 End-to-end tests of the SCons utility itself. These are
700 separate from the individual module unit tests, which live
701 side-by-side with the modules under src/.
707 See the src/RELEASE.txt file for notes about this specific release,
708 including known problems. See the src/CHANGES.txt file for a list of
709 changes since the previous release.
711 The doc/man/scons.1 man page is included in this package, and contains a
712 section of small examples for getting started using SCons.
714 Additional documentation for SCons is available at:
716 http://www.scons.org/doc.html
722 SCons is distributed under the MIT license, a full copy of which is
723 available in the LICENSE file. The MIT license is an approved Open
724 Source license, which means:
726 This software is OSI Certified Open Source Software. OSI
727 Certified is a certification mark of the Open Source Initiative.
729 More information about OSI certifications and Open Source software is
732 http://www.opensource.org/
738 Please report bugs by following the detailed instructions on our Bug
741 http://scons.tigris.org/bug-submission.html
743 You can also send mail to the SCons developers' mailing list:
747 But even if you send email to the mailing list please make sure that you
748 ALSO submit a bug report to the project page bug tracker, because bug
749 reports in email often get overlooked in the general flood of messages.
755 An active mailing list for developers of SCons is available. You may
756 send questions or comments to the list at:
760 You may request a subscription to the developer's mailing list by sending
763 dev-subscribe@scons.tigris.org
765 Subscription to the developer's mailing list is by approval. In practice,
766 no one is refused list membership, but we reserve the right to limit
767 membership in the future and/or weed out lurkers.
769 There is also a low-volume mailing list available for announcements
770 about SCons. Subscribe by sending email to:
772 announce-subscribe@scons.tigris.org
774 There are other mailing lists available for SCons users, for notification
775 of SCons code changes, and for notification of updated bug reports and
776 project documents. Please see our mailing lists page for details.
782 If you find SCons helpful, please consider making a donation (of cash,
783 software, or hardware) to support continued work on the project.
784 Information is available at:
786 http://www.scons.org/donate.html
792 Check the SCons web site at:
794 http://www.scons.org/
801 knight at baldmt dot com
802 http://www.baldmt.com/~knight/
804 With plenty of help from the SCons Development team: