2 # __FILE__ __REVISION__ __DATE__ __DEVELOPER__
5 SCons - a software construction tool
10 This is SCons, a tool for building software (and other files). SCons is
11 implemented in Python, and its "configuration files" are actually Python
12 scripts, allowing you to use the full power of a real scripting language
13 to solve build problems. You do not, however, need to know Python to
14 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 using
18 the instructions on the following page:
20 http://scons.org/lists.php
24 RELEASE 1.3.0 - Tue, 23 Mar 2010 21:44:19 -0400
26 Please consult the CHANGES.txt file for a list of specific changes
29 Please note the following important changes in this release:
31 -- DEPRECATED FEATURES WILL GENERATE MANDATORY WARNINGS IN 1.3.0
33 In keeping with our deprecation cycle, the following deprecated
34 features will still be supported in 1.3.0 but will generate
35 mandatory, non-disableable warnings:
37 -- Support for Python versions 1.5, 1.6, 2.0, 2.1, 2.2, and 2.3.
38 -- The overrides= keyword argument to the Builder() call.
39 -- The scanner= keyword argument to the Builder() call.
40 -- The BuildDir() function and env.BuildDir() method.
41 -- The env.Copy() method.
42 -- The SourceSignatures() function and
43 env.SourceSignatures() method.
44 -- The TargetSignatures() function and
45 env.TargetSignatures() method.
46 -- The Sig module (now an unnused stub).
47 -- The --debug=dtree, --debug=stree and --debug=tree options.
48 -- The --debug=nomemoizer option.
49 -- The Options object and the related BoolOption(),
50 EnumOption(), ListOption(), PackageOption() and
51 PathOption() functions.
53 The mandatory warnings will be issued in order to make sure
54 users of 1.3.0 notice *prior* to the release of SCons 2.0.0, that
55 these features will be removed. In SCons 2.0.0 these features
56 will no longer work at all, and will instead generate specific
57 fatal errors when anyone tries to use them.
59 Please note the following important changes since release 1.2.0:
61 -- MICROSOFT VISUAL STUDIO VERSION/ARCH DETECTION HAS CHANGED
63 The way SCons detects Visual Studio on Windows has changed in
64 1.3. By default, it should now use the latest installed
65 Visual Studio version on your machine, and compile for 32 or
66 64 bits according to whether your OS is 32 or 64 bits (32/64
67 bit python makes no difference).
69 Two new variables control Visual Studio: MSVC_VERSION and
70 TARGET_ARCH. These variables ONLY take effect when passed to
71 the Environment() constructor; setting them later has no
72 effect. To use a non-default Visual Studio version, set
73 MSVC_VERSION to e.g. "8.0" or "7.1". Setting it to "xxx" (or
74 any nonexistent value) will make it print out the valid
75 versions on your system. To use a non-default architecture,
76 set TARGET_ARCH to "x86" or "x86_64" (various synonyms are
79 In addition, MSVC_USE_SCRIPT can be used to bypass the
80 above autodetection; setting it to the path of a Visual
81 Studio .bat file (e.g. vcvars.bat) will cause SCons to
82 run that bat file and extract the relevant variables
83 from the result (typically %INCLUDE%, %LIB%, and %PATH%).
84 Setting MSVC_USE_SCRIPT to None bypasses the Visual Studio
85 autodetection entirely; use this if you are importing
86 the shell env and running SCons in a Visual Studio cmd window.
88 Note that if you use MSVS_VERSION to build Visual Studio
89 projects from your SConstructs, MSVS_VERSION must be set to
90 the same version as MSVC_VERSION.
92 Support for HOST_OS,HOST_ARCH,TARGET_OS, TARGET_ARCH has been
93 added to allow specifying different target arch than the host
94 system. This is only supported for Visual Studio/Visual C++
97 -- Support for Latex glossaries and acronyms has been added
99 -- VISUAL C/C++ PRECOMPILED HEADERS WILL BE REBUILT
101 Precompiled header files built with Visual C/C++ will be
102 rebuilt after upgrading from 1.2.0 to a later release.
104 This rebuild is normal and will occur because the command line
105 defined by the $PCHCOM construction variable has had the $CCFLAGS
106 variable added, and has been rearranged to put the "/Fo" output
107 flag towards the beginning of the line, consistent with the
108 related command lines for $CCCOM, $CXXCOM, etc.
110 -- CHANGES TO SOME LINKER COMMAND LINES WILL CAUSE RELINKING
112 Changes to the command line definitions for the Microsoft link.exe
113 linker, the OS/2 ilink linker and the Phar Lap linkloc linker
114 will cause targets built with those tools be to be rebuilt after
115 upgrading from 1.2.0 to a later release.
117 This relink is normal and will occur because the command lines for
118 these tools have been redefined to remove unnecessary nested $(
119 and $) character strings.
121 -- MSVS_USE_MFC_DIRS and MSVS_IGNORE_IDE_PATHS are obsoleted and
124 Please note the following important changes since release 1.1.0:
126 -- THE $CHANGED_SOURCES, $CHANGED_TARGETS, $UNCHANGED_SOURCES
127 AND $UNCHANGED_TARGETS VARIABLES WILL BECOME RESERVED
129 A future release (probably 1.3.0) will make the construction
130 variable names $CHANGED_SOURCES, $CHANGED_TARGETS,
131 $UNCHANGED_SOURCES and $UNCHANGED_TARGETS into reserved
132 construction variable names controlled by SCons itself (like
133 the current $SOURCE, $TARGETS, etc.).
135 Setting these variable names in the current release will generate
136 a warning but still set the variables. When they become reserved
137 variable names, they will generate a different warning message
138 and attempts to set these variables will be ignored.
140 SCons configurations that happen to use these variable names
141 should be changed to use different variable names, in order
142 to ensure that the configuration continues to work with future
145 -- THE Options OBJECT AND RELATED FUNCTIONS NOW GENERATE WARNINGS
147 Use of the Options object, and related functions BoolOption(),
148 EnumOption(), ListOption(), PackageOption() and PathOption()
149 were announced as deprecated in release 0.98.1. Since then,
150 however, no warning messages were ever implemented for the
151 use of these deprecated functions.
153 By default, release 1.2.0 prints warning messages when these
154 deprecated features are used. Warnings about all deprecated
155 features may be suppressed by using the --warn=no-deprecated
158 $ scons --warn=no-deprecated
160 Or by using the appropriate SetOption() call in any SConscript
163 SetOption('warn', 'no-deprecated')
165 You may optionally disable just warnings about the deprecation
166 of the Options object and its related functions as follows:
168 SetOption('warn', 'no-deprecated-options')
170 The current plan is for these warnings to become mandatory
171 (non-suppressible) in release 1.3.0, and for the use of Options
172 and its related functions to generate errors in release 2.0.
174 Please note the following important changes since release 0.98.4:
176 -- scons.bat NOW RETURNS THE REAL SCONS EXIT STATUS
178 The scons.bat script shipped with SCons used to exit with
179 a status of 1 when it detected any failed (non-zero) exit
180 status from the underlying Python execution of SCons itself.
181 The scons.bat script now exits with the actual status
184 -- SCONS NOW WARNS WHEN TRYING TO LINK C++ AND FORTRAN OBJECT FILES
186 Some C++ toolchains do not understand Fortran runtimes and create
187 unpredictable executables when linking C++ and Fortran object
188 files together. SCons now issues a warning if you try to link
189 C++ and Fortran object files into the same executable:
191 scons: warning: Using $CXX to link Fortran and C++ code together.
192 This may generate a buggy executable if the '/usr/bin/gcc'
193 compiler does not know how to deal with Fortran runtimes.
195 The warning may be suppressed with either the --warning=no-link
196 or --warning=no-fortran-cxx-mix command line options, or by
197 adding either of the following lines to a SConscript file:
199 SetOption('warn', 'no-link')
200 SetOption('warn', 'no-fortran-cxx-mix')
202 Please note the following important changes since release 0.98:
204 -- SCONS NO LONGER SETS THE GNU TOOLCHAIN -fPIC FLAG IN $SHCXXFLAGS
206 The GNU toolchain support in previous versions of SCons would
207 add the -fPIC flag to the $SHCXXFLAGS construction variable.
208 The -fPIC flag has been now been removed from the default
209 $SHCXXFLAGS setting. Instead, the $SHCXXCOM construction variable
210 (the default SCons command line for compiling shared objects
211 from C++ source files) has been changed to add the $SHCCFLAGS
212 variable, which contains the -fPIC flag.
214 This change was made in order to make the behavior of the default
215 C++ compilation line including $SHCCFLAGS consistent with the
216 default C compilation line including $CCFLAGS.
218 This change should have no impact on configurations that use
219 the default $SHCXXCOM command line. It may have an impact on
220 configurations that were using the default $SHCXXFLAGS value
221 *without* the $SHCCFLAGS variable to get the -fPIC flag into a
222 custom command line. You can fix these by adding the $SHCCFLAGS
223 to the custom command line.
225 Adding $SHCCFLAGS is backwards compatible with older SCons
226 releases, although it might cause the -fPIC flag to be repeated
227 on the command line if you execute it on an older version of
228 SCons that sets -fPIC in both the $SHCCLAFGS and $SHCXXFLAGS
229 variables. Duplicating the -fPIC flag on the g++ command line
230 will not cause any compilation problems, but the change to the
231 command line may cause SCons to rebuild object files.
233 -- FORTRAN NOW COMPILES .f FILES WITH gfortran BY DEFAULT
235 The Fortran Tool modules have had a major overhaul with the intent
236 of making them work as-is for most configurations. In general,
237 most configurations that use default settings should not see
238 any noticeable difference.
240 One configuration that has changed is if you have both a gfortran
241 and g77 compiler installed. In this case, previous versions of
242 SCons would, by default, use g77 by default to compile files with
243 a .f suffix, while SCons 0.98.1 will use the gfortran compiler
244 by default. The old behavior may be preserved by explicitly
245 initializing construction environments with the 'g77' Tool module:
247 env = Environment(tools = ['g77', 'default'])
249 The above code is backwards compatible to older versions of SCons.
251 If you notice any other changes in the behavior of default
252 Fortran support, please let us know so we can document them in
253 these release notes for other users.
255 Please note the following important changes since release 0.97.0d20071212:
257 -- SUPPORT FOR PYTHON VERSIONS BEFORE 2.2 IS NOW DEPRECATED
259 SCons now prints the following warning when it is run by any
260 Python 1.5, 2.0 or 2.1 release or sub-release:
262 scons: warning: Support for pre-2.2 Python (VERSION) is deprecated.
263 If this will cause hardship, contact dev@scons.tigris.org.
265 You may disable all warnings about deprecated features by adding
266 the option "--warn=no-deprecated" to the command line or to the
267 $SCONSFLAGS environment variable:
269 $ scons --warn=no-deprecated
271 Using '--warn=no-deprecated' is compatible with earlier versions
274 You may also, as of this version of SCons, disable all warnings
275 about deprecated features by adding the following to any
278 SetOption('warn', 'no-deprecated')
280 You may disable only the specific warning about running under
281 a deprecated Python version by adding the following to any
284 SetOption('warn', 'no-python-version')
286 The warning may also be suppressed on the command line:
288 $ scons --warn=no-python-version
290 Or by specifying the --warn=no-python-version option in the
291 $SCONSFLAGS environment variable.
293 Using SetOption('warn', ...), and the 'no-python-version'
294 command-line option for suppressing this specific warning,
295 are *not* backwards-compatible to earlier versions of SCons.
297 -- THE env.Copy() METHOD IS NOW OFFICIALLY DEPRECATED
299 The env.Copy() method is now officially deprecated and will
300 be removed in a future release. Using the env.Copy() method
301 now generates the following message:
303 scons: warning: The env.Copy() method is deprecated; use the env.Clone() method instead.
305 You may disable all warnings about deprecated features by adding
306 the option "--warn=no-deprecated" to the command line or to the
307 $SCONSFLAGS environment variable:
309 $ scons --warn=no-deprecated
311 Using '--warn=no-deprecated' is compatible with earlier versions
314 You may also, as of this version of SCons, disable all warnings
315 about deprecated features by adding the following to any
318 SetOption('warn', 'no-deprecated')
320 You may disable only the specific warning about the deprecated
321 env.Copy() method by adding the following to any SConscript
324 SetOption('warn', 'no-deprecated-copy')
326 The warning may also be suppressed on the command line:
328 $ scons --warn=no-deprecated-copy
330 Or by specifying the --warn=no-deprecated-copy option in the
331 $SCONSFLAGS environment variable.
333 Using SetOption('warn', ...), and the 'no-deprecated-copy'
334 command-line option for suppressing this specific warning,
335 are *not* backwards-compatible to earlier versions of SCons.
337 -- THE --debug=dtree, --debug=stree AND --debug=tree OPTIONS ARE DEPRECATED
339 The --debug=dtree, --debug=stree and --debug=tree methods
340 are now officially deprecated and will be removed in a
341 future release. Using these options now generate a warning
342 message recommending use of the --tree=derived, --tree=all,status
343 and --tree=all options, respectively.
345 You may disable these warnings, and all warnings about
346 deprecated features, by adding the option "--warn=no-deprecated"
347 to the command line or to the $SCONSFLAGS environment
350 $ scons --warn=no-deprecated
352 Using '--warn=no-deprecated' is compatible with earlier versions
355 -- THE TargetSignatures() AND SourceSignatures() FUNCTIONS ARE DEPRECATED
357 The TargetSignatures() and SourceSignatures() functions,
358 and their corresponding env.TargetSignatures() and
359 env.SourceSignatures() methods, are now officially deprecated
360 and will be be removed in a future release. Using ahy of
361 these functions or methods now generates a message
362 similar to the following:
364 scons: warning: The env.TargetSignatures() method is deprecated;
365 convert your build to use the env.Decider() method instead.
367 You may disable all warnings about deprecated features by adding
368 the option "--warn=no-deprecated" to the command line or to the
369 $SCONSFLAGS environment variable:
371 $ scons --warn=no-deprecated
373 Using '--warn=no-deprecated' is compatible with earlier versions
376 You may also, as of this version of SCons, disable all warnings
377 about deprecated features by adding the following to any
380 SetOption('warn', 'no-deprecated')
382 You may disable only the specific warning about the use of
383 TargetSignatures() or SourceSignatures() by adding the
384 following to any SConscript file:
386 SetOption('warn', 'no-deprecated-target-signatures')
387 SetOption('warn', 'no-deprecated-source-signatures')
389 The warnings may also be suppressed on the command line:
391 $ scons --warn=no-deprecated-target-signatures --warn=no-deprecated-source-signatures
393 Or by specifying these options in the $SCONSFLAGS environment
396 Using SetOption('warn', ...), or the command-line options
397 for suppressing these warnings, is *not* backwards-compatible
398 to earlier versions of SCons.
400 -- File(), Dir() and Entry() NOW RETURN A LIST WHEN THE INPUT IS A SEQUENCE
402 Previously, if these methods were passed a list, the list was
403 substituted and stringified, then passed as a single string to
404 create a File/Dir/Entry Node. This rarely if ever worked with
405 more than one element in the list. They now return a list of
406 Nodes when passed a list.
408 One case that works differently now is a passing in a
409 single-element sequence; that formerly was stringified
410 (returning its only element) and then a single Node would be
411 returned. Now a single-element list containing the Node will
412 be returned, for consistency.
414 -- THE env.subst() METHOD NOW RETURNS A LIST WHEN THE INPUT IS A SEQUENCE
416 The env.subst() method now returns a list with the elements
417 expanded when given a list as input. Previously, the env.subst()
418 method would always turn its result into a string.
420 This behavior was changed because it interfered with being able
421 to include things like lists within the expansion of variables
422 like $CPPPATH and then have SCons understand that the elements
423 of the "internal" lists still needed to be treated separately.
424 This would cause a $CPPPATH list like ['subdir1', 'subdir']
425 to show up in a command line as "-Isubdir1 subdir".
427 -- THE Jar() BUILDER NOW USES THE Java() BUILDER CLASSDIR BY DEFAULT
429 By default, the Jar() Builder will now use the class directory
430 specified when the Java() builder is called. So the following
433 classes = env.Java('classes', 'src')
434 env.Jar('out.jar', classes)
436 Will cause "-C classes" to be passed the "jar" command invocation,
437 and the Java classes in the "out.jar" file will not be prefixed
440 Explicitly setting the $JARCHDIR variable overrides this default
441 behavior. The old behavior of not passing any -C option to the
442 "jar" command can be preserved by explicitly setting $JARCHDIR
445 env = Environment(JARCHDIR = None)
447 The above setting is compatible with older versions of SCons.
449 Please note the following important changes since release 0.97.0d20070918:
451 -- SCons REDEFINES PYTHON open() AND file() ON Windows TO NOT PASS
452 ON OPEN FILE HANDLES TO CREATED PROCESSES
454 On Windows systems, SCons now redefines the Python open()
455 and file() functions so that, if the Python Win32 extensions
456 are available, the file handles for any opened files will *not*
457 be inherited by subprocesses, such as the spawned compilers and
458 other tools invoked to build the software.
460 This prevents certain race conditions where a file handle for
461 a file opened by Python (either in a Python function action,
462 or directly in a SConscript file) could be inherited and help
463 open by a subprocess, interfering with the ability of other
464 processes to create or modify the file.
466 In general, this should not cause problems for the vast majority
467 of configurations. The only time this would be a problem would be
468 in the unlikely event that a process spawned by SCons specifically
469 *expected* to use an inherited file handle opened by SCons.
471 If the Python Win32 extensions are not installed or are an
472 earlier version that does not have the ability to disable file
473 handle inheritance, SCons will print a warning message when the
474 -j option is used. The warning message may be suppressed by
475 specifying --warn=no-parallel-support.
477 Please note the following important changes since release 0.97.0d20070809:
479 -- "content" SIGNATURES ARE NOW THE DEFAULT BEHAVIOR
481 The default behavior of SCons is now to use the MD5 checksum of
482 all file contents to decide if any files have changed and should
483 cause rebuilds of their source files. This means that SCons may
484 decide not to rebuild "downstream" targets if a a given input
485 file is rebuilt to the exact same contents as the last time.
486 The old behavior may preserved by explicity specifying:
488 TargetSignatures("build")
490 In any of your SConscript files.
492 -- TARGETS NOW IMPLICITLY DEPEND ON THE COMMAND THAT BUILDS THEM
494 For all targets built by calling external commands (such as a
495 compiler or other utility), SCons now adds an implicit dependency
496 on the command(s) used to build the target.
498 This will cause rebuilds of all targets built by external commands
499 when running SCons in a tree built by previous version of SCons,
500 in order to update the recorded signatures.
502 The old behavior of not having targets depend on the external
503 commands that build them can be preserved by setting a new
504 $IMPLICIT_COMMAND_DEPENDENCIES construction variable to a
507 env = Environment(IMPLICIT_COMMAND_DEPENDENCIES = 0)
509 or by adding Ignore() calls for any targets where the behavior
512 Ignore('/usr/bin/gcc', 'foo.o')
514 Both of these settings are compatible with older versions
517 -- CHANGING SourceSignature() MAY CAUSE "UNECESSARY" REBUILDS
519 If you change the SourceSignature() value from 'timestamp' to
520 'MD5', SCons will now rebuild targets that were already up-to-date
521 with respect to their source files.
523 This will happen because SCons did not record the content
524 signatures of the input source files when the target was last
525 built--it only recorded the timestamps--and it must record them
526 to make sure the signature information is correct. However,
527 the content of source files may have changed since the last
528 timestamp build was performed, and SCons would not have any way to
529 verify that. (It would have had to open up the file and record
530 a content signature, which is one of the things you're trying to
531 avoid by specifying use of timestamps....) So in order to make
532 sure the built targets reflect the contents of the source files,
533 the targets must be rebuilt.
535 Change the SourceSignature() value from 'MD5' to 'timestamp'
536 should correctly not rebuild target files, because the timestamp
537 of the files is always recorded.
539 In previous versions of SCons, changing the SourceSignature()
540 value would lead to unpredictable behavior, usually including
543 -- THE Return() FUNCTION NOW ACTUALLY RETURNS IMMEDIATELY
545 The Return() function now immediately stops processing the
546 SConscript file in which it appears and returns the values of the
547 variables named in its arguments. It used to continue processing
548 the rest of the SConscript file, and then return the values of the
549 specified variables at the point the Return() function was called.
551 The old behavior may be requested by adding a "stop=False"
552 keyword argument to the Return() call:
554 Return('value', stop=False)
556 The "stop=" keyword argument is *not* compatible with SCons
557 versions 0.97.0d20070809 or earlier.
559 Please note the following important changes since release 0.97:
561 -- env.CacheDir() NOW ONLY AFFECTS CONSTRUCTION ENVIRONMENT TARGETS
563 The env.CacheDir() method now only causes derived files to be
564 retrieved from the specified cache directory for targets built
565 with the specified specified construction environment ("env").
567 Previously, any call to env.CacheDir() or CacheDir() would modify
568 a global setting and cause all built targets to be retrieved
569 from the specified cache directory. This behavior was changed so
570 that env.CacheDir() would be consistent with other construction
571 environment methods, which only affect targets built with the
572 specified construction environment.
574 The old behavior of changing the global behavior may be preserved
575 by changing any env.CacheDir() calls to:
577 CacheDir('/path/to/cache/directory')
579 The above change is backwards-compatible and works in all earlier
580 versions of SCons that support CacheDir().
582 -- INTERPRETATION OF SUFFIX-LESS SOURCE ARGUMENTS HAS CHANGED
584 The interpretation of source arguments (files) without suffixes
585 has changed in one specific configuration.
587 Previously, if a Builder had a src_suffix specified (indicating
588 that source files without suffixes should have that suffix
589 appended), the suffix would only be applied to suffix-less source
590 arguments if the Builder did *not* have one or more attached
591 source Builders (that is, the Builder was not a "multi-stage"
592 Builder). So in the following configuration:
594 build_foo = Builder(src_suffix = '.foo')
595 build_bar = Builder(src_suffix = '.bar',
596 src_builder = build_bar)
598 env = Environment(BUILDERS = {
603 env.Foo('tgt1', 'src1')
604 env.Bar('tgt2', 'src2')
606 SCons would have expected to find a source file 'src1.foo' for the
607 env.Foo() call, but a source file 'src2' for the env.Bar() call.
609 This behavior has now been made consistent, so that the two
610 above calls would expect source files named 'src1.foo' and
611 'src2.bar', respectively.
613 Note that, if genuinely desired, the old behavior of building
614 from a source file without a suffix at all (when the Builder has
615 a src_suffix *and* a src_builder) can be specified explicity by
616 turning the string into a File Node directly:
618 env.Bar('tgt2', File('src2'))
620 The above use of File() is backwards-compatible and will work
621 on earlier versions of SCons.
623 -- THE DEFAULT EXECUTION PATH FOR Solaris HAS CHANGED
625 On Solaris systems, SCons now adds the "/opt/SUNWspro/bin"
626 directory to the default execution $PATH variable before the
627 "/usr/ccs/bin" directory. This was done to reflect the fact
628 that /opt/SUNWspro/ is the default for SUN tools, but it may
629 cause a different compiler to be used if you have compilers
630 installed in both directories.
632 -- GENERATED config.h FILES NOW SAY "#define HAVE_{FEATURE} 1"
634 When generating a "config.h" file, SCons now defines values that
635 record the existence of a feature with a "1" value:
637 #define HAVE_FEATURE 1
639 Instead of printing the line without a "1", as it used to:
643 This should not cause any problems in the normal use of "#ifdef
644 HAVE_{FEATURE}" statements interpreted by a C preprocessor, but
645 might cause a compatibility issue if a script or other utility
646 looks for an exact match of the previous text.
648 Please note the following planned, future changes:
650 -- THE Options OBJECT AND RELATED FUNCTIONS WILL BE DEPRECATED
652 The Options object is being replaced by a new Variables
653 object, which uses a new Variables.AddVariable() method
654 where the previous interface used Options.AddOptions().
656 Similarly, the following utility functions are being replaced
657 by the following similarly-named functions:
659 BoolOption() BoolVariable()
660 EnumOption() EnumVariable()
661 ListOption() ListVariable()
662 PackageOption() PackageVariable()
663 PathOption() PathVariable()
665 And also related, the options= keyword argument when creating
666 construction environments with the Environment() functions is
667 being replaced with a variables= keyword argument.
669 In some future release a deprecation warning will be added to
670 existing uses of the Options object, its methods, the above
671 utility functions, and the options= keyword argument of the
672 Environment() function. At some point after the deprecation
673 warning is added, the Options object, related functions and
674 options= keyword argument will be removed entirely.
676 You can prepare for this by changing all your uses of the Options
677 object and related functions to the Variables object and the new
678 function names, and changing any uses of the options= keyword
679 argument to variables=.
681 NOTE: CONVERTING TO USING THE NEW Variables OBJECT OR THE
682 RELATED *Variable() FUNCTIONS, OR USING THE NEW variable=
683 KEYWORD ARGUMENT, IS NOT BACKWARDS COMPATIBLE TO VERSIONS OF
684 SCons BEFORE 0.98. YOUR SConscript FILES WILL NOT WORK ON
685 EARLIER VERSIONS OF SCons AFTER MAKING THIS CHANGE.
687 If you change SConscript files in software that you make available
688 for download or otherwise distribute, other users may try to
689 build your software with an earlier version of SCons that does
690 not have the Variables object or related *Variable() functions.
691 We recommend preparing for this in one of two ways:
693 -- Make your SConscript files backwards-compatible by
694 modifying your calls with Python try:-except: blocks
698 vars = Variables('custom.py', ARGUMENTS)
700 BoolVariable('WARNINGS', 'cmopile with -Wall', 1),
701 EnumVariable('DEBUG', 'debug version', 'no'
702 allowed_values=('yes', 'no', 'full'),
703 map={}, ignorecase=0),
704 ListVariable('SHAREDLIBS',
705 'libraries to build shared',
707 names = list_of_libs),
708 PackageVariable('X11',
711 PathVariable('QTDIR', 'root of Qt', qtdir),
714 vars = Options('custom.py', ARGUMENTS)
716 BoolOption('WARNINGS', 'cmopile with -Wall', 1),
717 EnumOption('DEBUG', 'debug version', 'no'
718 allowed_values=('yes', 'no', 'full'),
719 map={}, ignorecase=0),
720 ListOption('SHAREDLIBS',
721 'libraries to build shared',
723 names = list_of_libs),
727 PathOption('QTDIR', 'root of Qt', qtdir),
730 Additionally, you can check for availability of the new
731 variables= keyword argument as follows:
734 env = Environment(variables=vars)
736 env = Environment(options=vars)
738 (Note that we plan to maintain the existing Options object
739 name for some time, to ensure backwards compatibility,
740 so in practice it may be easier to just continue to use
741 the old name until you're reasonably sure you won't have
742 people trying to build your software with versions of
743 SCons earlier than 0.98.1.)
745 -- Use the EnsureSConsVersion() function to provide a
746 descriptive error message if your SConscript files
747 are executed by an earlier version of SCons:
749 EnsureSConsVersion(0, 98, 1)
751 -- THE BuildDir() METHOD AND FUNCTION WILL BE DEPRECATED
753 The env.BuildDir() method and BuildDir() function are being
754 replaced by the new env.VariantDir() method and VariantDir()
757 In some future release a deprecation warning will be added
758 to existing uses of the env.BuildDir() method and BuildDir()
759 function. At some point after the deprecation warning, the
760 env.Builder() method and BuildDir() function will either
761 be removed entirely or have their behavior changed.
763 You can prepare for this by changing all your uses of the
764 env.BuildDir() method to env.VariantDir() and uses of the
765 global BuildDir() function to VariantDir(). If you use a
766 named keyword argument of "build_dir" when calling
767 env.BuildDir() or BuildDir():
769 env.BuildDir(build_dir='opt', src_dir='src')
771 The keyword must be changed to "variant_dir":
773 env.VariantDir(variant_dir='opt', src_dir='src')
775 NOTE: CHANGING USES OF env.BuildDir() AND BuildDir() to
776 env.VariantDir() AND VariantDir() IS NOT BACKWARDS COMPATIBLE
777 TO VERSIONS OF SCons BEFORE 0.98. YOUR SConscript FILES
778 WILL NOT WORK ON EARLIER VERSIONS OF SCons AFTER MAKING
781 If you change SConscript files in software that you make
782 available for download or otherwise distribute, other users
783 may try to build your software with an earlier version of
784 SCons that does not have the env.VariantDir() method or
785 VariantDir() fnction. We recommend preparing for this in
788 -- Make your SConscript files backwards-compatible by
789 including the following code near the beginning of your
790 top-level SConstruct file:
792 import SCons.Environment
794 SCons.Environment.Environment.VariantDir
795 except AttributeError:
796 SCons.Environment.Environment.VariantDir = \
797 SCons.Environment.Environment.BuildDir
799 -- Use the EnsureSConsVersion() function to provide a
800 descriptive error message if your SConscript files
801 are executed by an earlier version of SCons:
803 EnsureSConsVersion(0, 98)
805 -- THE SConscript() "build_dir" KEYWORD ARGUMENT WILL BE DEPRECATED
807 The "build_dir" keyword argument of the SConscript function
808 and env.SConscript() method are being replaced by a new
809 "variant_dir" keyword argument.
811 In some future release a deprecation warning will be added
812 to existing uses of the SConscript()/env.SConscript()
813 "build_dir" keyword argument. At some point after the
814 deprecation warning, support for this keyword argument will
817 You can prepare for this by changing all your uses of the
818 SConscript()/env.SConscript() 'build_dir" keyword argument:
820 SConscript('src/SConscript', build_dir='opt')
822 To use the new "variant_dir" keyword argument:
824 SConscript('src/SConscript', variant_dir='opt')
826 NOTE: USING THE NEW "variant_dir" KEYWORD IS NOT BACKWARDS
827 COMPATIBLE TO VERSIONS OF SCons BEFORE 0.98. YOUR SConscript
828 FILES WILL NOT WORK ON EARLIER VERSIONS OF SCons AFTER
831 If you change SConscript files in software that you make
832 available for download or otherwise distribute, other users
833 may try to build your software with an earlier version of
834 SCons that does not support the "variant_dir" keyword.
836 If you can insist that users use a recent version of SCons
837 that supports "variant_dir", we recommend using the
838 EnsureSConsVersion() function to provide a descriptive error
839 message if your SConscript files are executed by an earlier
842 EnsureSConsVersion(0, 98)
844 If you want to make sure that your SConscript files will
845 still work with earlier versions of SCons, then your best
846 bet is to continue to use the "build_dir" keyword until the
847 support is removed (which, in all likelihood, won't happen
848 for quite some time).
850 -- SCANNER NAMES HAVE BEEN DEPRECATED AND WILL BE REMOVED
852 Several internal variable names in SCons.Defaults for various
853 pre-made default Scanner objects have been deprecated and will
854 be removed in a future revision. In their place are several new
855 global variable names that are now part of the publicly-supported
858 NEW NAME DEPRECATED NAME
859 -------- ----------------------------
860 CScanner SCons.Defaults.CScan
861 DSCanner SCons.Defaults.DScan
862 SourceFileScanner SCons.Defaults.ObjSourceScan
863 ProgramScanner SCons.Defaults.ProgScan
865 Of these, only ObjSourceScan was probably used at all, to add
866 new mappings of file suffixes to other scanners for use by the
867 Object() Builder. This should now be done as follows:
869 SourceFileScanner.add_scanner('.x', XScanner)
871 -- THE env.Copy() METHOD WILL CHANGE OR GO AWAY ENTIRELY
873 The env.Copy() method (to make a copy of a construction
874 environment) is being replaced by the env.Clone() method.
876 As of SCons 0.98, a deprecation warning has been added to
877 current uses of the env.Copy() method. At some point in
878 the future, the env.Copy() method will either be removed
879 entirely or have its behavior changed.
881 You can prepare for this by changing all your uses of env.Copy()
882 to env.Clone(), which has the exact same calling arguments.
884 NOTE: CHANGING USES OF env.Copy() TO env.Clone() WILL MAKE
885 YOUR SConscript FILES NOT WORK ON VERSIONS OF SCons BEFORE
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.Clone() method. We recommend
892 preparing for this in one of two ways:
894 -- Make your SConscript files backwards-compatible by
895 including the following code near the beginning of your
896 top-level SConstruct file:
898 import SCons.Environment
900 SCons.Environment.Environment.Clone
901 except AttributeError:
902 SCons.Environment.Environment.Clone = \
903 SCons.Environment.Environment.Copy
905 -- Use the EnsureSConsVersion() function to provide a
906 descriptive error message if your SConscript files
907 are executed by an earlier version of SCons:
909 EnsureSConsVersion(0, 96, 93)
911 -- THE CheckLib Configure TEST WILL CHANGE BEHAVIOR
913 The CheckLib() Configure test appends the lib(s) to the
914 Environment's LIBS list in 1.3 and earlier. In 1.3 there is a
915 new CheckLib argument, append, which defaults to True to
916 preserve the old behavior. In a future release, append will
917 be changed to default to False, to conform with autoconf and
918 user expectations, since it is usually used to build up
919 library lists in a right-to-left way.
923 SCons is developed with an extensive regression test suite, and a
924 rigorous development methodology for continually improving that suite.
925 Because of this, SCons is of sufficient quality that you can use it
928 The interfaces in release 1.0 will *not* be knowingly changed in
929 any new, future 1.x release. If an interface change should ever
930 become necessary due to extraordinary circumstances, the change
931 and an appropriate transition strategy will be documented in these
934 As you use SCons, please heed the following:
936 - Please report any bugs or other problems that you find to our bug
937 tracker at our SourceForge project page:
939 http://sourceforge.net/tracker/?func=add&group_id=30337&atid=398971
941 We have a reliable bug-fixing methodology already in place and
942 strive to respond to problems relatively quickly.
944 - Documentation is spottier than we'd like. You may need to dive
945 into the source code to figure out how to do something. Asking
946 questions on the scons-users mailing list is also welcome. We
947 will be addressing the documentation in upcoming releases, but
948 would be more than glad to have your assistance in correcting this
951 - The "SCons Design" documentation on the SCons web site is very
952 out of date, as we made significant changes to portions of the
953 interface as we figured out what worked and what didn't during the
954 extensive beta implementation. The "SCons Design" document should
955 be used only for historical purposes, or for just an extremely
956 general understanding of SCons' architectural goals.
958 - There may be performance issues. Improving SCons performance
959 is an ongoing priority. If you still find the performance
960 unacceptable, we would very much like to hear from you and learn
961 more about your configuration so we can optimize the right things.
963 - Error messages don't always exist where they'd be helpful.
964 Please let us know about any errors you ran into that would
965 have benefitted from a (more) descriptive message.
967 KNOWN PROBLEMS IN THIS RELEASE:
969 For a complete list of known problems, consult the SCons Issue Tracker
972 http://scons.tigris.org/project_issues.html
974 - Support for parallel builds (-j) does not work on WIN32 systems
975 prior to *official* Python release 2.2 (not 2.2 pre-releases).
977 Prior to Python 2.2, there is a bug in Python's Win32
978 implementation such that when a thread spawns an external command,
979 it blocks all threads from running. This breaks the SCons
980 multithreading architecture used to support -j builds.
982 We have included a patch file, os_spawnv_fix.diff, that you can
983 use if you you want to fix your version of Python to support
984 parallel builds in SCons.
986 - Again, the "SCons Design" documentation on the SCons web site is
987 out of date. Take what you read there with a grain of salt.
989 - On Win32 systems, you must put a space between the redirection
990 characters < and >, and the specified files (or construction
991 variable expansions):
993 command < $SOURCE > $TARGET
995 If you don't supply a space (for example, "<$SOURCE"), SCons will
996 not recognize the redirection.
998 - MSVC .res files are not rebuilt when icons change.
1000 - The -c option does not clean up .sconsign files or directories
1001 created as part of the build, and also does not clean up
1002 SideEffect files (for example, Visual Studio .pdb files).
1004 - When using multiple Repositories, changing the name of an include
1005 file can cause an old version of the file to be used.
1007 - There is currently no way to force use of a relative path (../*)
1008 for directories outside the top-level SConstruct file.
1010 - The Jar() Builder will, on its second or subsequent invocation,
1011 package up the .sconsign files that SCons uses to track signatures.
1012 You can work around this by using the SConsignFile() function
1013 to collect all of the .sconsign information into a single file
1014 outside of the directory being packaged by Jar().
1016 - SCons does not currently have a way to detect that an intermediate
1017 file has been corrupted from outside and should be rebuilt.
1019 - Unicode characters in path names do not work in all circumstances.
1021 - SCons does not currently automatically check out SConstruct or
1022 SConscript files from SCCS, RCS or BitKeeper.
1024 - No support yet for the following planned command-line options:
1026 -d -e -l --list-actions --list-derived --list-where
1027 -o --override -p -r -R -w --write-filenames
1028 -W --warn-undefined-variables
1032 Thank you for your interest, and please let us know how we can help
1033 improve SCons for your needs.
1036 knight at baldmt dot com
1037 http://www.baldmt.com/~knight/
1039 With plenty of help from the SCons Development team: