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