src/RELEASE.txt

   1 # __COPYRIGHT__
   2 # __FILE__ __REVISION__ __DATE__ __DEVELOPER__
   3
   4
   5                  SCons - a software construction tool
   6
   7                             Release Notes
   8
   9
  10 This is a beta release of SCons, a tool for building software (and other
  11 files).  SCons is implemented in Python, and its "configuration files"
  12 are actually Python scripts, allowing you to use the full power of a
  13 real scripting language to solve build problems.  You do not, however,
  14 need to know Python to use SCons effectively.
  15
  16 So that everyone using SCons can help each other learn how to use it
  17 more effectively, please sign up for the scons-users mailing list at:
  18
  19     http://lists.sourceforge.net/lists/listinfo/scons-users
  20
  21
  22
  23 RELEASE 0.96 - XXX
  24
  25   This is the seventh beta release of SCons.  Please consult the
  26   CHANGES.txt file for a list of specific changes since last release.
  27
  28   Please note the following important changes since release 0.95:
  29
  30     - The SConsignFile() function now uses an internally-supplied
  31       SCons.dblite module as the default DB scheme for the .sconsign file.
  32       If you are using the SConsignFile() function without an explicitly
  33       specified dbm_module argument, this will cause all of your targets
  34       to be recompiled the first time you use SCons 0.96.  To preserve the
  35       previous behavior, specify the "anydbm" module explicitly:
  36
  37           import anydbm
  38           SConsignFile('.sconsign_file_name', anydbm)
  39
  40     - The scan_check function that can be supplied to a custom Scanner now
  41       must take two arguments, the Node to be checked and a construction
  42       environment.  It previously only used the Node as an argument.
  43
  44     - The internal Scanner.add_skey() method no longer works for the
  45       default scanners, which now use construction variables to hold their
  46       lists of suffixes.  If you had a custom Tool specification that was
  47       reaching into the internals in this way to add a suffix to one of
  48       the following scanner, you must now add the suffix to a construction
  49       environment through which you plan to call the scanner, as follows:
  50
  51
  52           CScan.add_skey('.x')       => env.Append(CPPSUFFIXES = ['.x'])
  53           DScan.add_skey('.x')       => env.Append(DSUFFIXES = ['.x'])
  54           FortranScan.add_skey('.x') => env.Append(FORTRANSUFFIXES = ['.x'])
  55
  56     - The internal "node_factory" keyword argument has been removed;
  57       the seperate and more flexible "target_factory" and "source_factory"
  58       keywords should be used instead.
  59
  60     - The behavior of the env.Append() and env.Prepend() methods has
  61       changed when appending a string value to a UserList, or vice versa.
  62       They now behave like normal Python addition of a string to
  63       a UserList.  Given an initialization and an env.Append() call like:
  64
  65           env = Environment(VAR1=UserList(['foo']), VAR2='foo')
  66           env.Append(VAR1='bar', VAR2=UserList(['bar'])
  67
  68       The resulting values of $VAR1 and $VAR2 will now be ['foo', 'b',
  69       'a', 'r'] and ['f', 'o', 'o', 'bar'], respectively.  This is because
  70       Python UserList objects treat strings as sequences of letters when
  71       adding them to the value of the UserList.
  72
  73       The old behavior of yielding $VAR1 and $VAR2 values of ['foo',
  74       'bar'] when either variable is a UserList object now requires that
  75       the string variables be enclosed in a list:
  76
  77           env = Environment(VAR1=UserList(['foo']), VAR2=['foo'])
  78           env.Append(VAR1='bar', VAR2=UserList(['bar']))
  79
  80       Note that the SCons behavior when appending to normal lists has
  81       *not* changed, and the behavior of all of the default values that
  82       SCons uses to initialize all construction variables has *not*
  83       changed.  This change *only* affects any cases where you explicitly
  84       use UserList objects to initialize or append to a variable.
  85
  86   Please note the following important changes since release 0.94:
  87
  88     - The internal Python function used by the Zip Builder in Python
  89       releases 1.6 or later now compresses the resulting .zip file
  90       by default.  The old behavior of creating an uncompressed file
  91       may be preserved by setting the new ZIPCOMPRESSION construction
  92       variable to 0 (or zipfile.ZIP_STORED, if you import the
  93       underlying zipfile module).
  94
  95     - The "overrides" keyword argument to calls to the Builder() function
  96       used to create new Builder objects has been deprecated and will
  97       be removed in a future release.  The items in an "overrides"
  98       dictionary should now be specified as keyword arguments:
  99
 100           # Old way, "overrides" is a dictionary:
 101           Builder(action = 'cp $TDIR/$TARGET $SDIR/$SOURCE',
 102                   overrides = {'TDIR' : dir1, 'SDIR' : dir2})
 103
 104           # New way, items are specified as keyword arguments:
 105           Builder(action = 'cp $TDIR/$TARGET $SDIR/$SOURCE',
 106                   TDIR = dir1, SDIR = dir2)
 107
 108     - The meaning of some of the values of the "mode" argument to
 109       the SCons.Util.scons_subst() and SCons.Util.scons_subst_list()
 110       functions have been swapped.  The wrapper Environment.subst() and
 111       Environment.subst_list() methods remain completely unchanged, so
 112       this should have no external effect.  (We've listed the change here
 113       because it might cause a problem if you're reaching into the SCons
 114       internals and calling either of these SCons.Util functions directly.)
 115
 116   Please note the following FUTURE changes that you may wish to prepare
 117   for:
 118
 119     - When compiling with Microsoft Visual Studio, SCons currently adds
 120       the ATL and MFC directories to the INCLUDE and LIB environment
 121       variables by default.  This default behavior will be changed in
 122       a future release; the current plan is to change it for the 0.97
 123       release (next release).
 124
 125       Whether or not the ATL and MFC directories are added to these
 126       environment variables is now controlled by a new MSVS_USE_MFC_DIRS
 127       *construction* variable.  Setting this variable to a non-zero
 128       value when you initialize an Environment will ensure that these
 129       directories will be included in your external path(s) even when
 130       the default behavior changes:
 131
 132           env = Environment(MSVS_USE_MFC_DIRS = 1)
 133
 134       The MSVS_USE_MFC_DIRS variable may, of course, be set to 0 (or
 135       None) to prevent SCons from adding the ATL and MFC directories to
 136       the INCLUDE and LIB environment variables.
 137
 138   SCons is developed with an extensive regression test suite, and a
 139   rigorous development methodology for continually improving that suite.
 140   Because of this, SCons is of sufficient quality that you can use it
 141   for real work.  The "beta" status of the release reflects that we
 142   still may change interfaces in future releases, which may require
 143   modifications to your SConscript files.  We strive to hold these
 144   changes to a minimum.
 145
 146   Nevertheless, please heed the following disclaimers:
 147
 148     - Please report any bugs or other problems that you find to our bug
 149       tracker at our SourceForge project page:
 150
 151       http://sourceforge.net/tracker/?func=add&group_id=30337&atid=398971
 152
 153       We have a reliable bug-fixing methodology already in place and
 154       strive to respond to problems relatively quickly.
 155
 156     - Documentation is spottier than we'd like.  You may need to dive
 157       into the source code to figure out how to do something.  Asking
 158       questions on the scons-users mailing list is also welcome.  We
 159       will be addressing the documentation in upcoming releases, but
 160       would be more than glad to have your assistance in correcting this
 161       problem... :-)
 162
 163       In particular, the "SCons Design" documentation on the SCons web
 164       site is currently out of date, as we made significant changes to
 165       portions of the interface as we figured out what worked and what
 166       didn't during implementation.
 167
 168     - There may be performance issues.  Improving SCons performance
 169       is an ongoing priority.  If you still find the performance
 170       unacceptable, we would very much like to hear from you and learn
 171       more about your configuration so we can optimize the right things.
 172
 173     - Error messages don't always exist where they'd be helpful.
 174       Please let us know about any errors you ran into that would
 175       have benefitted from a (more) descriptive message.
 176
 177   KNOWN PROBLEMS IN THIS RELEASE:
 178
 179     For a complete list of known problems, consult the SCons bug tracker
 180     page at SourceForge:
 181
 182         http://sourceforge.net/tracker/?atid=398971&group_id=30337&func=browse
 183
 184     - Support for parallel builds (-j) does not work on WIN32 systems
 185       prior to *official* Python release 2.2 (not 2.2 pre-releases).
 186
 187       Prior to Python 2.2, there is a bug in Python's Win32
 188       implementation such that when a thread spawns an external command,
 189       it blocks all threads from running.  This breaks the SCons
 190       multithreading architecture used to support -j builds.
 191
 192       We have included a patch file, os_spawnv_fix.diff, that you can
 193       use if you you want to fix your version of Python to support
 194       parallel builds in SCons.
 195
 196     - Again, the "SCons Design" documentation on the SCons web
 197       site is currently out of date.  Take what you read there with a
 198       grain of salt.
 199
 200     - If a file is specified to be built in multiple ways, the last
 201       processed builder specification overwrites all other builders,
 202       without any warning.
 203
 204     - On Win32 systems, you must put a space between the redirection
 205       characters < and >, and the specified files (or construction
 206       variable expansions):
 207
 208         command < $SOURCE > $TARGET
 209
 210       If you don't supply a space (for example, "<$SOURCE"), SCons will
 211       not recognize the redirection.
 212
 213     - People have reported problems with SCons not stopping a build when
 214       an interrupt (CTRL+C) is received.  A fix was checked in to 0.11
 215       that should fix this behavior on many systems, but there are
 216       issues with the underlying Python os.system() call that suggest
 217       this fix does not work on all systems or in all circumstances.
 218       We're working to try to find a universal solution.
 219
 220     - Modifying a construction environment in a subsidiary SConscript
 221       file modifies the global environment.
 222
 223     - MSVC .res files are not rebuilt when icons change.
 224
 225     - The -c option does not clean up .sconsign files or directories
 226       created as part of the build, and also does not clean up
 227       SideEffect files (for example, Visual Studio .pdb files).
 228
 229     - Switching content signatures from "MD5" to "timestamp" and back
 230       again can cause unusual errors.  These errors can be cleared up by
 231       removing all .sconsign files.
 232
 233     - When using multiple Repositories, changing the name of an include
 234       file can cause an old version of the file to be used.
 235
 236     - There is currently no way to force use of a relative path (../*)
 237       for directories outside the top-level SConstruct file.
 238
 239     - The Jar() Builder will, on its second or subsequent invocation,
 240       package up the .sconsign files that SCons uses to track signatures.
 241       You can work around this by using the SConsignFile() function
 242       to collect all of the .sconsign information into a single file
 243       outside of the directory being packaged by Jar().
 244
 245     - SCons does not currently have a way to detect that an intermediate
 246       file has been corrupted from outside and should be rebuilt.
 247
 248     - Unicode characters in path names do not work in all circumstances.
 249
 250     - A stray source file in a BuildDir can prevent targets from being
 251       (re)built when they should.
 252
 253     - SCons does not automatically rebuild LaTeX files when the file
 254       has an undefined reference on the first build.
 255
 256     - SideEffect() files are not retrieved properly from a CacheDir(),
 257       and can lead to a stack trace.
 258
 259     - Use of --implicit-cache with TargetSignatures('content') can,
 260       for some changes, not rebuild a file when necessary.
 261
 262     - SCons does not currently automatically check out SConstruct or
 263       SConscript files from SCCS, RCS or BitKeeper.
 264
 265     - The Command() global function (specified without a construction
 266       environment) is broken.
 267
 268     - No support yet for the following planned command-line options:
 269
 270          -d -e -l --list-actions --list-derived --list-where
 271          -o --override -p -r -R -w --write-filenames
 272          -W --warn-undefined-variables
 273
 274
 275
 276 Thank you for your interest, and please let us know how we can help
 277 improve SCons for your needs.
 278
 279 Steven Knight
 280 knight at baldmt dot com
 281 http://www.baldmt.com/~knight/
 282
 283 With plenty of help from the SCons Development team:
 284         Chad Austin
 285         Charles Crain
 286         Steve Leblanc
 287         Gary Oberbrunner
 288         Anthony Roach
 289         Greg Spencer
 290         Christoph Wiedemann
 291