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