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