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.  This is
 121 in the process of being reworked for the next release, however, so for
 122 now, see the comments in the runtest.py script itself if you want to run
 123 tests against a package.
 124
 125
 126 BUILDING PACKAGES
 127 =================
 128
 129 We now use SCons (version 0.04 or later) to build its own packages.
 130 If you already have an appropriate version of SCons installed on your
 131 system, you can build everything by simply running it:
 132
 133         $ scons
 134
 135 If you don't have SCons version 0.04 or later already installed on your
 136 system, you can build this version of SCons with itself with a little
 137 more work:
 138
 139         $ SCONS_LIB_DIR=`pwd`/src/engine python src/script/scons.py
 140
 141 Depending on the utilities installed on your system, any or all of the
 142 following packages will be built:
 143
 144         build/dist/scons-0.04-1.noarch.rpm
 145         build/dist/scons-0.04-1.src.rpm
 146         build/dist/scons-0.04.linux-i686.tar.gz
 147         build/dist/scons-0.04.tar.gz
 148         build/dist/scons-0.04.win32.exe
 149         build/dist/scons-doc-0.04.tar.gz
 150         build/dist/scons-src-0.04.tar.gz
 151         build/dist/scons_0.04-1_all.deb
 152
 153 The SConstruct file is supposed to be smart enough to avoid trying to
 154 build packages for which you don't have the proper utilities installed.
 155 For example, if you don't have Debian packaging tools installed, it
 156 should just not build the .deb package, not fail the build.
 157
 158 If you receive a build error, please report it to the scons-devel
 159 mailing list.
 160
 161 Note that in addition to creating the above packages, the default build
 162 will also unpack one or more of the packages for testing.
 163
 164
 165 CONTENTS OF THIS PACKAGE
 166 ========================
 167
 168 Not guaranteed to be up-to-date (but better than nothing):
 169
 170 bin/
 171         Miscellaneous utilities used in SCons development.  Right now,
 172         there's a copy of the script we use to translate an Aegis change
 173         into a CVS checkin.
 174
 175 build/
 176         This doesn't exist yet if you're looking at a vanilla source
 177         tree.  This is generated as part of our build process, and it's
 178         where, believe it or not, we *build* everything.
 179
 180 Construct
 181         The old "Makefile" Cons-based for the SCons distribution.  This
 182         is obsolete as of version 0.04, but it's being left around for a
 183         little while, just in case...
 184
 185 config
 186         The Aegis configuration, governing much of how we use Aegis to
 187         build, test, control source, etc.
 188
 189 debian/
 190         Files needed to construct a Debian package. The contents of this
 191         directory are dictated by the Debian Policy Manual
 192         (http://www.debian.org/doc/debian-policy). The package will not be
 193         accepted into the Debian distribution unless the contents of this
 194         directory satisfy the relevant Debian policies.
 195
 196 doc/
 197         SCons documentation.  A variety of things here, in various
 198         stages of (in)completeness.
 199
 200 etc/
 201         A subdirectory for miscellaneous things that we need.  Right
 202         now, it has copies of Python modules that we use for testing,
 203         and which we don't want to force people to have to install on
 204         their own just to help out with SCons development.
 205
 206 HOWTO/
 207         Documentation of SCons administrative procedures (making a
 208         change, releasing a new version).  Maybe other administrative
 209         stuff in the future.
 210
 211 README
 212         What you're looking at right now.
 213
 214 rpm/
 215         The .spec file for building our RPM packages.
 216
 217 runtest.py
 218         Script for running our tests.  By default, this will run a
 219         test against the code in the local src/ tree, so you don't
 220         have to do a build before testing your changes.  Aegis uses
 221         it with an option that requires that you've done a build
 222         (aeb) before running tests.
 223
 224 SConstruct
 225         The "Makefile" for the SCons distribution.
 226
 227 src/
 228         Where the actual source code is kept, of course.
 229
 230 template/
 231         Template files, used by Aegis to give you a head start when you
 232         aenf or aent a new file.
 233
 234 test/
 235         End-to-end tests of the SCons utility itself.  These are
 236         separate from the individual module unit tests, which live
 237         side-by-side with the modules under src/.
 238
 239
 240 DOCUMENTATION
 241 =============
 242
 243 See the src/RELEASE.txt file for notes about this specific release,
 244 including known problems.  See the src/CHANGES.txt file for a list of
 245 changes since the previous release.
 246
 247 The doc/man/scons.1 man page is included in this package, and contains a
 248 section of small examples for getting started using SCons.
 249
 250 Additional documentation for SCons is available at:
 251
 252         http://www.scons.org/doc.html
 253
 254
 255 LICENSING
 256 =========
 257
 258 SCons is distributed under the MIT license, a full copy of which is
 259 available in the LICENSE.txt file. The MIT license is an approved Open
 260 Source license, which means:
 261
 262         This software is OSI Certified Open Source Software.  OSI
 263         Certified is a certification mark of the Open Source Initiative.
 264
 265 More information about OSI certifications and Open Source software is
 266 available at:
 267
 268         http://www.opensource.org/
 269
 270
 271 REPORTING BUGS
 272 ==============
 273
 274 You can report bugs either by following the "Tracker - Bugs" link
 275 on the SCons project page:
 276
 277         http://sourceforge.net/projects/scons/
 278
 279 or by sending mail to the SCons developers mailing list:
 280
 281         scons-devel@lists.sourceforge.net
 282
 283
 284 MAILING LISTS
 285 =============
 286
 287 A mailing list for developers of SCons is available.  You may send
 288 questions or comments to the list at:
 289
 290         scons-devel@lists.sourceforge.net
 291
 292 You may request a subscription to the scons-devel mailing list at:
 293
 294         http://lists.sourceforge.net/lists/listinfo/scons-devel
 295
 296 Subscription to the list is by approval.  In practice, no one is being
 297 refused list membership right now, but we reserve the right to limit
 298 membership in the future and/or weed out lurkers.
 299
 300
 301 FOR MORE INFORMATION
 302 ====================
 303
 304 Check the SCons web site at:
 305
 306         http://www.scons.org/
 307
 308
 309 AUTHOR INFO
 310 ===========
 311
 312 Steven Knight
 313 knight at baldmt dot com
 314 http://www.baldmt.com/~knight/
 315
 316 With more than a little help from the SCons Development team:
 317         Chad Austin
 318         Charles Crain
 319         Steve Leblanc
 320         Anthony Roach
 321