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