2 # __FILE__ __REVISION__ __DATE__ __DEVELOPER__
5 SCons - a software construction tool
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.
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:
19 http://lists.sourceforge.net/lists/listinfo/scons-users
23 RELEASE 0.98 - Sun, 30 Mar 2008 23:33:05 -0700
25 This is the ninth beta release of SCons. Please consult the
26 CHANGES.txt file for a list of specific changes since last release.
28 Please note the following important changes since release 0.97.0d20071212:
30 -- SUPPORT FOR PYTHON VERSIONS BEFORE 2.2 IS NOW DEPRECATED
32 SCons now prints the following warning when it is run by any
33 Python 1.5, 2.0 or 2.1 release or sub-release:
35 scons: warning: Support for pre-2.2 Python (VERSION) is deprecated.
36 If this will cause hardship, contact dev@scons.tigris.org.
38 You may disable all warnings about deprecated features by adding
39 the option "--warn=no-deprecated" to the command line or to the
40 $SCONSFLAGS environment variable:
42 $ scons --warn=no-deprecated
44 Using '--warn=no-deprecated' is compatible with earlier versions
47 You may also, as of this version of SCons, disable all warnings
48 about deprecated features by adding the following to any
51 SetOption('warn', 'no-deprecated')
53 You may disable only the specific warning about running under
54 a deprecated Python version by adding the following to any
57 SetOption('warn', 'no-python-version')
59 The warning may also be suppressed on the command line:
61 $ scons --warn=no-python-version
63 Or by specifying the --warn=no-python-version option in the
64 $SCONSFLAGS environment variable.
66 Using SetOption('warn', ...), and the 'no-python-version'
67 command-line option for suppressing this specific warning,
68 are *not* backwards-compatible to earlier versions of SCons.
70 -- THE env.Copy() METHOD IS NOW OFFICIALLY DEPRECATED
72 The env.Copy() method is now officially deprecated and will
73 be removed in a future release. Using the env.Copy() method
74 now generates the following message:
76 scons: warning: The env.Copy() method is deprecated; use the env.Clone() method instead.
78 You may disable all warnings about deprecated features by adding
79 the option "--warn=no-deprecated" to the command line or to the
80 $SCONSFLAGS environment variable:
82 $ scons --warn=no-deprecated
84 Using '--warn=no-deprecated' is compatible with earlier versions
87 You may also, as of this version of SCons, disable all warnings
88 about deprecated features by adding the following to any
91 SetOption('warn', 'no-deprecated')
93 You may disable only the specific warning about the deprecated
94 env.Copy() method by adding the following to any SConscript
97 SetOption('warn', 'no-deprecated-copy')
99 The warning may also be suppressed on the command line:
101 $ scons --warn=no-deprecated-copy
103 Or by specifying the --warn=no-deprecated-copy option in the
104 $SCONSFLAGS environment variable.
106 Using SetOption('warn', ...), and the 'no-deprecated-copy'
107 command-line option for suppressing this specific warning,
108 are *not* backwards-compatible to earlier versions of SCons.
110 -- THE --debug=dtree, --debug=stree AND --debug=tree OPTIONS ARE DEPRECATED
112 The --debug=dtree, --debug=stree and --debug=tree methods
113 are now officially deprecated and will be removed in a
114 future release. Using these options now generate a warning
115 message recommending use of the --tree=derived, --tree=all,status
116 and --tree=all options, respectively.
118 You may disable these warnings, and all warnings about
119 deprecated features, by adding the option "--warn=no-deprecated"
120 to the command line or to the $SCONSFLAGS environment
123 $ scons --warn=no-deprecated
125 Using '--warn=no-deprecated' is compatible with earlier versions
128 -- THE TargetSignatures() AND SourceSignatures() FUNCTIONS ARE DEPRECATED
130 The TargetSignatures() and SourceSignatures() functions,
131 and their corresponding env.TargetSignatures() and
132 env.SourceSignatures() methods, are now officially deprecated
133 and will be be removed in a future release. Using ahy of
134 these functions or methods now generates a message
135 similar to the following:
137 scons: warning: The env.TargetSignatures() method is deprecated;
138 convert your build to use the env.Decider() method instead.
140 You may disable all warnings about deprecated features by adding
141 the option "--warn=no-deprecated" to the command line or to the
142 $SCONSFLAGS environment variable:
144 $ scons --warn=no-deprecated
146 Using '--warn=no-deprecated' is compatible with earlier versions
149 You may also, as of this version of SCons, disable all warnings
150 about deprecated features by adding the following to any
153 SetOption('warn', 'no-deprecated')
155 You may disable only the specific warning about the use of
156 TargetSignatures() or SourceSignatures() by adding the
157 following to any SConscript file:
159 SetOption('warn', 'no-deprecated-target-signatures')
160 SetOption('warn', 'no-deprecated-source-signatures')
162 The warnings may also be suppressed on the command line:
164 $ scons --warn=no-deprecated-target-signatures --warn=no-deprecated-source-signatures
166 Or by specifying these options in the $SCONSFLAGS environment
169 Using SetOption('warn', ...), or the command-line options
170 for suppressing these warnings, is *not* backwards-compatible
171 to earlier versions of SCons.
173 -- File(), Dir() and Entry() NOW RETURN A LIST WHEN THE INPUT IS A SEQUENCE
175 Previously, if these methods were passed a list, the list was
176 substituted and stringified, then passed as a single string to
177 create a File/Dir/Entry Node. This rarely if ever worked with
178 more than one element in the list. They now return a list of
179 Nodes when passed a list.
181 One case that works differently now is a passing in a
182 single-element sequence; that formerly was stringified
183 (returning its only element) and then a single Node would be
184 returned. Now a single-element list containing the Node will
185 be returned, for consistency.
187 -- THE env.subst() METHOD NOW RETURNS A LIST WHEN THE INPUT IS A SEQUENCE
189 The env.subst() method now returns a list with the elements
190 expanded when given a list as input. Previously, the env.subst()
191 method would always turn its result into a string.
193 This behavior was changed because it interfered with being able
194 to include things like lists within the expansion of variables
195 like $CPPPATH and then have SCons understand that the elements
196 of the "internal" lists still needed to be treated separately.
197 This would cause a $CPPPATH list like ['subdir1', 'subdir']
198 to show up in a command line as "-Isubdir1 subdir".
200 -- THE Jar() BUILDER NOW USES THE Java() BUILDER CLASSDIR BY DEFAULT
202 By default, the Jar() Builder will now use the class directory
203 specified when the Java() builder is called. So the following
206 classes = env.Java('classes', 'src')
207 env.Jar('out.jar', classes)
209 Will cause "-C classes" to be passed the "jar" command invocation,
210 and the Java classes in the "out.jar" file will not be prefixed
213 Explicitly setting the $JARCHDIR variable overrides this default
214 behavior. The old behavior of not passing any -C option to the
215 "jar" command can be preserved by explicitly setting $JARCHDIR
218 env = Environment(JARCHDIR = None)
220 The above setting is compatible with older versions of SCons.
222 Please note the following important changes since release 0.97.0d20070918:
224 -- SCons REDEFINES PYTHON open() AND file() ON Windows TO NOT PASS
225 ON OPEN FILE HANDLES TO CREATED PROCESSES
227 On Windows systems, SCons now redefines the Python open()
228 and file() functions so that, if the Python Win32 extensions
229 are available, the file handles for any opened files will *not*
230 be inherited by subprocesses, such as the spawned compilers and
231 other tools invoked to build the software.
233 This prevents certain race conditions where a file handle for
234 a file opened by Python (either in a Python function action,
235 or directly in a SConscript file) could be inherited and help
236 open by a subprocess, interfering with the ability of other
237 processes to create or modify the file.
239 In general, this should not cause problems for the vast majority
240 of configurations. The only time this would be a problem would be
241 in the unlikely event that a process spawned by SCons specifically
242 *expected* to use an inherited file handle opened by SCons.
244 If the Python Win32 extensions are not installed or are an
245 earlier version that does not have the ability to disable file
246 handle inheritance, SCons will print a warning message when the
247 -j option is used. The warning message may be suppressed by
248 specifying --warn=no-parallel-support.
250 Please note the following important changes since release 0.97.0d20070809:
252 -- "content" SIGNATURES ARE NOW THE DEFAULT BEHAVIOR
254 The default behavior of SCons is now to use the MD5 checksum of
255 all file contents to decide if any files have changed and should
256 cause rebuilds of their source files. This means that SCons may
257 decide not to rebuild "downstream" targets if a a given input
258 file is rebuilt to the exact same contents as the last time.
259 The old behavior may preserved by explicity specifying:
261 TargetSignatures("build")
263 In any of your SConscript files.
265 -- TARGETS NOW IMPLICITLY DEPEND ON THE COMMAND THAT BUILDS THEM
267 For all targets built by calling external commands (such as a
268 compiler or other utility), SCons now adds an implicit dependency
269 on the command(s) used to build the target.
271 This will cause rebuilds of all targets built by external commands
272 when running SCons in a tree built by previous version of SCons,
273 in order to update the recorded signatures.
275 The old behavior of not having targets depend on the external
276 commands that build them can be preserved by setting a new
277 $IMPLICIT_COMMAND_DEPENDENCIES construction variable to a
280 env = Environment(IMPLICIT_COMMAND_DEPENDENCIES = 0)
282 or by adding Ignore() calls for any targets where the behavior
285 Ignore('/usr/bin/gcc', 'foo.o')
287 Both of these settings are compatible with older versions
290 -- CHANGING SourceSignature() MAY CAUSE "UNECESSARY" REBUILDS
292 If you change the SourceSignature() value from 'timestamp' to
293 'MD5', SCons will now rebuild targets that were already up-to-date
294 with respect to their source files.
296 This will happen because SCons did not record the content
297 signatures of the input source files when the target was last
298 built--it only recorded the timestamps--and it must record them
299 to make sure the signature information is correct. However,
300 the content of source files may have changed since the last
301 timestamp build was performed, and SCons would not have any way to
302 verify that. (It would have had to open up the file and record
303 a content signature, which is one of the things you're trying to
304 avoid by specifying use of timestamps....) So in order to make
305 sure the built targets reflect the contents of the source files,
306 the targets must be rebuilt.
308 Change the SourceSignature() value from 'MD5' to 'timestamp'
309 should correctly not rebuild target files, because the timestamp
310 of the files is always recorded.
312 In previous versions of SCons, changing the SourceSignature()
313 value would lead to unpredictable behavior, usually including
316 -- THE Return() FUNCTION NOW ACTUALLY RETURNS IMMEDIATELY
318 The Return() function now immediately stops processing the
319 SConscript file in which it appears and returns the values of the
320 variables named in its arguments. It used to continue processing
321 the rest of the SConscript file, and then return the values of the
322 specified variables at the point the Return() function was called.
324 The old behavior may be requested by adding a "stop=False"
325 keyword argument to the Return() call:
327 Return('value', stop=False)
329 The "stop=" keyword argument is *not* compatible with SCons
330 versions 0.97.0d20070809 or earlier.
332 Please note the following important changes since release 0.97:
334 -- env.CacheDir() NOW ONLY AFFECTS CONSTRUCTION ENVIRONMENT TARGETS
336 The env.CacheDir() method now only causes derived files to be
337 retrieved from the specified cache directory for targets built
338 with the specified specified construction environment ("env").
340 Previously, any call to env.CacheDir() or CacheDir() would modify
341 a global setting and cause all built targets to be retrieved
342 from the specified cache directory. This behavior was changed so
343 that env.CacheDir() would be consistent with other construction
344 environment methods, which only affect targets built with the
345 specified construction environment.
347 The old behavior of changing the global behavior may be preserved
348 by changing any env.CacheDir() calls to:
350 CacheDir('/path/to/cache/directory')
352 The above change is backwards-compatible and works in all earlier
353 versions of SCons that support CacheDir().
355 -- INTERPRETATION OF SUFFIX-LESS SOURCE ARGUMENTS HAS CHANGED
357 The interpretation of source arguments (files) without suffixes
358 has changed in one specific configuration.
360 Previously, if a Builder had a src_suffix specified (indicating
361 that source files without suffixes should have that suffix
362 appended), the suffix would only be applied to suffix-less source
363 arguments if the Builder did *not* have one or more attached
364 source Builders (that is, the Builder was not a "multi-stage"
365 Builder). So in the following configuration:
367 build_foo = Builder(src_suffix = '.foo')
368 build_bar = Builder(src_suffix = '.bar',
369 src_builder = build_bar)
371 env = Environment(BUILDERS = {
376 env.Foo('tgt1', 'src1')
377 env.Bar('tgt2', 'src2')
379 SCons would have expected to find a source file 'src1.foo' for the
380 env.Foo() call, but a source file 'src2' for the env.Bar() call.
382 This behavior has now been made consistent, so that the two
383 above calls would expect source files named 'src1.foo' and
384 'src2.bar', respectively.
386 Note that, if genuinely desired, the old behavior of building
387 from a source file without a suffix at all (when the Builder has
388 a src_suffix *and* a src_builder) can be specified explicity by
389 turning the string into a File Node directly:
391 env.Bar('tgt2', File('src2'))
393 The above use of File() is backwards-compatible and will work
394 on earlier versions of SCons.
396 -- THE DEFAULT EXECUTION PATH FOR Solaris HAS CHANGED
398 On Solaris systems, SCons now adds the "/opt/SUNWspro/bin"
399 directory to the default execution $PATH variable before the
400 "/usr/ccs/bin" directory. This was done to reflect the fact
401 that /opt/SUNWspro/ is the default for SUN tools, but it may
402 cause a different compiler to be used if you have compilers
403 installed in both directories.
405 -- GENERATED config.h FILES NOW SAY "#define HAVE_{FEATURE} 1"
407 When generating a "config.h" file, SCons now defines values that
408 record the existence of a feature with a "1" value:
410 #define HAVE_FEATURE 1
412 Instead of printing the line without a "1", as it used to:
416 This should not cause any problems in the normal use of "#ifdef
417 HAVE_{FEATURE}" statements interpreted by a C preprocessor, but
418 might cause a compatibility issue if a script or other utility
419 looks for an exact match of the previous text.
421 Please note the following important changes since release 0.96.93:
423 -- THE --debug=memoizer OPTION NOW REQUIRES PYTHON 2.2 OR LATER
425 The --debug=memoizer option now prints a warning message and
426 does nothing if SCons is run on a version of Python that does
427 not support metaclasses (earlier than Python 2.2).
429 -- THE --debug=nomemoizer OPTION DOES NOTHING AND IS NOW DEPRECATED
431 The --debug=nomemoizer no longer does anything and instead
432 now generates a warning message about being deprecated. The
433 --debug=nomemoizer will be removed completely in a future release.
435 Please note the following important changes since release 0.96.91:
437 -- /opt/bin AND /sw/bin ADDED TO DEFAULT EXECUTION PATH VARIABLES
439 On all POSIX systems, the default execution PATH variable has had
440 the /opt/bin directory added after the /usr/local/bin directory
441 and before /bin and /usr/bin directories. This may cause SCons
442 to find and/or use different compilers, linkers, etc., if you
443 have any same-named utilities installed in /opt/bin that SCons
444 previously found in /bin or /usr/bin.
446 On Mac OS X (Darwin) systems, the /sw/bin directory has been added
447 to the end of the default execution PATH. This may cause SCons
448 to find compilers, linkers and other utilities it previously did
449 not, although it should not otherwise change existing behavior.
451 -- Configure.Checklib() ARGUMENTS HAVE CHANGED TO MATCH DOCUMENTATION
453 The order of the arguments to the Configure.CheckLib() function
454 has changed to put the "autoadd" keyword argument last, matching
455 the documentation in the man page. This could cause problems
456 for any calls to Configure.Checklib() that were relying on the
457 order of the arguments. Specifying all arguments as keyword
458 arguments will work on both older and newer versions of SCons.
460 -- env.subst() NO LONGER EXPANDS $TARGET, $SOURCES, etc. BY DEFAULT
462 Calls to the env.subst() method to interpolate construction
463 variables in strings no longer automatically expand the special
464 variables $TARGET, $TARGETS, $SOURCE and $SOURCES. The keyword
465 variables "target" and "source" must now be set to the lists
466 of target and source files to be used in expansion of those
467 variables, when desired.
469 This is most likely necessary for any env.subst() calls within
470 a Python function being used as an SCons action for a Builder:
472 def build_it(env, target, source):
473 env.subst('$STRING', target=targets, source=sources)
474 MyBuilder = Builder(action=build_it)
476 The "target" and "source" keyword arguments are backwards
477 compatible and can be added to SConscript files without breaking
478 builds on systems using older SCons releases.
480 -- INTERNAL FUNCTIONS AND CLASSES HAVE MOVED FROM SCons.Util
482 All internal functions and classes related to string substitution
483 have been moved out of the SCons.Util module into their own
484 SCons.Subst module. The following classes have been moved:
492 And the following functions have moved:
501 If your SConscript files have been using any of these function
502 directly from the SCons.Util module (which they ultimately should
503 not be!), you will need to modify them.
505 Please note the following important changes since release 0.96.90:
507 -- SIGNATURES ARE NOW STORED IN AN SConsignFile() BY DEFAULT,
508 CAUSING LIKELY REBUILDS; SPECIAL NOTE CONCERNING INTERACTION
511 The default behavior has been changed to store signature
512 information in a single .sconsign.dblite file in the top-level
513 SConstruct file. This will cause rebuilds on upgrade to 0.97,
514 unless you were already calling the SConsignFile() function in
515 your SConscript files.
517 The previous default behavior was to store signature information
518 in a .sconsign file in each directory that contained target
519 files that SCons knew about. The old behavior may be preserved
524 in any SConscript file.
526 If you are using the Repository feature, and are not already
527 using the SConsignFile() function in your build, you *must*
528 add "SConsignFile(None)" to your build configuration to keep
529 interoperating with an existing Repository that uses the old
530 behavior of a .sconsign file in each directory. Alternatively,
531 you can rebuild the Repository with the new default behavior.
533 -- OTHER SIGNATURE CHANGES WILL CAUSE LIKELY REBUILDS AFTER UPGRADE
535 This release adds several changes to the signature mechanism that
536 will cause SCons to rebuild most configurations after upgrading
537 (and when switching back to an earlier release from 0.97).
540 -- NORMALIZED PATHS IN SConsignFile() DATABASES ON WINDOWS
542 When using an SConsignFile() database, instead of
543 individual .sconsign files in each directory, the path
544 names are stored in normalized form with / (forward slash)
545 separating the elements. This may cause rebuilds when
546 upgrading to SCons 0.97 on Windows systems with hierarchical
547 build configurations.
549 -- STORED DEPENDENCY PATHS ARE NOW RELATIVE TO THE TARGET
551 SCons used to store the paths of all source files and
552 dependencies relative to the top-level SConstruct directory.
553 It now stores them relative to the directory of the
554 associated target file. This makes it possible to use
555 content signatures to subdivide a dependency tree without
556 causing unnecessary rebuilds due to an intermediate file in
557 one build being treated as a source file in a nother build.
559 This is a step towards making it possible to write a
560 hierarchy of SConstruct files that allow developers
561 to build just one portion of a tree wherever there's an
562 SConstruct file. (Note that this would still require some
563 specific code at the top of each SConstruct file, but we
564 hope to make this an easier/more naturally supported thing
567 -- PYTHON FUNCTION ACTION SIGNATURES HAVE CHANGED TO AVOID
568 FUTURE REBUILDS AND REBUILDS BETWEEN PYTHON VERSIONS
570 SCons Actions for Python functions use the function's
571 byte code to generate their signature. The byte code
572 in older versions of Python includes indications of the
573 line numbers at which the function's code appeared in
574 its original source file, which means that changes in the
575 location of an otherwise unmodified Python function would
576 trigger rebuilds. The line number byte codes are now
577 removed from the signature, which will cause any targets
578 built by Python function Actions (including various
579 pre-supplied SCons Actions) to be rebuilt.
581 -- REMOVED CONVERSION FROM PRE-0.96 .sconsign FORMATS
583 Because this release involves so many other signature
584 changes that cause rebuilds, the support for automatically
585 converting signature information from .sconsign files
586 written by SCons versions prior to 0.96 has been removed.
588 -- ORDER OF -o FLAGS ON CERTAIN LINK COMMAND LINES HAS CHANGED
590 The -o flag that specifies an output file has been moved
591 on certain linker command lines to place it consistently
592 right after the link command itself. This will cause
593 recompilation of target files created by these changed
596 -- F95 AND F90 COMPILERS ARE NOW PREFERRED OVER F77
598 SCons now searches for Fortran 95 and Fortran 90 compilers first
599 in preference to Fortran 77. This may result in a different
600 Fortran compiler being used by default, although as Fortran 95 and
601 Fortran 90 are backwards compatible with Fortran 77, this should
602 not cause problems for standards-compliant Fortran programs.
603 On systems that have multiple versions of Fortran installed,
604 the Fortran 77 compiler may be explicitly selected by specifying
605 it when creating the construction environment:
607 env = Environment(tools = ['default', 'f77'])
609 -- SOLARIS DEFAULT SHARED OBJECT PREFIXES AND SUFFIXES HAVE CHANGED
611 On Solaris, SCons now builds shared objects from C and C++ source
612 files with a default prefix of "so_" and a default suffix of ".o".
613 The previous default suffix of ".os" caused problems when trying
614 to use SCons with Sun WorkShop.
616 -- CACHED Configure() RESULTS ARE STORED IN A DIFFERENT FILE
618 The Configure() subsystem now stores its cached results in a
619 different file. This may cause configuration tests to be re-run
620 the first time after you install 0.97.
622 -- setup.py INSTALLS VERSION-NUMBERED SCRIPTS AND DIRS BY DEFAULT
624 The setup.py script has been changed to always install SCons in
625 a version-numbered directory (e.g. /usr/local/lib/scons-0.97
626 or D:\Python23\scons-0.97) and with a version-numbered script
627 name (scons-0.97) in addition to the usual installation of an
628 "scons" script name. A number of new setup.py options allow
629 control over what does or does not get installed, and where.
630 See the README.txt or README files for additional information.
632 -- setup.py NOW INSTALLS MAN PAGES ON UNIX AND Linux SYSTEMS
634 The SCons setup.py script now installs the "scons.1" and
635 "sconsign.1" man pages on UNIX and Linux systems. A
638 -- BUILDERS RETURN A LIST-LIKE OBJECT, NOT A REGULAR LIST
640 Builder calls now return an object that behaves like a list
641 (and which provides some other functionality), not an underlying
642 Python list. In general, this should not cause any problems,
643 although it introduces a subtle change in the following behavior:
645 obj += env.Object('foo.c')
647 If "obj" is a regular Python list, Python will no longer update
648 the "obj" in place, because the return value from env.Object()
649 is no longer the same type. Python will instead allocate a
650 new object and assign the local variable "obj" to it. If "obj"
651 is defined in an SConscript file that calls another SConscript
652 file containing the above code, "obj" in the first SConscript
653 file will not contain the object file nodes created by the
656 You can guarantee that a list will be updated in place regardless
657 of which SConscript file defines it and which adds to it by
658 using the list extend() method as follows:
660 obj.extend(env.Object('foo.c'))
662 Please note the following important changes since release 0.96.1:
664 -- DIRECTORY TREES ARE NO LONGER AUTOMATICALLY SCANNED FOR CHANGES
666 Custom builders and Command() calls that accept directories as
667 source arguments no longer scan entire on-disk directory trees by
668 default. This means that their targets will not be automatically
669 rebuilt if a file changes on disk *unless* SCons already knows
670 about the file from a specific Builder or File() call. Note that
671 the targets will still be rebuilt correctly if a file changes
672 that SCons already knows about due to a Builder or other call.
674 The existing behavior of scanning on-disk directory trees for
675 any changed file can be maintained by passing the new DirScanner
676 global directory scanner as the source_scanner keyword argument
679 bld = Builder("build < $SOURCE > $TARGET",
680 source_scanner = DirScanner)
682 The same keyword argument can also be supplied to any Command()
683 calls that need to scan directory trees on-disk for changed files:
685 env.Command("archive.out", "directory",
686 "archiver -o $TARGET $SOURCE",
687 source_scanner = DirScanner)
689 This change was made because scanning directories by default
690 could cause huge slowdowns if a configurable directory like /usr
691 or /usr/local was passed as the source to a Builder or Command()
692 call, in which case SCons would scan the entire directory tree.
694 -- ParseConfig() METHOD ADDS LIBRARY FILE NAMES TO THE $LIBS VARIABLE
696 The ParseConfig() method now adds library file names returned
697 by the specified *-config command to the $LIBS construction
698 variable, instead of returning them (the same way it handles
701 -- ParseConfig() METHOD DOESN'T ADD DUPLICATES TO CONSTRUCTION VARIABLES
703 By default, the ParseConfig() method now avoids adding duplicate
704 entries to construction variables. The old behavior may be
705 specified using a new "unique=0" keyword argument.
707 -- WINDOWS %TEMP% and %TMP% VARIABLES ARE PROPAGATED AUTOMATICALLY
709 The %TEMP% and %TMP% external environment variables are now
710 propagated automatically to the command execution environment on
713 -- OUTPUT OF Configure() SUBSYSTEM CHANGED SLIGHTLY
715 The Configure() subsystem now reports tests results as "yes" and
716 "no" instead of "ok" and "failed." This might interfere with any
717 scripts that automatically parse the Configure() output from SCons.
719 -- VISUAL STUDIO ATL AND MFC DIRECTORIES NOT ADDED BY DEFAULT
721 When compiling with Microsoft Visual Studio, SCons no longer
722 adds the ATL and MFC directories to the INCLUDE and LIB
723 environment variables by default. If you want these directories
724 included in your environment variables, you should now set the
725 $MSVS_USE_MFC_DIRS *construction* variable when initializing
728 env = Environment(MSVS_USE_MFC_DIRS = 1)
730 -- DEPRECATED GLOBAL FUNCTIONS HAVE BEEN REMOVED
732 The following deprecated global functions have been removed:
733 ParseConfig(), SetBuildSignatureType(), SetContentSignatureType(),
734 SetJobs() and GetJobs().
736 -- DEPRECATED "validater" KEYWORD HAS BEEN REMOVED
738 The deprecated "validater" keyword to the Options.Add() method
741 Please note the following important changes since release 0.95:
743 -- BUILDERS NOW ALWAYS RETURN A LIST OF TARGETS
745 All Builder calls (both built-in like Program(), Library(),
746 etc. and customer Builders) now always return a list of target
747 Nodes. If the Builder only builds one target, the Builder
748 call will now return a list containing that target Node, not
749 the target Node itself as it used to do.
751 This change should be invisibile to most normal uses of the
752 return values from Builder calls. It will cause an error if the
753 SConscript file was performing some direct manipulation of the
754 returned Node value. For example, an attempt to print the name
755 of a target returned by the Object() Builder:
757 target = Object('foo.c')
761 Will now need to access the first element in the list returned by
764 target = Object('foo.c')
768 This change was introduced to make the data type returned by Builder
769 calls consistent (always a list), regardless of platform or number
772 -- DEFAULT SConsignFile() DATABASE SCHEME HAS CHANGED
774 The SConsignFile() function now uses an internally-supplied
775 SCons.dblite module as the default DB scheme for the .sconsign file.
776 If you are using the SConsignFile() function without an explicitly
777 specified dbm_module argument, this will cause all of your targets
778 to be recompiled the first time you use SCons 0.96. To preserve the
779 previous behavior, specify the "anydbm" module explicitly:
782 SConsignFile('.sconsign_file_name', anydbm)
784 -- INTERNAL .sconsign FILE FORMAT HAS CHANGED
786 The internal format of .sconsign files has been changed. This might
787 cause warnings about "ignoring corrupt .sconsign files" and rebuilds
788 when you use SCons 0.96 for the first time in a tree that was
789 previously built with SCons 0.95 or earlier.
791 -- INTERFACE CHANGE OF scan_check FUNCTION TO CUSTOM SCANNERS
793 The scan_check function that can be supplied to a custom Scanner now
794 must take two arguments, the Node to be checked and a construction
795 environment. It previously only used the Node as an argument.
797 -- DEFAULT SCANNERS NO LONGER HEED INTERNAL Scanner.add_skey() METHOD
799 The internal Scanner.add_skey() method no longer works for the
800 default scanners, which now use construction variables to hold their
801 lists of suffixes. If you had a custom Tool specification that was
802 reaching into the internals in this way to add a suffix to one of
803 the following scanner, you must now add the suffix to a construction
804 environment through which you plan to call the scanner, as follows:
806 CScan.add_skey('.x') => env.Append(CPPSUFFIXES = ['.x'])
807 DScan.add_skey('.x') => env.Append(DSUFFIXES = ['.x'])
808 FortranScan.add_skey('.x') => env.Append(FORTRANSUFFIXES = ['.x'])
810 -- KEYWORD ARGUMENTS TO Builder() HAVE BEEN REMOVED
812 The "node_factory" and "scanner" keyword arguments to the Builder()
813 function have been removed. In their place, the separate and more
814 flexible "target_factory," "source_factory," "target_scanner" and
815 "source scanner" keywords should be used instead.
817 -- ALL-DIGIT FILE "EXTENSIONS" ARE NOW PART OF THE FILE BASENAME
819 SCons now treats file "extensions" that contain all digits (for
820 example, "file.123") as part of the file basename, for easier
821 handling of version numbers in the names of shared libraries
822 and other files. Builders will now add their file extensions to
823 file names specified with all-digit extensions. If you need to
824 generate a file with an all-digit extension using a Builder that
825 adds a file extension, you can preserve the previous behavior by
826 wrapping the file name in a File() call.
828 -- Append()/Prepend() METHODS CHANGED WHEN USING UserList OBJECTS
830 The behavior of the env.Append() and env.Prepend() methods has
831 changed when appending a string value to a UserList, or vice versa.
832 They now behave like normal Python addition of a string to
833 a UserList. Given an initialization and an env.Append() call like:
835 env = Environment(VAR1=UserList(['foo']), VAR2='foo')
836 env.Append(VAR1='bar', VAR2=UserList(['bar'])
838 The resulting values of $VAR1 and $VAR2 will now be ['foo', 'b',
839 'a', 'r'] and ['f', 'o', 'o', 'bar'], respectively. This is because
840 Python UserList objects treat strings as sequences of letters when
841 adding them to the value of the UserList.
843 The old behavior of yielding $VAR1 and $VAR2 values of ['foo',
844 'bar'] when either variable is a UserList object now requires that
845 the string variables be enclosed in a list:
847 env = Environment(VAR1=UserList(['foo']), VAR2=['foo'])
848 env.Append(VAR1='bar', VAR2=UserList(['bar']))
850 Note that the SCons behavior when appending to normal lists has
851 *not* changed, and the behavior of all of the default values that
852 SCons uses to initialize all construction variables has *not*
853 changed. This change *only* affects any cases where you explicitly
854 use UserList objects to initialize or append to a variable.
856 Please note the following planned, future changes:
858 -- THE BuildDir() METHOD AND FUNCTION WILL BE DEPRECATED
860 The env.BuildDir() method and BuildDir() function are being
861 replaced by the new env.VariantDir() method and VariantDir()
864 In some future release a deprecation warning will be added
865 to existing uses of the env.BuildDir() method and BuildDir()
866 function. At some point after the deprecation warning, the
867 env.Builder() method and BuildDir() function will either
868 be removed entirely or have their behavior changed.
870 You can prepare for this by changing all your uses of the
871 env.BuildDir() method to env.VariantDir() and uses of the
872 global BuildDir() function to VariantDir(). If you use a
873 named keyword argument of "build_dir" when calling
874 env.BuildDir() or BuildDir():
876 env.BuildDir(build_dir='opt', src_dir='src')
878 The keyword must be changed to "variant_dir":
880 env.VariantDir(variant_dir='opt', src_dir='src')
882 NOTE: CHANGING USES OF env.BuildDir() AND BuildDir() to
883 env.VariantDir() AND VariantDir() IS NOT BACKWARDS COMPATIBLE
884 TO VERSIONS OF SCons BEFORE 0.98. YOUR SConscript FILES
885 WILL NOT WORK ON EARLIER VERSIONS OF SCons AFTER MAKING
888 If you change SConscript files in software that you make
889 available for download or otherwise distribute, other users
890 may try to build your software with an earlier version of
891 SCons that does not have the env.VariantDir() method or
892 VariantDir() fnction. We recommend preparing for this in
895 -- Make your SConscript files backwards-compatible by
896 including the following code near the beginning of your
897 top-level SConstruct file:
899 import SCons.Environment
901 SCons.Environment.Environment.VariantDir
902 except AttributeError:
903 SCons.Environment.Environment.VariantDir = \
904 SCons.Environment.Environment.BuildDir
906 -- Use the EnsureSConsVersion() function to provide a
907 descriptive error message if your SConscript files
908 are executed by an earlier version of SCons:
910 EnsureSConsVersion(0, 98)
912 -- THE SConscript() "build_dir" KEYWORD ARGUMENT WILL BE DEPRECATED
914 The "build_dir" keyword argument of the SConscript function
915 and env.SConscript() method are being replaced by a new
916 "variant_dir" keyword argument.
918 In some future release a deprecation warning will be added
919 to existing uses of the SConscript()/env.SConscript()
920 "build_dir" keyword argument. At some point after the
921 deprecation warning, support for this keyword argument will
924 You can prepare for this by changing all your uses of the
925 SConscript()/env.SConscript() 'build_dir" keyword argument:
927 SConscript('src/SConscript', build_dir='opt')
929 To use the new "variant_dir" keyword argument:
931 SConscript('src/SConscript', variant_dir='opt')
933 NOTE: USING THE NEW "variant_dir" KEYWORD IS NOT BACKWARDS
934 COMPATIBLE TO VERSIONS OF SCons BEFORE 0.98. YOUR SConscript
935 FILES WILL NOT WORK ON EARLIER VERSIONS OF SCons AFTER
938 If you change SConscript files in software that you make
939 available for download or otherwise distribute, other users
940 may try to build your software with an earlier version of
941 SCons that does not support the "variant_dir" keyword.
943 If you can insist that users use a recent version of SCons
944 that supports "variant_dir", we recommend using the
945 EnsureSConsVersion() function to provide a descriptive error
946 message if your SConscript files are executed by an earlier
949 EnsureSConsVersion(0, 98)
951 If you want to make sure that your SConscript files will
952 still work with earlier versions of SCons, then your best
953 bet is to continue to use the "build_dir" keyword until the
954 support is removed (which, in all likelihood, won't happen
955 for quite some time).
957 -- SCANNER NAMES HAVE BEEN DEPRECATED AND WILL BE REMOVED
959 Several internal variable names in SCons.Defaults for various
960 pre-made default Scanner objects have been deprecated and will
961 be removed in a future revision. In their place are several new
962 global variable names that are now part of the publicly-supported
965 NEW NAME DEPRECATED NAME
966 -------- ----------------------------
967 CScanner SCons.Defaults.CScan
968 DSCanner SCons.Defaults.DScan
969 SourceFileScanner SCons.Defaults.ObjSourceScan
970 ProgramScanner SCons.Defaults.ProgScan
972 Of these, only ObjSourceScan was probably used at all, to add
973 new mappings of file suffixes to other scanners for use by the
974 Object() Builder. This should now be done as follows:
976 SourceFileScanner.add_scanner('.x', XScanner)
978 -- THE env.Copy() METHOD WILL CHANGE OR GO AWAY ENTIRELY
980 The env.Copy() method (to make a copy of a construction
981 environment) is being replaced by the env.Clone() method.
983 As of SCons 0.98, a deprecation warning has been added to
984 current uses of the env.Copy() method. At some point in
985 the future, the env.Copy() method will either be removed
986 entirely or have its behavior changed.
988 You can prepare for this by changing all your uses of env.Copy()
989 to env.Clone(), which has the exact same calling arguments.
991 NOTE: CHANGING USES OF env.Copy() TO env.Clone() WILL MAKE
992 YOUR SConscript FILES NOT WORK ON VERSIONS OF SCons BEFORE
995 If you change SConscript files in software that you make
996 available for download or otherwise distribute, other users
997 may try to build your software with an earlier version of
998 SCons that does not have the env.Clone() method. We recommend
999 preparing for this in one of two ways:
1001 -- Make your SConscript files backwards-compatible by
1002 including the following code near the beginning of your
1003 top-level SConstruct file:
1005 import SCons.Environment
1007 SCons.Environment.Environment.Clone
1008 except AttributeError:
1009 SCons.Environment.Environment.Clone = \
1010 SCons.Environment.Environment.Copy
1012 -- Use the EnsureSConsVersion() function to provide a
1013 descriptive error message if your SConscript files
1014 are executed by an earlier version of SCons:
1016 EnsureSConsVersion(0, 96, 93)
1018 SCons is developed with an extensive regression test suite, and a
1019 rigorous development methodology for continually improving that suite.
1020 Because of this, SCons is of sufficient quality that you can use it
1021 for real work. The "beta" status of the release reflects that we
1022 still may change interfaces in future releases, which may require
1023 modifications to your SConscript files. We strive to hold these
1024 changes to a minimum.
1026 Nevertheless, please heed the following disclaimers:
1028 - Please report any bugs or other problems that you find to our bug
1029 tracker at our SourceForge project page:
1031 http://sourceforge.net/tracker/?func=add&group_id=30337&atid=398971
1033 We have a reliable bug-fixing methodology already in place and
1034 strive to respond to problems relatively quickly.
1036 - Documentation is spottier than we'd like. You may need to dive
1037 into the source code to figure out how to do something. Asking
1038 questions on the scons-users mailing list is also welcome. We
1039 will be addressing the documentation in upcoming releases, but
1040 would be more than glad to have your assistance in correcting this
1043 In particular, the "SCons Design" documentation on the SCons web
1044 site is currently out of date, as we made significant changes to
1045 portions of the interface as we figured out what worked and what
1046 didn't during implementation.
1048 - There may be performance issues. Improving SCons performance
1049 is an ongoing priority. If you still find the performance
1050 unacceptable, we would very much like to hear from you and learn
1051 more about your configuration so we can optimize the right things.
1053 - Error messages don't always exist where they'd be helpful.
1054 Please let us know about any errors you ran into that would
1055 have benefitted from a (more) descriptive message.
1057 KNOWN PROBLEMS IN THIS RELEASE:
1059 For a complete list of known problems, consult the SCons Issue Tracker
1062 http://scons.tigris.org/project_issues.html
1064 - Support for parallel builds (-j) does not work on WIN32 systems
1065 prior to *official* Python release 2.2 (not 2.2 pre-releases).
1067 Prior to Python 2.2, there is a bug in Python's Win32
1068 implementation such that when a thread spawns an external command,
1069 it blocks all threads from running. This breaks the SCons
1070 multithreading architecture used to support -j builds.
1072 We have included a patch file, os_spawnv_fix.diff, that you can
1073 use if you you want to fix your version of Python to support
1074 parallel builds in SCons.
1076 - Again, the "SCons Design" documentation on the SCons web
1077 site is currently out of date. Take what you read there with a
1080 - On Win32 systems, you must put a space between the redirection
1081 characters < and >, and the specified files (or construction
1082 variable expansions):
1084 command < $SOURCE > $TARGET
1086 If you don't supply a space (for example, "<$SOURCE"), SCons will
1087 not recognize the redirection.
1089 - MSVC .res files are not rebuilt when icons change.
1091 - The -c option does not clean up .sconsign files or directories
1092 created as part of the build, and also does not clean up
1093 SideEffect files (for example, Visual Studio .pdb files).
1095 - When using multiple Repositories, changing the name of an include
1096 file can cause an old version of the file to be used.
1098 - There is currently no way to force use of a relative path (../*)
1099 for directories outside the top-level SConstruct file.
1101 - The Jar() Builder will, on its second or subsequent invocation,
1102 package up the .sconsign files that SCons uses to track signatures.
1103 You can work around this by using the SConsignFile() function
1104 to collect all of the .sconsign information into a single file
1105 outside of the directory being packaged by Jar().
1107 - SCons does not currently have a way to detect that an intermediate
1108 file has been corrupted from outside and should be rebuilt.
1110 - Unicode characters in path names do not work in all circumstances.
1112 - SCons does not currently automatically check out SConstruct or
1113 SConscript files from SCCS, RCS or BitKeeper.
1115 - No support yet for the following planned command-line options:
1117 -d -e -l --list-actions --list-derived --list-where
1118 -o --override -p -r -R -w --write-filenames
1119 -W --warn-undefined-variables
1123 Thank you for your interest, and please let us know how we can help
1124 improve SCons for your needs.
1127 knight at baldmt dot com
1128 http://www.baldmt.com/~knight/
1130 With plenty of help from the SCons Development team: