README

   1 # __COPYRIGHT__
   2
   3                  SCons - a software construction tool
   4
   5 Welcome to the SCons development tree.  The real purpose of this tree is
   6 to package SCons for production distribution in a variety of formats,
   7 not just to hack SCons code.
   8
   9 To that extent, the normal development cycle (enforced by Aegis) is not
  10 to test the code directly, but to package SCons, unpack the package,
  11 "install" SCons in a test subdirectory, and then to run the tests
  12 against the unpacked and installed software.  This helps eliminate
  13 problems caused by, for example, failure to update the list of files to
  14 be packaged.
  15
  16 Note that if all you want to do is install and run SCons, it
  17 will probably be easier for you to download and install the
  18 scons-{version}.tar.gz or scons-{version}.zip package rather than to
  19 work with the packaging logic in this tree.
  20
  21
  22 LATEST VERSION
  23 ==============
  24
  25 Before going further, you can check that this package you have is the
  26 latest version at the SCons download page:
  27
  28         http://www.scons.org/download.html
  29
  30
  31 EXECUTION REQUIREMENTS
  32 ======================
  33
  34 Running SCons requires Python version 1.5.2 or later.  There should be
  35 no other dependencies or requirements to run SCons.
  36
  37 The default SCons configuration assumes use of the Microsoft Visual C++
  38 compiler suite on WIN32 systems, and assumes a C compiler named 'cc',
  39 a C++ compiler named 'c++', and a Fortran compiler named 'g77' (such
  40 as found in the GNU C compiler suite) on any other type of system.
  41 You may, of course, override these default values by appropriate
  42 configuration of Environment construction variables.
  43
  44 By default, SCons knows how to search for available programming tools
  45 on various systems--see the SCons man page for details.  You may,
  46 of course, override the default SCons choices made by appropriate
  47 configuration of Environment construction variables.
  48
  49
  50 INSTALLATION REQUIREMENTS
  51 =========================
  52
  53 Building and installing SCons from this package requires the Python
  54 distutils package.  The distutils package was not shipped as a standard
  55 part of Python until Python version 1.6, so if your system is running
  56 Python 1.5.2, you may not have distutils installed.  If you are running
  57 Python version 1.6 or later, you should be fine.
  58
  59 NOTE TO RED HAT USERS:  All Red Hat Linux versions up to 7.3 still ship
  60 Python 1.5.2 as the default, so you probably do *not* have distutils
  61 installed, unless you have already done so manually or are running Red
  62 Hat 8.0 or later.
  63
  64 In this case, your options are:
  65
  66     --  (Optional.)  Install from a pre-packaged SCons package that
  67         does not require distutils:
  68
  69             Red Hat Linux       scons-0.12-1.noarch.rpm
  70
  71             Debian GNU/Linux    scons_0.12-1_all.deb
  72                                 (or use apt-get)
  73
  74             Windows             scons-0.12.win32.exe
  75
  76     --  (Recommended.)  Download the latest distutils package from the
  77         following URL:
  78
  79             http://www.python.org/sigs/distutils-sig/download.html
  80
  81         Install the distutils according to the instructions on the page.
  82         You can then proceed to the next section to install SCons from
  83         this package.
  84
  85
  86 INSTALLATION
  87 ============
  88
  89 Assuming your system satisfies the installation requirements in
  90 the previous section, install SCons from this package by first
  91 populating the build/scons/ directory.  (For an easier way to
  92 install SCons, without having to populate this directory, use the
  93 scons-{version}.tar.gz or scons-{version}.zip package.)
  94
  95 If you already have an appropriate version of SCons installed on your
  96 system, populate the build/scons/ directory by running:
  97
  98         $ scons build/scons
  99
 100 If you don't have SCons version 0.11 or later already installed on your
 101 system, you can use SCons itself to populate the build/scons/ directory
 102 with a little more typing:
 103
 104         $ SCONS_LIB_DIR=`pwd`/src/engine python src/script/scons.py build/scons
 105
 106 Either command will populate the build/scons/ directory with the
 107 necessary files and directory structure to use the Python-standard setup
 108 script as follows:
 109
 110         # cd build/scons
 111         # python setup.py install
 112
 113 If this is the first time you are installing SCons on your system,
 114 the above command will install the scons script in the default system
 115 script directory (/usr/bin or C:\Python*\Scripts, for example) and the
 116 build engine in an appropriate stand-alone SCons library directory
 117 (/usr/lib/scons or C:\Python*\scons, for example).
 118
 119 Note that, by default, SCons does not install its library in the
 120 standard Python library directories.  If you want to be able to use the
 121 SCons library modules (the build engine) in other Python scripts, you
 122 can run the setup script as follows:
 123
 124         # cd build/scons
 125         # python setup.py install --standard-lib
 126
 127 This will install the build engine in the standard Python
 128 library directory (/usr/lib/python*/site-packages or
 129 C:\Python*\Lib\site-packages).
 130
 131 Alternatively, you may want to install multiple versions of SCons
 132 side-by-side, which you can do as follows:
 133
 134         # cd build/scons
 135         # python setup.py install --version-lib
 136
 137 This will install the build engine in a version-specific library
 138 directory (/usr/lib/scons-__VERSION__ or C:\Python*\scons-__VERSION__).
 139
 140 If this is not the first time you are installing SCons on your system,
 141 the setup script will, by default, search for where you have previously
 142 installed the SCons library, and install this version's library the
 143 same way--that is, if you previously installed the SCons library in
 144 the standard Python library, the setup script will install this one
 145 in the same location.  You may, of course, specify one of the --*-lib
 146 options described above to select a specific library location, or use
 147 the following option to explicitly select installation into the default
 148 standalone library directory (/usr/lib/scons or C:\Python*\scons):
 149
 150         # cd build/scons
 151         # python setup.py install --standalone-lib
 152
 153 Note that, to install SCons in any of the above system directories,
 154 you should have system installation privileges (that is, "root" or
 155 "Administrator") when running the setup.py script.  If you don't have
 156 system installation privileges, you can use the --prefix option to
 157 specify an alternate installation location, such as your home directory:
 158
 159         $ cd build/scons
 160         $ python setup.py install --prefix=$HOME
 161
 162 This will install SCons in the appropriate locations relative to
 163 $HOME--that is, the scons script itself $HOME/bin and the associated
 164 library in $HOME/lib/scons, for example.
 165
 166
 167 TESTING
 168 =======
 169
 170 Tests are run by the runtest.py script in this directory.
 171
 172 There are two types of tests in this package:
 173
 174     Unit tests for individual SCons modules live underneath the
 175     src/engine/ subdirectory and are the same base name as the module
 176     with "Tests.py" appended--for example, the unit test for the
 177     Builder.py module is the BuilderTests.py script.
 178
 179     End-to-end tests of SCons live in the test/ subdirectory.
 180
 181 You may specifically list one or more tests to be run:
 182
 183         $ python runtest.py src/engine/SCons/BuilderTests.py
 184
 185         $ python runtest.py test/option-j.py test/Program.py
 186
 187 Alternatively, the runtest.py script takes a -a option that searches
 188 the tree for all of the tests and runs them:
 189
 190         $ python runtest.py -a
 191
 192 If more than one test is run, the runtest.py script prints a summary
 193 of how many tests passed, failed, or yielded no result, and lists any
 194 unsuccessful tests.
 195
 196 The above invocations all test directly the files underneath the src/
 197 subdirectory, and do not require that a build be performed first.  The
 198 runtest.py script supports additional options to run tests against
 199 unpacked packages in the build/test-*/ subdirectories.  See the "TESTING
 200 PACKAGES" section below.
 201
 202
 203 BUILDING PACKAGES
 204 =================
 205
 206 We now use SCons (version 0.11 or later) to build its own packages.
 207 If you already have an appropriate version of SCons installed on your
 208 system, you can build everything by simply running it:
 209
 210         $ scons
 211
 212 If you don't have SCons version 0.11 or later already installed on your
 213 system, you can build this version of SCons with itself with a little
 214 more typing:
 215
 216         $ SCONS_LIB_DIR=`pwd`/src/engine python src/script/scons.py
 217
 218 Depending on the utilities installed on your system, any or all of the
 219 following packages will be built:
 220
 221         build/dist/scons-0.12-1.noarch.rpm
 222         build/dist/scons-0.12-1.src.rpm
 223         build/dist/scons-0.12.linux-i686.tar.gz
 224         build/dist/scons-0.12.tar.gz
 225         build/dist/scons-0.12.win32.exe
 226         build/dist/scons-0.12.zip
 227         build/dist/scons-doc-0.12.tar.gz
 228         build/dist/scons-local-0.12.tar.gz
 229         build/dist/scons-local-0.12.zip
 230         build/dist/scons-src-0.12.tar.gz
 231         build/dist/scons-src-0.12.zip
 232         build/dist/scons_0.12-1_all.deb
 233
 234 The SConstruct file is supposed to be smart enough to avoid trying to
 235 build packages for which you don't have the proper utilities installed.
 236 For example, if you don't have Debian packaging tools installed, it
 237 should just not build the .deb package, not fail the build.
 238
 239 If you receive a build error, please report it to the scons-devel
 240 mailing list and open a bug report on the SCons bug tracker.
 241
 242 Note that in addition to creating the above packages, the default build
 243 will also unpack one or more of the packages for testing.
 244
 245
 246 TESTING PACKAGES
 247 ================
 248
 249 A full build will unpack and/or install any .deb, .rpm., .local.tar.gz,
 250 .local.zip, .src.tar.gz, .src.zip, .tar.gz, and .zip packages into
 251 separate build/test-*/ subdirectories.  (Of course, if a package was
 252 not built on your system, it should not try to install it.)  The
 253 runtest.py script supports a -p option that will run the specified tests
 254 (individually or collectively via the -a option) against the unpacked
 255 build/test-/* subdirectory:
 256
 257         $ python runtest.py -p deb
 258
 259         $ python runtest.py -p rpm
 260
 261         $ python runtest.py -p local-tar-gz
 262
 263         $ python runtest.py -p local-zip
 264
 265         $ python runtest.py -p src-tar-gz
 266
 267         $ python runtest.py -p src-zip
 268
 269         $ python runtest.py -p tar-gz
 270
 271         $ python runtest.py -p zip
 272
 273 (The canonical invocation is to also use the runtest.py -a option so
 274 that all tests are run against the specified package.)
 275
 276
 277 CONTENTS OF THIS PACKAGE
 278 ========================
 279
 280 Not guaranteed to be up-to-date (but better than nothing):
 281
 282 bin/
 283         Miscellaneous utilities used in SCons development.  Right now,
 284         there's a copy of the script we use to translate an Aegis change
 285         into a CVS checkin.
 286
 287 bootstrap.py
 288         A build script for use with Aegis.  This collects a current copy
 289         of SCons from the Aegis baseline directories in a bootstrap/
 290         subdirectory, and then executes SCons with the supplied
 291         command-line arguments.
 292
 293 build/
 294         This doesn't exist yet if you're looking at a vanilla source
 295         tree.  This is generated as part of our build process, and it's
 296         where, believe it or not, we *build* everything.
 297
 298 config
 299         The Aegis configuration, governing much of how we use Aegis to
 300         build, test, control source, etc.
 301
 302 debian/
 303         Files needed to construct a Debian package. The contents of this
 304         directory are dictated by the Debian Policy Manual
 305         (http://www.debian.org/doc/debian-policy). The package will not be
 306         accepted into the Debian distribution unless the contents of this
 307         directory satisfy the relevant Debian policies.
 308
 309 doc/
 310         SCons documentation.  A variety of things here, in various
 311         stages of (in)completeness.
 312
 313 etc/
 314         A subdirectory for miscellaneous things that we need.  Right
 315         now, it has copies of Python modules that we use for testing,
 316         and which we don't want to force people to have to install on
 317         their own just to help out with SCons development.
 318
 319 HOWTO/
 320         Documentation of SCons administrative procedures (making a
 321         change, releasing a new version).  Maybe other administrative
 322         stuff in the future.
 323
 324 LICENSE
 325         A copy of the copyright and terms under which SCons is
 326         distributed (the Open Source Initiative-approved MIT license).
 327
 328 LICENSE-local
 329         A copy of the copyright and terms under which SCons is
 330         distributed for inclusion in the scons-local-{version} packages.
 331         This is the same as LICENSE with a preamble that specifies
 332         the licensing terms are for SCons itself, not any other
 333         package that includes SCons.
 334
 335 README
 336         What you're looking at right now.
 337
 338 README-local
 339         A README file for inclusion in the scons-local-{version}
 340         packages.  Similar to this file, but stripped down and modified
 341         for people looking at including SCons in their shipped software.
 342
 343 rpm/
 344         The .spec file for building our RPM packages.
 345
 346 runtest.py
 347         Script for running SCons tests.  By default, this will run a
 348         test against the code in the local src/ tree, so you don't
 349         have to do a build before testing your changes.  Aegis uses
 350         it with an option that requires that you've done a build
 351         (aeb) before running tests.
 352
 353 SConstruct
 354         The "Makefile" for the SCons distribution.
 355
 356         (It has been pointed out that it's hard to find the SCons API
 357         in this SConstruct file, and that it looks a lot more like a
 358         pure Python script than a build configuration file.  That's
 359         mainly because all of the magick we have to perform to deal with
 360         all of the different packaging formats requires a lot of pure
 361         Python manipulation.  In other words, don't look at this file
 362         for an example of how easy it is to use SCons to build "normal"
 363         software.)
 364
 365 src/
 366         Where the actual source code is kept, of course.
 367
 368 template/
 369         Template files, used by Aegis to give you a head start when you
 370         aenf or aent a new file.
 371
 372 test/
 373         End-to-end tests of the SCons utility itself.  These are
 374         separate from the individual module unit tests, which live
 375         side-by-side with the modules under src/.
 376
 377
 378 DOCUMENTATION
 379 =============
 380
 381 See the src/RELEASE.txt file for notes about this specific release,
 382 including known problems.  See the src/CHANGES.txt file for a list of
 383 changes since the previous release.
 384
 385 The doc/man/scons.1 man page is included in this package, and contains a
 386 section of small examples for getting started using SCons.
 387
 388 Additional documentation for SCons is available at:
 389
 390         http://www.scons.org/doc.html
 391
 392
 393 LICENSING
 394 =========
 395
 396 SCons is distributed under the MIT license, a full copy of which is
 397 available in the LICENSE file. The MIT license is an approved Open
 398 Source license, which means:
 399
 400         This software is OSI Certified Open Source Software.  OSI
 401         Certified is a certification mark of the Open Source Initiative.
 402
 403 More information about OSI certifications and Open Source software is
 404 available at:
 405
 406         http://www.opensource.org/
 407
 408
 409 REPORTING BUGS
 410 ==============
 411
 412 You can report bugs either by following the "Tracker - Bugs" link
 413 on the SCons project page:
 414
 415         http://sourceforge.net/projects/scons/
 416
 417 or by sending mail to the SCons developers mailing list:
 418
 419         scons-devel@lists.sourceforge.net
 420
 421
 422 MAILING LISTS
 423 =============
 424
 425 A mailing list for developers of SCons is available.  You may send
 426 questions or comments to the list at:
 427
 428         scons-devel@lists.sourceforge.net
 429
 430 You may request a subscription to the scons-devel mailing list at:
 431
 432         http://lists.sourceforge.net/lists/listinfo/scons-devel
 433
 434 Subscription to the list is by approval.  In practice, no one is being
 435 refused list membership right now, but we reserve the right to limit
 436 membership in the future and/or weed out lurkers.
 437
 438
 439 FOR MORE INFORMATION
 440 ====================
 441
 442 Check the SCons web site at:
 443
 444         http://www.scons.org/
 445
 446
 447 AUTHOR INFO
 448 ===========
 449
 450 Steven Knight
 451 knight at baldmt dot com
 452 http://www.baldmt.com/~knight/
 453
 454 With plenty of help from the SCons Development team:
 455         Chad Austin
 456         Charles Crain
 457         Steve Leblanc
 458         Anthony Roach
 459         Terrel Shumway
 460