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 at:
19 http://lists.sourceforge.net/lists/listinfo/scons-users
23 RELEASE 1.0.1 - Sat, 06 Sep 2008 07:29:34 -0700
25 Please consult the CHANGES.txt file for a list of specific changes
28 Please note the following important changes since release 0.98.4:
30 -- scons.bat NOW RETURNS THE REAL SCONS EXIT STATUS
32 The scons.bat script shipped with SCons used to exit with
33 a status of 1 when it detected any failed (non-zero) exit
34 status from the underlying Python execution of SCons itself.
35 The scons.bat script now exits with the actual status
38 -- SCONS NOW WARNS WHEN TRYING TO LINK C++ AND FORTRAN OBJECT FILES
40 Some C++ toolchains do not understand Fortran runtimes and create
41 unpredictable executables when linking C++ and Fortran object
42 files together. SCons now issues a warning if you try to link
43 C++ and Fortran object files into the same executable:
45 scons: warning: Using $CXX to link Fortran and C++ code together.
46 This may generate a buggy executable if the '/usr/bin/gcc'
47 compiler does not know how to deal with Fortran runtimes.
49 The warning may be suppressed with either the --warning=no-link
50 or --warning=no-fortran-cxx-mix command line options, or by
51 adding either of the following lines to a SConscript file:
53 SetOption('warn', 'no-link')
54 SetOption('warn', 'no-fortran-cxx-mix')
56 Please note the following important changes since release 0.98:
58 -- SCONS NO LONGER SETS THE GNU TOOLCHAIN -fPIC FLAG IN $SHCXXFLAGS
60 The GNU toolchain support in previous versions of SCons would
61 add the -fPIC flag to the $SHCXXFLAGS construction variable.
62 The -fPIC flag has been now been removed from the default
63 $SHCXXFLAGS setting. Instead, the $SHCXXCOM construction variable
64 (the default SCons command line for compiling shared objects
65 from C++ source files) has been changed to add the $SHCCFLAGS
66 variable, which contains the -fPIC flag.
68 This change was made in order to make the behavior of the default
69 C++ compilation line including $SHCCFLAGS consistent with the
70 default C compilation line including $CCFLAGS.
72 This change should have no impact on configurations that use
73 the default $SHCXXCOM command line. It may have an impact on
74 configurations that were using the default $SHCXXFLAGS value
75 *without* the $SHCCFLAGS variable to get the -fPIC flag into a
76 custom command line. You can fix these by adding the $SHCCFLAGS
77 to the custom command line.
79 Adding $SHCCFLAGS is backwards compatible with older SCons
80 releases, although it might cause the -fPIC flag to be repeated
81 on the command line if you execute it on an older version of
82 SCons that sets -fPIC in both the $SHCCLAFGS and $SHCXXFLAGS
83 variables. Duplicating the -fPIC flag on the g++ command line
84 will not cause any compilation problems, but the change to the
85 command line may cause SCons to rebuild object files.
87 -- FORTRAN NOW COMPILES .f FILES WITH gfortran BY DEFAULT
89 The Fortran Tool modules have had a major overhaul with the intent
90 of making them work as-is for most configurations. In general,
91 most configurations that use default settings should not see
92 any noticeable difference.
94 One configuration that has changed is if you have both a gfortran
95 and g77 compiler installed. In this case, previous versions of
96 SCons would, by default, use g77 by default to compile files with
97 a .f suffix, while SCons 0.98.1 will use the gfortran compiler
98 by default. The old behavior may be preserved by explicitly
99 initializing construction environments with the 'g77' Tool module:
101 env = Environment(tools = ['g77', 'default'])
103 The above code is backwards compatible to older versions of SCons.
105 If you notice any other changes in the behavior of default
106 Fortran support, please let us know so we can document them in
107 these release notes for other users.
109 Please note the following important changes since release 0.97.0d20071212:
111 -- SUPPORT FOR PYTHON VERSIONS BEFORE 2.2 IS NOW DEPRECATED
113 SCons now prints the following warning when it is run by any
114 Python 1.5, 2.0 or 2.1 release or sub-release:
116 scons: warning: Support for pre-2.2 Python (VERSION) is deprecated.
117 If this will cause hardship, contact dev@scons.tigris.org.
119 You may disable all warnings about deprecated features by adding
120 the option "--warn=no-deprecated" to the command line or to the
121 $SCONSFLAGS environment variable:
123 $ scons --warn=no-deprecated
125 Using '--warn=no-deprecated' is compatible with earlier versions
128 You may also, as of this version of SCons, disable all warnings
129 about deprecated features by adding the following to any
132 SetOption('warn', 'no-deprecated')
134 You may disable only the specific warning about running under
135 a deprecated Python version by adding the following to any
138 SetOption('warn', 'no-python-version')
140 The warning may also be suppressed on the command line:
142 $ scons --warn=no-python-version
144 Or by specifying the --warn=no-python-version option in the
145 $SCONSFLAGS environment variable.
147 Using SetOption('warn', ...), and the 'no-python-version'
148 command-line option for suppressing this specific warning,
149 are *not* backwards-compatible to earlier versions of SCons.
151 -- THE env.Copy() METHOD IS NOW OFFICIALLY DEPRECATED
153 The env.Copy() method is now officially deprecated and will
154 be removed in a future release. Using the env.Copy() method
155 now generates the following message:
157 scons: warning: The env.Copy() method is deprecated; use the env.Clone() method instead.
159 You may disable all warnings about deprecated features by adding
160 the option "--warn=no-deprecated" to the command line or to the
161 $SCONSFLAGS environment variable:
163 $ scons --warn=no-deprecated
165 Using '--warn=no-deprecated' is compatible with earlier versions
168 You may also, as of this version of SCons, disable all warnings
169 about deprecated features by adding the following to any
172 SetOption('warn', 'no-deprecated')
174 You may disable only the specific warning about the deprecated
175 env.Copy() method by adding the following to any SConscript
178 SetOption('warn', 'no-deprecated-copy')
180 The warning may also be suppressed on the command line:
182 $ scons --warn=no-deprecated-copy
184 Or by specifying the --warn=no-deprecated-copy option in the
185 $SCONSFLAGS environment variable.
187 Using SetOption('warn', ...), and the 'no-deprecated-copy'
188 command-line option for suppressing this specific warning,
189 are *not* backwards-compatible to earlier versions of SCons.
191 -- THE --debug=dtree, --debug=stree AND --debug=tree OPTIONS ARE DEPRECATED
193 The --debug=dtree, --debug=stree and --debug=tree methods
194 are now officially deprecated and will be removed in a
195 future release. Using these options now generate a warning
196 message recommending use of the --tree=derived, --tree=all,status
197 and --tree=all options, respectively.
199 You may disable these warnings, and all warnings about
200 deprecated features, by adding the option "--warn=no-deprecated"
201 to the command line or to the $SCONSFLAGS environment
204 $ scons --warn=no-deprecated
206 Using '--warn=no-deprecated' is compatible with earlier versions
209 -- THE TargetSignatures() AND SourceSignatures() FUNCTIONS ARE DEPRECATED
211 The TargetSignatures() and SourceSignatures() functions,
212 and their corresponding env.TargetSignatures() and
213 env.SourceSignatures() methods, are now officially deprecated
214 and will be be removed in a future release. Using ahy of
215 these functions or methods now generates a message
216 similar to the following:
218 scons: warning: The env.TargetSignatures() method is deprecated;
219 convert your build to use the env.Decider() method instead.
221 You may disable all warnings about deprecated features by adding
222 the option "--warn=no-deprecated" to the command line or to the
223 $SCONSFLAGS environment variable:
225 $ scons --warn=no-deprecated
227 Using '--warn=no-deprecated' is compatible with earlier versions
230 You may also, as of this version of SCons, disable all warnings
231 about deprecated features by adding the following to any
234 SetOption('warn', 'no-deprecated')
236 You may disable only the specific warning about the use of
237 TargetSignatures() or SourceSignatures() by adding the
238 following to any SConscript file:
240 SetOption('warn', 'no-deprecated-target-signatures')
241 SetOption('warn', 'no-deprecated-source-signatures')
243 The warnings may also be suppressed on the command line:
245 $ scons --warn=no-deprecated-target-signatures --warn=no-deprecated-source-signatures
247 Or by specifying these options in the $SCONSFLAGS environment
250 Using SetOption('warn', ...), or the command-line options
251 for suppressing these warnings, is *not* backwards-compatible
252 to earlier versions of SCons.
254 -- File(), Dir() and Entry() NOW RETURN A LIST WHEN THE INPUT IS A SEQUENCE
256 Previously, if these methods were passed a list, the list was
257 substituted and stringified, then passed as a single string to
258 create a File/Dir/Entry Node. This rarely if ever worked with
259 more than one element in the list. They now return a list of
260 Nodes when passed a list.
262 One case that works differently now is a passing in a
263 single-element sequence; that formerly was stringified
264 (returning its only element) and then a single Node would be
265 returned. Now a single-element list containing the Node will
266 be returned, for consistency.
268 -- THE env.subst() METHOD NOW RETURNS A LIST WHEN THE INPUT IS A SEQUENCE
270 The env.subst() method now returns a list with the elements
271 expanded when given a list as input. Previously, the env.subst()
272 method would always turn its result into a string.
274 This behavior was changed because it interfered with being able
275 to include things like lists within the expansion of variables
276 like $CPPPATH and then have SCons understand that the elements
277 of the "internal" lists still needed to be treated separately.
278 This would cause a $CPPPATH list like ['subdir1', 'subdir']
279 to show up in a command line as "-Isubdir1 subdir".
281 -- THE Jar() BUILDER NOW USES THE Java() BUILDER CLASSDIR BY DEFAULT
283 By default, the Jar() Builder will now use the class directory
284 specified when the Java() builder is called. So the following
287 classes = env.Java('classes', 'src')
288 env.Jar('out.jar', classes)
290 Will cause "-C classes" to be passed the "jar" command invocation,
291 and the Java classes in the "out.jar" file will not be prefixed
294 Explicitly setting the $JARCHDIR variable overrides this default
295 behavior. The old behavior of not passing any -C option to the
296 "jar" command can be preserved by explicitly setting $JARCHDIR
299 env = Environment(JARCHDIR = None)
301 The above setting is compatible with older versions of SCons.
303 Please note the following important changes since release 0.97.0d20070918:
305 -- SCons REDEFINES PYTHON open() AND file() ON Windows TO NOT PASS
306 ON OPEN FILE HANDLES TO CREATED PROCESSES
308 On Windows systems, SCons now redefines the Python open()
309 and file() functions so that, if the Python Win32 extensions
310 are available, the file handles for any opened files will *not*
311 be inherited by subprocesses, such as the spawned compilers and
312 other tools invoked to build the software.
314 This prevents certain race conditions where a file handle for
315 a file opened by Python (either in a Python function action,
316 or directly in a SConscript file) could be inherited and help
317 open by a subprocess, interfering with the ability of other
318 processes to create or modify the file.
320 In general, this should not cause problems for the vast majority
321 of configurations. The only time this would be a problem would be
322 in the unlikely event that a process spawned by SCons specifically
323 *expected* to use an inherited file handle opened by SCons.
325 If the Python Win32 extensions are not installed or are an
326 earlier version that does not have the ability to disable file
327 handle inheritance, SCons will print a warning message when the
328 -j option is used. The warning message may be suppressed by
329 specifying --warn=no-parallel-support.
331 Please note the following important changes since release 0.97.0d20070809:
333 -- "content" SIGNATURES ARE NOW THE DEFAULT BEHAVIOR
335 The default behavior of SCons is now to use the MD5 checksum of
336 all file contents to decide if any files have changed and should
337 cause rebuilds of their source files. This means that SCons may
338 decide not to rebuild "downstream" targets if a a given input
339 file is rebuilt to the exact same contents as the last time.
340 The old behavior may preserved by explicity specifying:
342 TargetSignatures("build")
344 In any of your SConscript files.
346 -- TARGETS NOW IMPLICITLY DEPEND ON THE COMMAND THAT BUILDS THEM
348 For all targets built by calling external commands (such as a
349 compiler or other utility), SCons now adds an implicit dependency
350 on the command(s) used to build the target.
352 This will cause rebuilds of all targets built by external commands
353 when running SCons in a tree built by previous version of SCons,
354 in order to update the recorded signatures.
356 The old behavior of not having targets depend on the external
357 commands that build them can be preserved by setting a new
358 $IMPLICIT_COMMAND_DEPENDENCIES construction variable to a
361 env = Environment(IMPLICIT_COMMAND_DEPENDENCIES = 0)
363 or by adding Ignore() calls for any targets where the behavior
366 Ignore('/usr/bin/gcc', 'foo.o')
368 Both of these settings are compatible with older versions
371 -- CHANGING SourceSignature() MAY CAUSE "UNECESSARY" REBUILDS
373 If you change the SourceSignature() value from 'timestamp' to
374 'MD5', SCons will now rebuild targets that were already up-to-date
375 with respect to their source files.
377 This will happen because SCons did not record the content
378 signatures of the input source files when the target was last
379 built--it only recorded the timestamps--and it must record them
380 to make sure the signature information is correct. However,
381 the content of source files may have changed since the last
382 timestamp build was performed, and SCons would not have any way to
383 verify that. (It would have had to open up the file and record
384 a content signature, which is one of the things you're trying to
385 avoid by specifying use of timestamps....) So in order to make
386 sure the built targets reflect the contents of the source files,
387 the targets must be rebuilt.
389 Change the SourceSignature() value from 'MD5' to 'timestamp'
390 should correctly not rebuild target files, because the timestamp
391 of the files is always recorded.
393 In previous versions of SCons, changing the SourceSignature()
394 value would lead to unpredictable behavior, usually including
397 -- THE Return() FUNCTION NOW ACTUALLY RETURNS IMMEDIATELY
399 The Return() function now immediately stops processing the
400 SConscript file in which it appears and returns the values of the
401 variables named in its arguments. It used to continue processing
402 the rest of the SConscript file, and then return the values of the
403 specified variables at the point the Return() function was called.
405 The old behavior may be requested by adding a "stop=False"
406 keyword argument to the Return() call:
408 Return('value', stop=False)
410 The "stop=" keyword argument is *not* compatible with SCons
411 versions 0.97.0d20070809 or earlier.
413 Please note the following important changes since release 0.97:
415 -- env.CacheDir() NOW ONLY AFFECTS CONSTRUCTION ENVIRONMENT TARGETS
417 The env.CacheDir() method now only causes derived files to be
418 retrieved from the specified cache directory for targets built
419 with the specified specified construction environment ("env").
421 Previously, any call to env.CacheDir() or CacheDir() would modify
422 a global setting and cause all built targets to be retrieved
423 from the specified cache directory. This behavior was changed so
424 that env.CacheDir() would be consistent with other construction
425 environment methods, which only affect targets built with the
426 specified construction environment.
428 The old behavior of changing the global behavior may be preserved
429 by changing any env.CacheDir() calls to:
431 CacheDir('/path/to/cache/directory')
433 The above change is backwards-compatible and works in all earlier
434 versions of SCons that support CacheDir().
436 -- INTERPRETATION OF SUFFIX-LESS SOURCE ARGUMENTS HAS CHANGED
438 The interpretation of source arguments (files) without suffixes
439 has changed in one specific configuration.
441 Previously, if a Builder had a src_suffix specified (indicating
442 that source files without suffixes should have that suffix
443 appended), the suffix would only be applied to suffix-less source
444 arguments if the Builder did *not* have one or more attached
445 source Builders (that is, the Builder was not a "multi-stage"
446 Builder). So in the following configuration:
448 build_foo = Builder(src_suffix = '.foo')
449 build_bar = Builder(src_suffix = '.bar',
450 src_builder = build_bar)
452 env = Environment(BUILDERS = {
457 env.Foo('tgt1', 'src1')
458 env.Bar('tgt2', 'src2')
460 SCons would have expected to find a source file 'src1.foo' for the
461 env.Foo() call, but a source file 'src2' for the env.Bar() call.
463 This behavior has now been made consistent, so that the two
464 above calls would expect source files named 'src1.foo' and
465 'src2.bar', respectively.
467 Note that, if genuinely desired, the old behavior of building
468 from a source file without a suffix at all (when the Builder has
469 a src_suffix *and* a src_builder) can be specified explicity by
470 turning the string into a File Node directly:
472 env.Bar('tgt2', File('src2'))
474 The above use of File() is backwards-compatible and will work
475 on earlier versions of SCons.
477 -- THE DEFAULT EXECUTION PATH FOR Solaris HAS CHANGED
479 On Solaris systems, SCons now adds the "/opt/SUNWspro/bin"
480 directory to the default execution $PATH variable before the
481 "/usr/ccs/bin" directory. This was done to reflect the fact
482 that /opt/SUNWspro/ is the default for SUN tools, but it may
483 cause a different compiler to be used if you have compilers
484 installed in both directories.
486 -- GENERATED config.h FILES NOW SAY "#define HAVE_{FEATURE} 1"
488 When generating a "config.h" file, SCons now defines values that
489 record the existence of a feature with a "1" value:
491 #define HAVE_FEATURE 1
493 Instead of printing the line without a "1", as it used to:
497 This should not cause any problems in the normal use of "#ifdef
498 HAVE_{FEATURE}" statements interpreted by a C preprocessor, but
499 might cause a compatibility issue if a script or other utility
500 looks for an exact match of the previous text.
502 Please note the following planned, future changes:
504 -- THE Options OBJECT AND RELATED FUNCTIONS WILL BE DEPRECATED
506 The Options object is being replaced by a new Variables
507 object, which uses a new Variables.AddVariable() method
508 where the previous interface used Options.AddOptions().
510 Similarly, the following utility functions are being replaced
511 by the following similarly-named functions:
513 BoolOption() BoolVariable()
514 EnumOption() EnumVariable()
515 ListOption() ListVariable()
516 PackageOption() PackageVariable()
517 PathOption() PathVariable()
519 And also related, the options= keyword argument when creating
520 construction environments with the Environment() functions is
521 being replaced with a variables= keyword argument.
523 In some future release a deprecation warning will be added to
524 existing uses of the Options object, its methods, the above
525 utility functions, and the options= keyword argument of the
526 Environment() function. At some point after the deprecation
527 warning is added, the Options object, related functions and
528 options= keyword argument will be removed entirely.
530 You can prepare for this by changing all your uses of the Options
531 object and related functions to the Variables object and the new
532 function names, and changing any uses of the options= keyword
533 argument to variables=.
535 NOTE: CONVERTING TO USING THE NEW Variables OBJECT OR THE
536 RELATED *Variable() FUNCTIONS, OR USING THE NEW variable=
537 KEYWORD ARGUMENT, IS NOT BACKWARDS COMPATIBLE TO VERSIONS OF
538 SCons BEFORE 0.98. YOUR SConscript FILES WILL NOT WORK ON
539 EARLIER VERSIONS OF SCons AFTER MAKING THIS CHANGE.
541 If you change SConscript files in software that you make available
542 for download or otherwise distribute, other users may try to
543 build your software with an earlier version of SCons that does
544 not have the Variables object or related *Variable() functions.
545 We recommend preparing for this in one of two ways:
547 -- Make your SConscript files backwards-compatible by
548 modifying your calls with Python try:-except: blocks
552 vars = Variables('custom.py', ARGUMENTS)
554 BoolVariable('WARNINGS', 'cmopile with -Wall', 1),
555 EnumVariable('DEBUG', 'debug version', 'no'
556 allowed_values=('yes', 'no', 'full'),
557 map={}, ignorecase=0),
558 ListVariable('SHAREDLIBS',
559 'libraries to build shared',
561 names = list_of_libs),
562 PackageVariable('X11',
565 PathVariable('QTDIR', 'root of Qt', qtdir),
568 vars = Options('custom.py', ARGUMENTS)
570 BoolOption('WARNINGS', 'cmopile with -Wall', 1),
571 EnumOption('DEBUG', 'debug version', 'no'
572 allowed_values=('yes', 'no', 'full'),
573 map={}, ignorecase=0),
574 ListOption('SHAREDLIBS',
575 'libraries to build shared',
577 names = list_of_libs),
581 PathOption('QTDIR', 'root of Qt', qtdir),
584 Additionally, you can check for availability of the new
585 variables= keyword argument as follows:
588 env = Environment(variables=vars)
590 env = Environment(options=vars)
592 (Note that we plan to maintain the existing Options object
593 name for some time, to ensure backwards compatibility,
594 so in practice it may be easier to just continue to use
595 the old name until you're reasonably sure you won't have
596 people trying to build your software with versions of
597 SCons earlier than 0.98.1.)
599 -- Use the EnsureSConsVersion() function to provide a
600 descriptive error message if your SConscript files
601 are executed by an earlier version of SCons:
603 EnsureSConsVersion(0, 98, 1)
605 -- THE BuildDir() METHOD AND FUNCTION WILL BE DEPRECATED
607 The env.BuildDir() method and BuildDir() function are being
608 replaced by the new env.VariantDir() method and VariantDir()
611 In some future release a deprecation warning will be added
612 to existing uses of the env.BuildDir() method and BuildDir()
613 function. At some point after the deprecation warning, the
614 env.Builder() method and BuildDir() function will either
615 be removed entirely or have their behavior changed.
617 You can prepare for this by changing all your uses of the
618 env.BuildDir() method to env.VariantDir() and uses of the
619 global BuildDir() function to VariantDir(). If you use a
620 named keyword argument of "build_dir" when calling
621 env.BuildDir() or BuildDir():
623 env.BuildDir(build_dir='opt', src_dir='src')
625 The keyword must be changed to "variant_dir":
627 env.VariantDir(variant_dir='opt', src_dir='src')
629 NOTE: CHANGING USES OF env.BuildDir() AND BuildDir() to
630 env.VariantDir() AND VariantDir() IS NOT BACKWARDS COMPATIBLE
631 TO VERSIONS OF SCons BEFORE 0.98. YOUR SConscript FILES
632 WILL NOT WORK ON EARLIER VERSIONS OF SCons AFTER MAKING
635 If you change SConscript files in software that you make
636 available for download or otherwise distribute, other users
637 may try to build your software with an earlier version of
638 SCons that does not have the env.VariantDir() method or
639 VariantDir() fnction. We recommend preparing for this in
642 -- Make your SConscript files backwards-compatible by
643 including the following code near the beginning of your
644 top-level SConstruct file:
646 import SCons.Environment
648 SCons.Environment.Environment.VariantDir
649 except AttributeError:
650 SCons.Environment.Environment.VariantDir = \
651 SCons.Environment.Environment.BuildDir
653 -- Use the EnsureSConsVersion() function to provide a
654 descriptive error message if your SConscript files
655 are executed by an earlier version of SCons:
657 EnsureSConsVersion(0, 98)
659 -- THE SConscript() "build_dir" KEYWORD ARGUMENT WILL BE DEPRECATED
661 The "build_dir" keyword argument of the SConscript function
662 and env.SConscript() method are being replaced by a new
663 "variant_dir" keyword argument.
665 In some future release a deprecation warning will be added
666 to existing uses of the SConscript()/env.SConscript()
667 "build_dir" keyword argument. At some point after the
668 deprecation warning, support for this keyword argument will
671 You can prepare for this by changing all your uses of the
672 SConscript()/env.SConscript() 'build_dir" keyword argument:
674 SConscript('src/SConscript', build_dir='opt')
676 To use the new "variant_dir" keyword argument:
678 SConscript('src/SConscript', variant_dir='opt')
680 NOTE: USING THE NEW "variant_dir" KEYWORD IS NOT BACKWARDS
681 COMPATIBLE TO VERSIONS OF SCons BEFORE 0.98. YOUR SConscript
682 FILES WILL NOT WORK ON EARLIER VERSIONS OF SCons AFTER
685 If you change SConscript files in software that you make
686 available for download or otherwise distribute, other users
687 may try to build your software with an earlier version of
688 SCons that does not support the "variant_dir" keyword.
690 If you can insist that users use a recent version of SCons
691 that supports "variant_dir", we recommend using the
692 EnsureSConsVersion() function to provide a descriptive error
693 message if your SConscript files are executed by an earlier
696 EnsureSConsVersion(0, 98)
698 If you want to make sure that your SConscript files will
699 still work with earlier versions of SCons, then your best
700 bet is to continue to use the "build_dir" keyword until the
701 support is removed (which, in all likelihood, won't happen
702 for quite some time).
704 -- SCANNER NAMES HAVE BEEN DEPRECATED AND WILL BE REMOVED
706 Several internal variable names in SCons.Defaults for various
707 pre-made default Scanner objects have been deprecated and will
708 be removed in a future revision. In their place are several new
709 global variable names that are now part of the publicly-supported
712 NEW NAME DEPRECATED NAME
713 -------- ----------------------------
714 CScanner SCons.Defaults.CScan
715 DSCanner SCons.Defaults.DScan
716 SourceFileScanner SCons.Defaults.ObjSourceScan
717 ProgramScanner SCons.Defaults.ProgScan
719 Of these, only ObjSourceScan was probably used at all, to add
720 new mappings of file suffixes to other scanners for use by the
721 Object() Builder. This should now be done as follows:
723 SourceFileScanner.add_scanner('.x', XScanner)
725 -- THE env.Copy() METHOD WILL CHANGE OR GO AWAY ENTIRELY
727 The env.Copy() method (to make a copy of a construction
728 environment) is being replaced by the env.Clone() method.
730 As of SCons 0.98, a deprecation warning has been added to
731 current uses of the env.Copy() method. At some point in
732 the future, the env.Copy() method will either be removed
733 entirely or have its behavior changed.
735 You can prepare for this by changing all your uses of env.Copy()
736 to env.Clone(), which has the exact same calling arguments.
738 NOTE: CHANGING USES OF env.Copy() TO env.Clone() WILL MAKE
739 YOUR SConscript FILES NOT WORK ON VERSIONS OF SCons BEFORE
742 If you change SConscript files in software that you make
743 available for download or otherwise distribute, other users
744 may try to build your software with an earlier version of
745 SCons that does not have the env.Clone() method. We recommend
746 preparing for this in one of two ways:
748 -- Make your SConscript files backwards-compatible by
749 including the following code near the beginning of your
750 top-level SConstruct file:
752 import SCons.Environment
754 SCons.Environment.Environment.Clone
755 except AttributeError:
756 SCons.Environment.Environment.Clone = \
757 SCons.Environment.Environment.Copy
759 -- Use the EnsureSConsVersion() function to provide a
760 descriptive error message if your SConscript files
761 are executed by an earlier version of SCons:
763 EnsureSConsVersion(0, 96, 93)
765 SCons is developed with an extensive regression test suite, and a
766 rigorous development methodology for continually improving that suite.
767 Because of this, SCons is of sufficient quality that you can use it
770 The interfaces in release 1.0 will *not* be knowingly changed in
771 any new, future 1.x release. If an interface change should ever
772 become necessary due to extraordinary circumstances, the change
773 and an appropriate transition strategy will be documented in these
776 As you use SCons, please heed the following:
778 - Please report any bugs or other problems that you find to our bug
779 tracker at our SourceForge project page:
781 http://sourceforge.net/tracker/?func=add&group_id=30337&atid=398971
783 We have a reliable bug-fixing methodology already in place and
784 strive to respond to problems relatively quickly.
786 - Documentation is spottier than we'd like. You may need to dive
787 into the source code to figure out how to do something. Asking
788 questions on the scons-users mailing list is also welcome. We
789 will be addressing the documentation in upcoming releases, but
790 would be more than glad to have your assistance in correcting this
793 - The "SCons Design" documentation on the SCons web site is very
794 out of date, as we made significant changes to portions of the
795 interface as we figured out what worked and what didn't during the
796 extensive beta implementation. The "SCons Design" document should
797 be used only for historical purposes, or for just an extremely
798 general understanding of SCons' architectural goals.
800 - There may be performance issues. Improving SCons performance
801 is an ongoing priority. If you still find the performance
802 unacceptable, we would very much like to hear from you and learn
803 more about your configuration so we can optimize the right things.
805 - Error messages don't always exist where they'd be helpful.
806 Please let us know about any errors you ran into that would
807 have benefitted from a (more) descriptive message.
809 KNOWN PROBLEMS IN THIS RELEASE:
811 For a complete list of known problems, consult the SCons Issue Tracker
814 http://scons.tigris.org/project_issues.html
816 - Support for parallel builds (-j) does not work on WIN32 systems
817 prior to *official* Python release 2.2 (not 2.2 pre-releases).
819 Prior to Python 2.2, there is a bug in Python's Win32
820 implementation such that when a thread spawns an external command,
821 it blocks all threads from running. This breaks the SCons
822 multithreading architecture used to support -j builds.
824 We have included a patch file, os_spawnv_fix.diff, that you can
825 use if you you want to fix your version of Python to support
826 parallel builds in SCons.
828 - Again, the "SCons Design" documentation on the SCons web site is
829 out of date. Take what you read there with a grain of salt.
831 - On Win32 systems, you must put a space between the redirection
832 characters < and >, and the specified files (or construction
833 variable expansions):
835 command < $SOURCE > $TARGET
837 If you don't supply a space (for example, "<$SOURCE"), SCons will
838 not recognize the redirection.
840 - MSVC .res files are not rebuilt when icons change.
842 - The -c option does not clean up .sconsign files or directories
843 created as part of the build, and also does not clean up
844 SideEffect files (for example, Visual Studio .pdb files).
846 - When using multiple Repositories, changing the name of an include
847 file can cause an old version of the file to be used.
849 - There is currently no way to force use of a relative path (../*)
850 for directories outside the top-level SConstruct file.
852 - The Jar() Builder will, on its second or subsequent invocation,
853 package up the .sconsign files that SCons uses to track signatures.
854 You can work around this by using the SConsignFile() function
855 to collect all of the .sconsign information into a single file
856 outside of the directory being packaged by Jar().
858 - SCons does not currently have a way to detect that an intermediate
859 file has been corrupted from outside and should be rebuilt.
861 - Unicode characters in path names do not work in all circumstances.
863 - SCons does not currently automatically check out SConstruct or
864 SConscript files from SCCS, RCS or BitKeeper.
866 - No support yet for the following planned command-line options:
868 -d -e -l --list-actions --list-derived --list-where
869 -o --override -p -r -R -w --write-filenames
870 -W --warn-undefined-variables
874 Thank you for your interest, and please let us know how we can help
875 improve SCons for your needs.
878 knight at baldmt dot com
879 http://www.baldmt.com/~knight/
881 With plenty of help from the SCons Development team: