Eliminate / replace remaining cPickle references in test scripts.
[scons.git] / README
1 # __COPYRIGHT__
2
3                  SCons - a software construction tool
4
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.
8
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.
12
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.
19
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:
24
25     MAKING CHANGES
26         How to edit and execute SCons in-place.
27
28     DEBUGGING
29         Tips for debugging problems in SCons.
30
31     TESTING
32         How to use the automated regression tests.
33
34     DEVELOPMENT WORKFLOW
35         An example of how to put the edit/execute/test pieces
36         together in a reasonable development workflow.
37
38
39 LATEST VERSION
40 ==============
41
42 Before going further, you can check that this package you have is the
43 latest version at the SCons download page:
44
45         http://www.scons.org/download.html
46
47
48 EXECUTION REQUIREMENTS
49 ======================
50
51 Running SCons requires Python version 1.5.2 or later.  There should be
52 no other dependencies or requirements to run SCons.
53
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.
60
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.
65
66
67 INSTALLATION REQUIREMENTS
68 =========================
69
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.
75
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
79 Hat 8.0 or later.
80
81 In this case, your options are:
82
83     --  (Optional.)  Install from a pre-packaged SCons package that
84         does not require distutils:
85
86             Red Hat Linux       scons-1.3.0.noarch.rpm
87
88             Debian GNU/Linux    use apt-get to get the official package
89
90             Windows             scons-1.3.0.win32.exe
91
92     --  (Recommended.)  Download the latest distutils package from the
93         following URL:
94
95             http://www.python.org/sigs/distutils-sig/download.html
96
97         Install the distutils according to the instructions on the page.
98         You can then proceed to the next section to install SCons from
99         this package.
100
101
102 INSTALLATION
103 ============
104
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
111     end-user system.
112
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.)
118
119 If you already have an appropriate version of SCons installed on your
120 system, populate the build/scons/ directory by running:
121
122         $ scons build/scons
123
124 You can also use this version of SCons to populate its own build directory
125 by using a supplied bootstrap.py script:
126
127         $ python bootstrap.py build/scons
128
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.
132
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
138 or ksh):
139
140         $ export SCONS_LIB_DIR=`pwd`/src/engine
141         $ python src/script/scons.py build/scons
142
143 Or as follows on Windows:
144         
145         C:\scons\>set SCONS_LIB_DIR=%cd%\src\engine
146         C:\scons\>python src\script\scons.py build/scons
147
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:
151
152         # cd build/scons
153         # python setup.py install
154
155 And on Windows:
156
157         C:\scons\>cd build\scons
158         C:\scons\build\scons>python setup.py install
159
160 By default, the above commands will do the following:
161
162     --  Install the version-numbered "scons-1.3.0" and "sconsign-1.3.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
166         line.
167
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.
174
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.3.0" and
177         "sconsign-1.3.0" scripts by specifying the "--hardlink-scons" or
178         "--symlink-scons" options on the command line.
179
180     --  Install "scons-1.3.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
183         on the command line.
184
185         On UNIX or Linux systems, the "--install-bat" option may be
186         specified to have "scons-1.3.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.
190
191     --  Install the SCons build engine (a Python module) in an
192         appropriate version-numbered SCons library directory
193         (/usr/lib/scons-1.3.0 or C:\Python*\scons-1.3.0, for example).
194         See below for more options related to installing the build
195         engine library.
196
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.
203
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
208 follows:
209
210         # python setup.py install --standard-lib
211
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).
215
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:
220
221         # python setup.py install --standalone-lib
222
223 This is usually not recommended, however.
224
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:
230
231         $ python setup.py install --prefix=$HOME
232
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.
236
237
238 MAKING CHANGES
239 ==============
240
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.
243
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.
248
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:
252
253     $ python bootstrap.py [arguments]
254
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:
258
259     $ setenv MYSCONS=`pwd`/src
260     $ setenv SCONS_LIB_DIR=$MYSCONS/engine
261     $ python $MYSCONS/script/scons.py [arguments]
262
263 Or on Windows:
264
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]
268
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
273 that bug):
274
275     $ python bootstrap.py -C /some/other/location [arguments]
276
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:
280
281     $ chmod 755 src/script/scons.py
282     $ export PATH=$PATH:`pwd`/src/script
283
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.
286
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.
292
293
294 DEBUGGING
295 =========
296
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:
300
301     $ scons --debug=pdb [arguments]
302     > /home/knight/SCons/src/engine/SCons/Script/Main.py(927)_main()
303     -> default_warnings = [ SCons.Warnings.CorruptSConsignWarning,
304     (Pdb) 
305
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):
310
311     (Pdb) b SCons/Tool/msvc.py:158
312
313 The debugger also supports single stepping, stepping into functions,
314 printing variables, etc.
315
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.
321
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.
328
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:
332
333     def sample_method(self, value):
334         from SCons.Debug import Trace
335         Trace('called sample_method(%s, %s)\n' % (self, value))
336
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
339 the test automation.
340
341 The Trace() function can also redirect its output to a file, rather than
342 the screen:
343
344     def sample_method(self, value):
345         from SCons.Debug import Trace
346         Trace('called sample_method(%s, %s)\n' % (self, value),
347               file='trace.out')
348
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.
352
353
354 TESTING
355 =======
356
357 Tests are run by the runtest.py script in this directory.
358
359 There are two types of tests in this package:
360
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.
365
366     End-to-end tests of SCons live in the test/ subdirectory.
367
368 You may specifically list one or more tests to be run:
369
370         $ python runtest.py src/engine/SCons/BuilderTests.py
371
372         $ python runtest.py test/option-j.py test/Program.py
373
374 You also use the -f option to execute just the tests listed in a specified
375 text file:
376
377         $ cat testlist.txt
378         test/option-j.py
379         test/Program.py
380         $ python runtest.py -f testlist.txt
381
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).
386
387 The runtest.py script also takes a -a option that searches the tree for
388 all of the tests and runs them:
389
390         $ python runtest.py -a
391
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
394 unsuccessful tests.
395
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.
401
402
403 DEVELOPMENT WORKFLOW
404 ====================
405
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
413     good judgement.
414
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
419 be integrated.
420
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)):
425
426     --  Change to the top of your checked-out SCons tree and set
427         $SCONS_LIB_DIR to point to its build engine:
428
429             $ setenv SCONS_LIB_DIR=`pwd`/src
430
431     --  Confirm that the bug still exists in this version of SCons
432         by using the -C option to run the broken build:
433
434             $ python script/scons.py -C /home/me/broken_project .
435
436     --  Fix the bug in SCons by editing appropriate module files
437         underneath src/engine/SCons.
438
439     --  Confirm that you've fixed the bug affecting your project:
440
441             $ python script/scons.py -C /home/me/broken_project .
442
443     --  Test to see if your fix had any unintended side effects
444         that break existing functionality:
445
446             $ python runtest.py -a
447
448         Be patient, there are more than 700 test scripts in the
449         whole suite.
450
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.
456
457     --  Cut-and-paste the list of failed tests into a file:
458
459             $ cat > failed.txt
460             test/failed-test-1.py
461             test/failed-test-2.py
462             test/failed-test-3.py
463             ^D
464             $
465
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
472         failed:
473
474             $ [edit]
475             $ python runtest.py -f failed.txt
476
477         Repeat this until all of the tests that originally failed
478         now pass.
479
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:
484
485             $ python script/scons.py -C /home/me/broken_project .
486             $ python runtest.py -a
487
488         If you find any newly-broken tests, add them to your "failed.txt"
489         file and go back to the previous step.
490
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".
496
497
498 BUILDING PACKAGES
499 =================
500
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:
504
505         $ scons
506
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:
509
510         $ python bootstrap.py build/scons
511
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.
515
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):
518
519         $ export SCONS_LIB_DIR=`pwd`/src/engine
520         $ python src/script/scons.py
521
522 On Windows:
523         
524         C:\scons\>set SCONS_LIB_DIR=%cd%\src\engine
525         C:\scons\>python src/script/scons.py
526
527 Depending on the utilities installed on your system, any or all of the
528 following packages will be built:
529
530         build/dist/scons-1.3.0-1.noarch.rpm
531         build/dist/scons-1.3.0-1.src.rpm
532         build/dist/scons-1.3.0.linux-i686.tar.gz
533         build/dist/scons-1.3.0.tar.gz
534         build/dist/scons-1.3.0.win32.exe
535         build/dist/scons-1.3.0.zip
536         build/dist/scons-doc-1.3.0.tar.gz
537         build/dist/scons-local-1.3.0.tar.gz
538         build/dist/scons-local-1.3.0.zip
539         build/dist/scons-src-1.3.0.tar.gz
540         build/dist/scons-src-1.3.0.zip
541         build/dist/scons_1.3.0-1_all.deb
542
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.
547
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.
550
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.
553
554
555 TESTING PACKAGES
556 ================
557
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:
565
566         $ python runtest.py -p deb
567
568         $ python runtest.py -p rpm
569
570         $ python runtest.py -p local-tar-gz
571
572         $ python runtest.py -p local-zip
573
574         $ python runtest.py -p src-tar-gz
575
576         $ python runtest.py -p src-zip
577
578         $ python runtest.py -p tar-gz
579
580         $ python runtest.py -p zip
581
582 (The canonical invocation is to also use the runtest.py -a option so
583 that all tests are run against the specified package.)
584
585
586 CONTENTS OF THIS PACKAGE
587 ========================
588
589 Not guaranteed to be up-to-date (but better than nothing):
590
591 bench/
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
596         the future.
597
598 bin/
599         Miscellaneous utilities used in SCons development.  Right now,
600         some of the stuff here includes:
601
602             --  a copy of the script we use to translate an Aegis change
603                 into a CVS checkin
604             --  a script that runs pychecker on our source tree
605             --  a script that counts source and test files and numbers
606                 of lines in each
607             --  a script for synchronizing the Aegis tree to SourceForge
608             --  a prototype script for capturing sample SCons output
609                 in xml files
610             --  a script that can profile and time a packaging build of
611                 SCons itself
612             --  a copy of xml_export, which can retrieve project data
613                 from SourceForge
614             --  scripts and a Python module for translating the SCons
615                 home-brew XML documentation tags into DocBook and
616                 man page format
617
618 bootstrap.py
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.
623
624 build/
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.
628
629 config
630         The Aegis configuration, governing much of how we use Aegis to
631         build, test, control source, etc.
632
633 debian/
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.
639
640 doc/
641         SCons documentation.  A variety of things here, in various
642         stages of (in)completeness.
643
644 gentoo/
645         Stuff to generate files for Gentoo Linux.
646
647 HOWTO/
648         Documentation of SCons administrative procedures (making a
649         change, releasing a new version).  Maybe other administrative
650         stuff in the future.
651
652 LICENSE
653         A copy of the copyright and terms under which SCons is
654         distributed (the Open Source Initiative-approved MIT license).
655
656 LICENSE-local
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.
662
663 QMTest/
664         The Python modules we use for testing, some generic modules
665         originating elsewhere and some specific to SCons.
666
667 README
668         What you're looking at right now.
669
670 README-local
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.
674
675 rpm/
676         The .spec file for building our RPM packages.
677
678 runtest.py
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.
684
685 SConstruct
686         The "Makefile" for the SCons distribution.
687
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"
695         software.)
696
697 src/
698         Where the actual source code is kept, of course.
699
700 template/
701         Template files, used by Aegis to give you a head start when you
702         aenf or aent a new file.
703
704 test/
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/.
708
709
710 DOCUMENTATION
711 =============
712
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.
716
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.
719
720 Additional documentation for SCons is available at:
721
722         http://www.scons.org/doc.html
723
724
725 LICENSING
726 =========
727
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:
731
732         This software is OSI Certified Open Source Software.  OSI
733         Certified is a certification mark of the Open Source Initiative.
734
735 More information about OSI certifications and Open Source software is
736 available at:
737
738         http://www.opensource.org/
739
740
741 REPORTING BUGS
742 ==============
743
744 Please report bugs by following the detailed instructions on our Bug
745 Submission page:
746
747         http://scons.tigris.org/bug-submission.html
748
749 You can also send mail to the SCons developers' mailing list:
750
751         dev@scons.tigris.org
752
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.
756
757
758 MAILING LISTS
759 =============
760
761 An active mailing list for developers of SCons is available.  You may
762 send questions or comments to the list at:
763
764         dev@scons.tigris.org
765
766 You may request a subscription to the developer's mailing list by sending
767 email to:
768
769         dev-subscribe@scons.tigris.org
770
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.
774
775 There is also a low-volume mailing list available for announcements
776 about SCons.  Subscribe by sending email to:
777
778         announce-subscribe@scons.tigris.org
779
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.
783
784
785 DONATIONS
786 =========
787
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:
791
792         http://www.scons.org/donate.html
793
794
795 FOR MORE INFORMATION
796 ====================
797
798 Check the SCons web site at:
799
800         http://www.scons.org/
801
802
803 AUTHOR INFO
804 ===========
805
806 Steven Knight
807 knight at baldmt dot com
808 http://www.baldmt.com/~knight/
809
810 With plenty of help from the SCons Development team:
811         Chad Austin
812         Charles Crain
813         Bill Deegan
814         Steve Leblanc
815         Greg Noel
816         Gary Oberbrunner
817         Anthony Roach
818         Greg Spencer
819         Christoph Wiedemann
820