README

   1 # Copyright (c) 2001, 2002 Steven Knight
   2
   3                  SCons - a software construction tool
   4
   5 Welcome to the SCons development tree.  The purpose of this tree is
   6 not just to hack SCons code, but to package SCons for production
   7 distribution.
   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 package rather than to work with the packaging
  19 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 REQUIREMENTS
  32 ============
  33
  34 SCons requires Python version 1.5.2 or later.  There should be no
  35 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 and a C++ compiler named 'c++' (such as found in the GNU C compiler
  40 suite) on any other type of system.  You may, of course, override these
  41 default values by appropriate configuration of Environment construction
  42 variables.
  43
  44
  45 INSTALLATION
  46 ============
  47
  48 To install SCons from this package, you must first populate the
  49 build/scons/ directory.  (For an easier way to install SCons, without
  50 having to populate this directory, use the scons-{version}.tar.gz
  51 package.)
  52
  53 If you already have an appropriate version of SCons installed on your
  54 system, populate the build/scons/ directory by running:
  55
  56         $ scons build/scons
  57
  58 If you don't have SCons version 0.04 or later already installed on your
  59 system, you can use SCons itself to populate the build/scons/ directory
  60 with a little more work:
  61
  62         $ SCONS_LIB_DIR=`pwd`/src/engine python src/script/scons.py build/scons
  63
  64 Either command populates the build/scons/ directory with the necessary
  65 files and directory structure to use the Python-standard setup script as
  66 follows:
  67
  68         # cd build/scons
  69         # python setup.py install
  70
  71 This will install the scons script in the default system script
  72 directory (/usr/bin or C:\Python*\Scripts, for example) and the build
  73 engine in an appropriate SCons library directory (/usr/lib/scons or
  74 C:\Python*\SCons, for example).
  75
  76 You should have system installation privileges (that is, "root" or
  77 "Administrator") when running the setup.py script to install SCons in
  78 the default system directories.
  79
  80 If you don't have system installation privileges, you can use the
  81 --prefix option to specify an alternate installation location, such as
  82 your home directory:
  83
  84         $ cd build/scons
  85         $ python setup.py install --prefix=$HOME
  86
  87 This will install the scons script itself in $HOME/bin and the
  88 associated library in $HOME/lib/scons
  89
  90
  91 TESTING
  92 =======
  93
  94 Tests are run by the runtest.py script in this directory.
  95
  96 There are two types of tests in this package.  Unit tests for individual
  97 SCons modules live underneath the src/engine/ subdirectory and are the
  98 same base name as the module with "Tests.py" appended--for example,
  99 the unit test for the Builder.py module is the BuilderTests.py script.
 100 End-to-end tests of SCons live in the test/ subdirectory.
 101
 102 You may specifically list one or more tests to be run:
 103
 104         $ python runtest.py src/engine/SCons/BuilderTests.py
 105
 106         $ python runtest.py test/option-j.py test/Program.py
 107
 108 Alternatively, the runtest.py script takes a -a option that searches
 109 the tree for all of the tests and runs them:
 110
 111         $ python runtest.py -a
 112
 113 If more than one test is run, the runtest.py script prints a summary
 114 of how many tests passed, failed, or yielded no result, and lists any
 115 unsuccessful tests.
 116
 117 The above invocations all test directly the files underneath the src/
 118 subdirectory, and do not require that a build be performed first.  The
 119 runtest.py script supports supports additional options to run tests
 120 against unpacked packages in the build/test-*/ subdirectories.  See
 121 the "TESTING PACKAGES" section below.
 122
 123
 124 BUILDING PACKAGES
 125 =================
 126
 127 We now use SCons (version 0.04 or later) to build its own packages.
 128 If you already have an appropriate version of SCons installed on your
 129 system, you can build everything by simply running it:
 130
 131         $ scons
 132
 133 If you don't have SCons version 0.04 or later already installed on your
 134 system, you can build this version of SCons with itself with a little
 135 more work:
 136
 137         $ SCONS_LIB_DIR=`pwd`/src/engine python src/script/scons.py
 138
 139 Depending on the utilities installed on your system, any or all of the
 140 following packages will be built:
 141
 142         build/dist/scons-0.04-1.noarch.rpm
 143         build/dist/scons-0.04-1.src.rpm
 144         build/dist/scons-0.04.linux-i686.tar.gz
 145         build/dist/scons-0.04.tar.gz
 146         build/dist/scons-0.04.win32.exe
 147         build/dist/scons-doc-0.04.tar.gz
 148         build/dist/scons-src-0.04.tar.gz
 149         build/dist/scons_0.04-1_all.deb
 150
 151 The SConstruct file is supposed to be smart enough to avoid trying to
 152 build packages for which you don't have the proper utilities installed.
 153 For example, if you don't have Debian packaging tools installed, it
 154 should just not build the .deb package, not fail the build.
 155
 156 If you receive a build error, please report it to the scons-devel
 157 mailing list.
 158
 159 Note that in addition to creating the above packages, the default build
 160 will also unpack one or more of the packages for testing.
 161
 162
 163 TESTING PACKAGES
 164 ================
 165
 166 A full build will unpack and/or install any .deb, .rpm., .src.tar.gz,
 167 and .tar.gz packages into separate build/test-*/ subdirectories.  (Of
 168 course, if a package was not built on your system, it should not try to
 169 install it.)  The runtest.py script supports a -p option that will run
 170 the specified tests (individually or collectively via the -a option)
 171 against the unpacked build/test-/* subdirectory:
 172
 173         $ python runtest.py -p tar-gz
 174
 175         $ python runtest.py -p src-tar-gz
 176
 177         $ python runtest.py -p rpm
 178
 179         $ python runtest.py -p deb
 180
 181
 182 CONTENTS OF THIS PACKAGE
 183 ========================
 184
 185 Not guaranteed to be up-to-date (but better than nothing):
 186
 187 bin/
 188         Miscellaneous utilities used in SCons development.  Right now,
 189         there's a copy of the script we use to translate an Aegis change
 190         into a CVS checkin.
 191
 192 build/
 193         This doesn't exist yet if you're looking at a vanilla source
 194         tree.  This is generated as part of our build process, and it's
 195         where, believe it or not, we *build* everything.
 196
 197 Construct
 198         The old "Makefile" Cons-based for the SCons distribution.  This
 199         is obsolete as of version 0.04, but it's being left around for a
 200         little while, just in case...
 201
 202 config
 203         The Aegis configuration, governing much of how we use Aegis to
 204         build, test, control source, etc.
 205
 206 debian/
 207         Files needed to construct a Debian package. The contents of this
 208         directory are dictated by the Debian Policy Manual
 209         (http://www.debian.org/doc/debian-policy). The package will not be
 210         accepted into the Debian distribution unless the contents of this
 211         directory satisfy the relevant Debian policies.
 212
 213 doc/
 214         SCons documentation.  A variety of things here, in various
 215         stages of (in)completeness.
 216
 217 etc/
 218         A subdirectory for miscellaneous things that we need.  Right
 219         now, it has copies of Python modules that we use for testing,
 220         and which we don't want to force people to have to install on
 221         their own just to help out with SCons development.
 222
 223 HOWTO/
 224         Documentation of SCons administrative procedures (making a
 225         change, releasing a new version).  Maybe other administrative
 226         stuff in the future.
 227
 228 README
 229         What you're looking at right now.
 230
 231 rpm/
 232         The .spec file for building our RPM packages.
 233
 234 runtest.py
 235         Script for running our tests.  By default, this will run a
 236         test against the code in the local src/ tree, so you don't
 237         have to do a build before testing your changes.  Aegis uses
 238         it with an option that requires that you've done a build
 239         (aeb) before running tests.
 240
 241 SConstruct
 242         The "Makefile" for the SCons distribution.
 243
 244 src/
 245         Where the actual source code is kept, of course.
 246
 247 template/
 248         Template files, used by Aegis to give you a head start when you
 249         aenf or aent a new file.
 250
 251 test/
 252         End-to-end tests of the SCons utility itself.  These are
 253         separate from the individual module unit tests, which live
 254         side-by-side with the modules under src/.
 255
 256
 257 DOCUMENTATION
 258 =============
 259
 260 See the src/RELEASE.txt file for notes about this specific release,
 261 including known problems.  See the src/CHANGES.txt file for a list of
 262 changes since the previous release.
 263
 264 The doc/man/scons.1 man page is included in this package, and contains a
 265 section of small examples for getting started using SCons.
 266
 267 Additional documentation for SCons is available at:
 268
 269         http://www.scons.org/doc.html
 270
 271
 272 LICENSING
 273 =========
 274
 275 SCons is distributed under the MIT license, a full copy of which is
 276 available in the LICENSE.txt file. The MIT license is an approved Open
 277 Source license, which means:
 278
 279         This software is OSI Certified Open Source Software.  OSI
 280         Certified is a certification mark of the Open Source Initiative.
 281
 282 More information about OSI certifications and Open Source software is
 283 available at:
 284
 285         http://www.opensource.org/
 286
 287
 288 REPORTING BUGS
 289 ==============
 290
 291 You can report bugs either by following the "Tracker - Bugs" link
 292 on the SCons project page:
 293
 294         http://sourceforge.net/projects/scons/
 295
 296 or by sending mail to the SCons developers mailing list:
 297
 298         scons-devel@lists.sourceforge.net
 299
 300
 301 MAILING LISTS
 302 =============
 303
 304 A mailing list for developers of SCons is available.  You may send
 305 questions or comments to the list at:
 306
 307         scons-devel@lists.sourceforge.net
 308
 309 You may request a subscription to the scons-devel mailing list at:
 310
 311         http://lists.sourceforge.net/lists/listinfo/scons-devel
 312
 313 Subscription to the list is by approval.  In practice, no one is being
 314 refused list membership right now, but we reserve the right to limit
 315 membership in the future and/or weed out lurkers.
 316
 317
 318 FOR MORE INFORMATION
 319 ====================
 320
 321 Check the SCons web site at:
 322
 323         http://www.scons.org/
 324
 325
 326 AUTHOR INFO
 327 ===========
 328
 329 Steven Knight
 330 knight at baldmt dot com
 331 http://www.baldmt.com/~knight/
 332
 333 With more than a little help from the SCons Development team:
 334         Chad Austin
 335         Charles Crain
 336         Steve Leblanc
 337         Anthony Roach
 338