# __COPYRIGHT__ # __FILE__ __REVISION__ __DATE__ __DEVELOPER__ SCons - a software construction tool Release Notes This is a beta release of SCons, a tool for building software (and other files). SCons is implemented in Python, and its "configuration files" are actually Python scripts, allowing you to use the full power of a real scripting language to solve build problems. You do not, however, need to know Python to use SCons effectively. So that everyone using SCons can help each other learn how to use it more effectively, please sign up for the scons-users mailing list at: http://lists.sourceforge.net/lists/listinfo/scons-users RELEASE 0.97 - XXX This is a pre-release for testing the eighth beta release of SCons. Please consult the CHANGES.txt file for a list of specific changes since last release. Please note the following important changes since release 0.96.93: -- THE --debug=memoizer OPTION NOW REQUIRES PYTHON 2.2 OR LATER The --debug=memoizer option now prints a warning message and does nothing if SCons is run on a version of Python that does not support metaclasses (earlier than Python 2.2). -- THE --debug=nomemoizer OPTION DOES NOTHING AND IS NOW DEPRECATED The --debug=nomemoizer no longer does anything and instead now generates a warning message about being deprecated. The --debug=nomemoizer will be removed completely in a future release. Please note the following important changes since release 0.96.91: -- /opt/bin AND /sw/bin ADDED TO DEFAULT EXECUTION PATH VARIABLES On all POSIX systems, the default execution PATH variable has had the /opt/bin directory added after the /usr/local/bin directory and before /bin and /usr/bin directories. This may cause SCons to find and/or different compilers, linkers, etc. if you have any same-named utilities installed in /opt/bin that it previously found in /bin or /usr/bin. On Mac OS X (Darwin) systems, the /sw/bin directory has been added to the end of the default execution PATH. This may cause SCons to find compilers, linkers and other utilities it previously did not, although it should not otherwise change existing behavior. -- Configure.Checklib() ARGUMENTS HAVE CHANGED TO MATCH DOCUMENTATION The order of the arguments to the Configure.CheckLib() function has changed to put the "autoadd" keyword argument last, matching the documentation in the man page. This could cause problems for any calls to Configure.Checklib() that were relying on the order of the arguments. Specifying all arguments as keyword arguments will work on both older and newer versions of SCons. -- env.subst() NO LONGER EXPANDS $TARGET, $SOURCES, etc. BY DEFAULT Calls to the env.subst() method to interpolate construction variables in strings no longer automatically expand the special variables $TARGET, $TARGETS, $SOURCE and $SOURCES. The keyword variables "target" and "source" must now be set to the lists of target and source files to be used in expansion of those variables, when desired. This is most likely necessary for any env.subst() calls within a Python function being used as an SCons action for a Builder: def build_it(env, target, source): env.subst('$STRING', target=targets, source=sources) MyBuilder = Builder(action=build_it) The "target" and "source" keyword arguments are backwards compatible and can be added to SConscript files without breaking builds on systems using older SCons releases. -- INTERNAL FUNCTIONS AND CLASSES HAVE MOVED FROM SCons.Util All internal functions and classes related to string substitution have been moved out of the SCons.Util module into their own SCons.Subst module. The following classes have been moved: Literal SpecialAttrWrapper NLWrapper Targets_or_Sources Target_or_Source And the following functions have moved: quote_spaces() escape_list() subst_dict() scons_subst() scons_subst_list() scons_subst_once() If your SConscript files have been using any of these function directly from the SCons.Util module (which they ultimately should not be!), you will need to modify them. Please note the following important changes since release 0.96.90: -- SIGNATURES ARE NOW STORED IN AN SConsignFile() BY DEFAULT, CAUSING LIKELY REBUILDS; SPECIAL NOTE CONCERNING INTERACTION WITH REPOSITORIES The default behavior has been changed to store signature information in a single .sconsign.dblite file in the top-level SConstruct file. This will cause rebuilds on upgrade to 0.97, unless you were already calling the SConsignFile() function in your SConscript files. The previous default behavior was to store signature information in a .sconsign file in each directory that contained target files that SCons knew about. The old behavior may be preserved by specifying: SConsignFile(None) in any SConscript file. If you are using the Repository feature, and are not already using the SConsignFile() function in your build, you *must* add "SConsignFile(None)" to your build configuration to keep interoperating with an existing Repository that uses the old behavior of a .sconsign file in each directory. Alternatively, you can rebuild the Repository with the new default behavior. -- OTHER SIGNATURE CHANGES WILL CAUSE LIKELY REBUILDS AFTER UPGRADE This release adds several changes to the signature mechanism that will cause SCons to rebuild most configurations after upgrading (and when switching back to an earlier release from 0.97). These changes are: -- NORMALIZED PATHS IN SConsignFile() DATABASES ON WINDOWS When using an SConsignFile() database, instead of individual .sconsign files in each directory, the path names are stored in normalized form with / (forward slash) separating the elements. This may cause rebuilds on Windows systems with hierarchical configurations. -- STORED DEPENDENCY PATHS ARE NOW RELATIVE TO THE TARGET SCons used to store the paths of all source files and dependencies relative to the top-level SConstruct directory. It now stores them relative to the directory of the associated target file. This makes it possible to use content signatures to subdivide a dependency tree without causing unnecessary rebuilds due to an intermediate file in one build being treated as a source file in a nother build. This a step towards making it possible to write a hierarchy of SConstruct files that allow developers to build just one portion of a tree wherever there's an SConstruct file. (Note that this would still require some specific code at the top of each SConstruct file, but we hope to make this an easier/more naturally supported thing in the future.) -- PYTHON FUNCTION ACTION SIGNATURES HAVE CHANGED TO AVOID FUTURE REBUILDS AND REBUILDS BETWEEN PYTHON VERSIONS SCons Actions for Python functions use the functions byte code to generate their signature. The byte code in older versions of Python includes indications of the line numbers at which the function's code appeared in its original source file, which means that changes in the location of an otherwise unmodified Python function would trigger rebuilds. The line number byte codes are now removed from the signature, which will cause any targets built by Python function Actions (including various pre-supplied SCons Actions) be rebuilt. -- REMOVED CONVERSION FROM PRE-0.96 .sconsign FORMATS Because this release involves so many other signature changes that cause rebuilds, the support for automatically converting signature information from .sconsign files written by SCons versions prior to 0.96 has been removed. -- ORDER OF -o FLAGS ON CERTAIN LINK COMMAND LINES HAS CHANGED The -o flag that specifies an output file has been moved on certain linker command lines to place it consistently after the link command itself. This will cause recompilation of target files created by these changed lines. -- F95 AND F90 COMPILERS ARE NOW PREFERRED OVER F77 SCons now searches for Fortran 95 and Fortran 90 compilers first in preference to Fortran 77. This may result in a different Fortran compiler being used by default, although as Fortran 95 and Fortran 90 are backwards compatible with Fortran 77, this should not cause problems for standards-compliant Fortran programs. On systems that have multiple versions of Fortran installed, the Fortran 77 compiler may be explicitly selected by specifying it when creating the construction environment: env = Environment(tools = ['default', 'f77']) -- SOLARIS DEFAULT SHARED OBJECT PREFIXES AND SUFFIXES HAVE CHANGED On Solaris, SCons now builds shared objects from C and C++ source files with a default prefix of "so_" and a default suffix of ".o". The previous default suffix of ".os" caused problems when trying to use SCons with Sun WorkShop. -- CACHED Configure() RESULTS ARE STORED IN A DIFFERENT FILE The Configure() subsystem now stores its cached results in a different file. This may cause configuration tests to be re-run the first time after you install 0.97. -- setup.py INSTALLS VERSION-NUMBERED SCRIPTS AND DIRS BY DEFAULT The setup.py script has been changed to always install SCons in a version-numbered directory (e.g. /usr/local/lib/scons-0.97 or D:\Python23\scons-0.97) and with a version-numbered script name (scons-0.97) in addition to the usual installation of an "scons" script name. A number of new setup.py options allow control over what does or does not get installed, and where. See the README.txt or README files for additional information. -- setup.py NOW INSTALLS MAN PAGES ON UNIX AND Linux SYSTEMS The SCons setup.py script now installs the "scons.1" and "sconsign.1" man pages on UNIX and Linux systems. A new --no-install-man -- BUILDERS RETURN A LIST-LIKE OBJECT, NOT A REGULAR LIST Builder calls now return an object that behaves like a list (and which provides some other functionality), not an underlying Python list. In general, this should not cause any problems, although it introduces a subtle change in the following behavior: obj += env.Object('foo.c') If "obj" is a regular Python list, Python will no longer update the "obj" in place, because the return value from env.Object() is no longer the same type. Python will instead allocate a new object and assign the local variable "obj" to it. If "obj" is defined in an SConscript file that calls another SConscript file containing the above code, "obj" in the first SConscript file will not contain the object file nodes created by the env.Object() call. You can guarantee that a list will be updated in place regardless of which SConscript file defines it and which adds to it by using the list append() method as follows: obj.append(env.Object('foo.c')) Please note the following important changes since release 0.96.1: -- DIRECTORY TREES ARE NO LONGER AUTOMATICALLY SCANNED FOR CHANGES Custom builders and Command() calls that accept directories as source arguments no longer scan entire on-disk directory trees by default. This means that their targets will not be automatically rebuilt if a file changes on disk *unless* SCons already knows about the file from a specific Builder or File() call. Note that the targets will still be rebuilt correctly if a file changes that SCons already knows about due to a Builder or other call. The existing behavior of scanning on-disk directory trees for any changed file can be maintained by passing the new DirScanner global directory scanner as the source_scanner keyword argument to the Builder call: bld = Builder("build < $SOURCE > $TARGET", source_scanner = DirScanner) The same keyword argument can also be supplied to any Command() calls that need to scan directory trees on-disk for changed files: env.Command("archive.out", "directory", "archiver -o $TARGET $SOURCE", source_scanner = DirScanner) This change was made because scanning directories by default could cause huge slowdowns if a configurable directory like /usr or /usr/local was passed as the source to a Builder or Command() call, in which case SCons would scan the entire directory tree. -- ParseConfig() METHOD ADDS LIBRARY FILE NAMES TO THE $LIBS VARIABLE The ParseConfig() method now adds library file names returned by the specified *-config command to the $LIBS construction variable, instead of returning them (the same way it handles the -l option). -- ParseConfig() METHOD DOESN'T ADD DUPLICATES TO CONSTRUCTION VARIABLES By default, the ParseConfig() method now avoids adding duplicate entries to construction variables. The old behavior may be specified using a new "unique=0" keyword argument. -- WINDOWS %TEMP% and %TMP% VARIABLES ARE PROPAGATED AUTOMATICALLY The %TEMP% and %TMP% external environment variables are now propagated automatically to the command execution environment on Windows systems. -- OUTPUT OF Configure() SUBSYSTEM CHANGED SLIGHTLY The Configure() subsystem now reports tests results as "yes" and "no" instead of "ok" and "failed." This might interfere with any scripts that automatically parse the Configure() output from SCons. -- VISUAL STUDIO ATL AND MFC DIRECTORIES NOT ADDED BY DEFAULT When compiling with Microsoft Visual Studio, SCons no longer adds the ATL and MFC directories to the INCLUDE and LIB environment variables by default. If you want these directories included in your environment variables, you should now set the $MSVS_USE_MFC_DIRS *construction* variable when initializing your environment: env = Environment(MSVS_USE_MFC_DIRS = 1) -- DEPRECATED GLOBAL FUNCTIONS HAVE BEEN REMOVED The following deprecated global functions have been removed: ParseConfig(), SetBuildSignatureType(), SetContentSignatureType(), SetJobs() and GetJobs(). -- DEPRECATED "validater" KEYWORD HAS BEEN REMOVED The deprecated "validater" keyword to the Options.Add() method has been removed. Please note the following important changes since release 0.95: -- BUILDERS NOW ALWAYS RETURN A LIST OF TARGETS All Builder calls (both built-in like Program(), Library(), etc. and customer Builders) now always return a list of target Nodes. If the Builder only builds one target, the Builder call will now return a list containing that target Node, not the target Node itself as it used to do. This change should be invisibile to most normal uses of the return values from Builder calls. It will cause an error if the SConscript file was performing some direct manipulation of the returned Node value. For example, an attempt to print the name of a target returned by the Object() Builder: target = Object('foo.c') # OLD WAY print target Will now need to access the first element in the list returned by the Object() call: target = Object('foo.c') # NEW WAY print target[0] This change was introduced to make the data type returned by Builder calls consistent (always a list), regardless of platform or number of returned targets. -- DEFAULT SConsignFile() DATABASE SCHEME HAS CHANGED The SConsignFile() function now uses an internally-supplied SCons.dblite module as the default DB scheme for the .sconsign file. If you are using the SConsignFile() function without an explicitly specified dbm_module argument, this will cause all of your targets to be recompiled the first time you use SCons 0.96. To preserve the previous behavior, specify the "anydbm" module explicitly: import anydbm SConsignFile('.sconsign_file_name', anydbm) -- INTERNAL .sconsign FILE FORMAT HAS CHANGED The internal format of .sconsign files has been changed. This might cause warnings about "ignoring corrupt .sconsign files" and rebuilds when you use SCons 0.96 for the first time in a tree that was previously built with SCons 0.95 or earlier. -- INTERFACE CHANGE OF scan_check FUNCTION TO CUSTOM SCANNERS The scan_check function that can be supplied to a custom Scanner now must take two arguments, the Node to be checked and a construction environment. It previously only used the Node as an argument. -- DEFAULT SCANNERS NO LONGER HEED INTERNAL Scanner.add_skey() METHOD The internal Scanner.add_skey() method no longer works for the default scanners, which now use construction variables to hold their lists of suffixes. If you had a custom Tool specification that was reaching into the internals in this way to add a suffix to one of the following scanner, you must now add the suffix to a construction environment through which you plan to call the scanner, as follows: CScan.add_skey('.x') => env.Append(CPPSUFFIXES = ['.x']) DScan.add_skey('.x') => env.Append(DSUFFIXES = ['.x']) FortranScan.add_skey('.x') => env.Append(FORTRANSUFFIXES = ['.x']) -- KEYWORD ARGUMENTS TO Builder() HAVE BEEN REMOVED The "node_factory" and "scanner" keyword arguments to the Builder() function have been removed. In their place, the separate and more flexible "target_factory," "source_factory," "target_scanner" and "source scanner" keywords should be used instead. -- ALL-DIGIT FILE "EXTENSIONS" ARE NOW PART OF THE FILE BASENAME SCons now treats file "extensions" that contain all digits (for example, "file.123") as part of the file basename, for easier handling of version numbers in the names of shared libraries and other files. Builders will now add their file extensions to file names specified with all-digit extensions. If you need to generate a file with an all-digit extension using a Builder that adds a file extension, you can preserve the previous behavior by wrapping the file name in a File() call. -- Append()/Prepend() METHODS CHANGED WHEN USING UserList OBJECTS The behavior of the env.Append() and env.Prepend() methods has changed when appending a string value to a UserList, or vice versa. They now behave like normal Python addition of a string to a UserList. Given an initialization and an env.Append() call like: env = Environment(VAR1=UserList(['foo']), VAR2='foo') env.Append(VAR1='bar', VAR2=UserList(['bar']) The resulting values of $VAR1 and $VAR2 will now be ['foo', 'b', 'a', 'r'] and ['f', 'o', 'o', 'bar'], respectively. This is because Python UserList objects treat strings as sequences of letters when adding them to the value of the UserList. The old behavior of yielding $VAR1 and $VAR2 values of ['foo', 'bar'] when either variable is a UserList object now requires that the string variables be enclosed in a list: env = Environment(VAR1=UserList(['foo']), VAR2=['foo']) env.Append(VAR1='bar', VAR2=UserList(['bar'])) Note that the SCons behavior when appending to normal lists has *not* changed, and the behavior of all of the default values that SCons uses to initialize all construction variables has *not* changed. This change *only* affects any cases where you explicitly use UserList objects to initialize or append to a variable. Please note the following planned, future changes: -- SCANNER NAMES HAVE BEEN DEPRECATED AND WILL BE REMOVED Several internal variable names in SCons.Defaults for various pre-made default Scanner objects have been deprecated and will be removed in a future revision. In their place are several new global variable names that are now part of the publicly-supported interface: NEW NAME DEPRECATED NAME -------- ---------------------------- CScanner SCons.Defaults.CScan DSCanner SCons.Defaults.DScan SourceFileScanner SCons.Defaults.ObjSourceScan ProgramScanner SCons.Defaults.ProgScan Of these, only ObjSourceScan was probably used at all, to add new mappings of file suffixes to other scanners for use by the Object() Builder. This should now be done as follows: SourceFileScanner.add_scanner('.x', XScanner) -- THE env.Copy() METHOD WILL CHANGE OR GO AWAY ENTIRELY The env.Copy() method (to make a copy of a construction environment) is being replaced by the env.Clone() method. In some future release, a deprecation warning will be added to current uses of the env.Copy() method. At some point after the deprecation warning, the env.Copy() method will either be removed entirely or have its behavior changed. You can prepare for this by changing all your uses of env.Copy() to env.Clone(), which has the exact same calling arguments. NOTE: CHANGING USES OF env.Copy() TO env.Clone() WILL MAKE YOUR SConscript FILES NOT WORK ON EARLIER VERSIONS OF SCons. If you change SConscript files in software that you make available for download or otherwise distribute, other users may try to build your software with an earlier version of SCons that does not have the env.Clone() method. We recommend preparing for this in one of two ways: -- Make your SConscript files backwards-compatible by including the following code near the beginning of your top-level SConstruct file: import SCons.Environment try: SCons.Environment.Environment.Clone except AttributeError: SCons.Environment.Environment.Clone = \ SCons.Environment.Environment.Copy -- Use the EnsureSConsVersion() function to provide a descriptive error message if your SConscript files are executed by an earlier version of SCons: EnsureSConsVersion(0, 96, 93) SCons is developed with an extensive regression test suite, and a rigorous development methodology for continually improving that suite. Because of this, SCons is of sufficient quality that you can use it for real work. The "beta" status of the release reflects that we still may change interfaces in future releases, which may require modifications to your SConscript files. We strive to hold these changes to a minimum. Nevertheless, please heed the following disclaimers: - Please report any bugs or other problems that you find to our bug tracker at our SourceForge project page: http://sourceforge.net/tracker/?func=add&group_id=30337&atid=398971 We have a reliable bug-fixing methodology already in place and strive to respond to problems relatively quickly. - Documentation is spottier than we'd like. You may need to dive into the source code to figure out how to do something. Asking questions on the scons-users mailing list is also welcome. We will be addressing the documentation in upcoming releases, but would be more than glad to have your assistance in correcting this problem... :-) In particular, the "SCons Design" documentation on the SCons web site is currently out of date, as we made significant changes to portions of the interface as we figured out what worked and what didn't during implementation. - There may be performance issues. Improving SCons performance is an ongoing priority. If you still find the performance unacceptable, we would very much like to hear from you and learn more about your configuration so we can optimize the right things. - Error messages don't always exist where they'd be helpful. Please let us know about any errors you ran into that would have benefitted from a (more) descriptive message. KNOWN PROBLEMS IN THIS RELEASE: For a complete list of known problems, consult the SCons bug tracker page at SourceForge: http://sourceforge.net/tracker/?atid=398971&group_id=30337&func=browse - Support for parallel builds (-j) does not work on WIN32 systems prior to *official* Python release 2.2 (not 2.2 pre-releases). Prior to Python 2.2, there is a bug in Python's Win32 implementation such that when a thread spawns an external command, it blocks all threads from running. This breaks the SCons multithreading architecture used to support -j builds. We have included a patch file, os_spawnv_fix.diff, that you can use if you you want to fix your version of Python to support parallel builds in SCons. - Again, the "SCons Design" documentation on the SCons web site is currently out of date. Take what you read there with a grain of salt. - On Win32 systems, you must put a space between the redirection characters < and >, and the specified files (or construction variable expansions): command < $SOURCE > $TARGET If you don't supply a space (for example, "<$SOURCE"), SCons will not recognize the redirection. - MSVC .res files are not rebuilt when icons change. - The -c option does not clean up .sconsign files or directories created as part of the build, and also does not clean up SideEffect files (for example, Visual Studio .pdb files). - Switching content signatures from "MD5" to "timestamp" and back again can cause unusual errors. These errors can be cleared up by removing all .sconsign files. - When using multiple Repositories, changing the name of an include file can cause an old version of the file to be used. - There is currently no way to force use of a relative path (../*) for directories outside the top-level SConstruct file. - The Jar() Builder will, on its second or subsequent invocation, package up the .sconsign files that SCons uses to track signatures. You can work around this by using the SConsignFile() function to collect all of the .sconsign information into a single file outside of the directory being packaged by Jar(). - SCons does not currently have a way to detect that an intermediate file has been corrupted from outside and should be rebuilt. - Unicode characters in path names do not work in all circumstances. - A stray source file in a BuildDir can prevent targets from being (re)built when they should. - SCons does not automatically rebuild LaTeX files when the file has an undefined reference on the first build. - Use of --implicit-cache with TargetSignatures('content') can, for some changes, not rebuild a file when necessary. - SCons does not currently automatically check out SConstruct or SConscript files from SCCS, RCS or BitKeeper. - No support yet for the following planned command-line options: -d -e -l --list-actions --list-derived --list-where -o --override -p -r -R -w --write-filenames -W --warn-undefined-variables Thank you for your interest, and please let us know how we can help improve SCons for your needs. Steven Knight knight at baldmt dot com http://www.baldmt.com/~knight/ With plenty of help from the SCons Development team: Chad Austin Charles Crain Steve Leblanc Gary Oberbrunner Anthony Roach Greg Spencer Christoph Wiedemann