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.1 - RELEASE 0.98.1 - Fri, 18 Apr 2008 19:11:58 -0700
25 This is an update to the ninth beta release of SCons. Please consult
26 the CHANGES.txt file for a list of specific changes since last release.
28 Please note the following important changes since release 0.98:
30 -- SCONS NO LONGER SETS THE GNU TOOLCHAIN -fPIC FLAG IN $SHCXXFLAGS
32 The GNU toolchain support in previous versions of SCons would
33 add the -fPIC flag to the $SHCXXFLAGS construction variable.
34 The -fPIC flag has been now been removed from the default
35 $SHCXXFLAGS setting. Instead, the $SHCXXCOM construction variable
36 (the default SCons command line for compiling shared objects
37 from C++ source files) has been changed to add the $SHCCFLAGS
38 variable, which contains the -fPIC flag.
40 This change was made in order to make the behavior of the default
41 C++ compilation line including $SHCCFLAGS consistent with the
42 default C compilation line including $CCFLAGS.
44 This change should have no impact on configurations that use
45 the default $SHCXXCOM command line. It may have an impact on
46 configurations that were using the default $SHCXXFLAGS value
47 *without* the $SHCCFLAGS variable to get the -fPIC flag into a
48 custom command line. You can fix these by adding the $SHCCFLAGS
49 to the custom command line.
51 Adding $SHCCFLAGS is backwards compatible with older SCons
52 releases, although it might cause the -fPIC flag to be repeated
53 on the command line if you execute it on an older version of
54 SCons that sets -fPIC in both the $SHCCLAFGS and $SHCXXFLAGS
55 variables. Duplicating the -fPIC flag on the g++ command line
56 will not cause any compilation problems, but the change to the
57 command line may cause SCons to rebuild object files.
59 -- FORTRAN NOW COMPILES .f FILES WITH gfortran BY DEFAULT
61 The Fortran Tool modules have had a major overhaul with the intent
62 of making them work as-is for most configurations. In general,
63 most configurations that use default settings should not see
64 any noticeable difference.
66 One configuration that has changed is if you have both a gfortran
67 and g77 compiler installed. In this case, previous versions of
68 SCons would, by default, use g77 by default to compile files with
69 a .f suffix, while SCons 0.98.1 will use the gfortran compiler
70 by default. The old behavior may be preserved by explicitly
71 initializing construction environments with the 'g77' Tool module:
73 env = Environment(tools = ['g77', 'default'])
75 The above code is backwards compatible to older versions of SCons.
77 If you notice any other changes in the behavior of default
78 Fortran support, please let us know so we can document them in
79 these release notes for other users.
81 Please note the following important changes since release 0.97.0d20071212:
83 -- SUPPORT FOR PYTHON VERSIONS BEFORE 2.2 IS NOW DEPRECATED
85 SCons now prints the following warning when it is run by any
86 Python 1.5, 2.0 or 2.1 release or sub-release:
88 scons: warning: Support for pre-2.2 Python (VERSION) is deprecated.
89 If this will cause hardship, contact dev@scons.tigris.org.
91 You may disable all warnings about deprecated features by adding
92 the option "--warn=no-deprecated" to the command line or to the
93 $SCONSFLAGS environment variable:
95 $ scons --warn=no-deprecated
97 Using '--warn=no-deprecated' is compatible with earlier versions
100 You may also, as of this version of SCons, disable all warnings
101 about deprecated features by adding the following to any
104 SetOption('warn', 'no-deprecated')
106 You may disable only the specific warning about running under
107 a deprecated Python version by adding the following to any
110 SetOption('warn', 'no-python-version')
112 The warning may also be suppressed on the command line:
114 $ scons --warn=no-python-version
116 Or by specifying the --warn=no-python-version option in the
117 $SCONSFLAGS environment variable.
119 Using SetOption('warn', ...), and the 'no-python-version'
120 command-line option for suppressing this specific warning,
121 are *not* backwards-compatible to earlier versions of SCons.
123 -- THE env.Copy() METHOD IS NOW OFFICIALLY DEPRECATED
125 The env.Copy() method is now officially deprecated and will
126 be removed in a future release. Using the env.Copy() method
127 now generates the following message:
129 scons: warning: The env.Copy() method is deprecated; use the env.Clone() method instead.
131 You may disable all warnings about deprecated features by adding
132 the option "--warn=no-deprecated" to the command line or to the
133 $SCONSFLAGS environment variable:
135 $ scons --warn=no-deprecated
137 Using '--warn=no-deprecated' is compatible with earlier versions
140 You may also, as of this version of SCons, disable all warnings
141 about deprecated features by adding the following to any
144 SetOption('warn', 'no-deprecated')
146 You may disable only the specific warning about the deprecated
147 env.Copy() method by adding the following to any SConscript
150 SetOption('warn', 'no-deprecated-copy')
152 The warning may also be suppressed on the command line:
154 $ scons --warn=no-deprecated-copy
156 Or by specifying the --warn=no-deprecated-copy option in the
157 $SCONSFLAGS environment variable.
159 Using SetOption('warn', ...), and the 'no-deprecated-copy'
160 command-line option for suppressing this specific warning,
161 are *not* backwards-compatible to earlier versions of SCons.
163 -- THE --debug=dtree, --debug=stree AND --debug=tree OPTIONS ARE DEPRECATED
165 The --debug=dtree, --debug=stree and --debug=tree methods
166 are now officially deprecated and will be removed in a
167 future release. Using these options now generate a warning
168 message recommending use of the --tree=derived, --tree=all,status
169 and --tree=all options, respectively.
171 You may disable these warnings, and all warnings about
172 deprecated features, by adding the option "--warn=no-deprecated"
173 to the command line or to the $SCONSFLAGS environment
176 $ scons --warn=no-deprecated
178 Using '--warn=no-deprecated' is compatible with earlier versions
181 -- THE TargetSignatures() AND SourceSignatures() FUNCTIONS ARE DEPRECATED
183 The TargetSignatures() and SourceSignatures() functions,
184 and their corresponding env.TargetSignatures() and
185 env.SourceSignatures() methods, are now officially deprecated
186 and will be be removed in a future release. Using ahy of
187 these functions or methods now generates a message
188 similar to the following:
190 scons: warning: The env.TargetSignatures() method is deprecated;
191 convert your build to use the env.Decider() method instead.
193 You may disable all warnings about deprecated features by adding
194 the option "--warn=no-deprecated" to the command line or to the
195 $SCONSFLAGS environment variable:
197 $ scons --warn=no-deprecated
199 Using '--warn=no-deprecated' is compatible with earlier versions
202 You may also, as of this version of SCons, disable all warnings
203 about deprecated features by adding the following to any
206 SetOption('warn', 'no-deprecated')
208 You may disable only the specific warning about the use of
209 TargetSignatures() or SourceSignatures() by adding the
210 following to any SConscript file:
212 SetOption('warn', 'no-deprecated-target-signatures')
213 SetOption('warn', 'no-deprecated-source-signatures')
215 The warnings may also be suppressed on the command line:
217 $ scons --warn=no-deprecated-target-signatures --warn=no-deprecated-source-signatures
219 Or by specifying these options in the $SCONSFLAGS environment
222 Using SetOption('warn', ...), or the command-line options
223 for suppressing these warnings, is *not* backwards-compatible
224 to earlier versions of SCons.
226 -- File(), Dir() and Entry() NOW RETURN A LIST WHEN THE INPUT IS A SEQUENCE
228 Previously, if these methods were passed a list, the list was
229 substituted and stringified, then passed as a single string to
230 create a File/Dir/Entry Node. This rarely if ever worked with
231 more than one element in the list. They now return a list of
232 Nodes when passed a list.
234 One case that works differently now is a passing in a
235 single-element sequence; that formerly was stringified
236 (returning its only element) and then a single Node would be
237 returned. Now a single-element list containing the Node will
238 be returned, for consistency.
240 -- THE env.subst() METHOD NOW RETURNS A LIST WHEN THE INPUT IS A SEQUENCE
242 The env.subst() method now returns a list with the elements
243 expanded when given a list as input. Previously, the env.subst()
244 method would always turn its result into a string.
246 This behavior was changed because it interfered with being able
247 to include things like lists within the expansion of variables
248 like $CPPPATH and then have SCons understand that the elements
249 of the "internal" lists still needed to be treated separately.
250 This would cause a $CPPPATH list like ['subdir1', 'subdir']
251 to show up in a command line as "-Isubdir1 subdir".
253 -- THE Jar() BUILDER NOW USES THE Java() BUILDER CLASSDIR BY DEFAULT
255 By default, the Jar() Builder will now use the class directory
256 specified when the Java() builder is called. So the following
259 classes = env.Java('classes', 'src')
260 env.Jar('out.jar', classes)
262 Will cause "-C classes" to be passed the "jar" command invocation,
263 and the Java classes in the "out.jar" file will not be prefixed
266 Explicitly setting the $JARCHDIR variable overrides this default
267 behavior. The old behavior of not passing any -C option to the
268 "jar" command can be preserved by explicitly setting $JARCHDIR
271 env = Environment(JARCHDIR = None)
273 The above setting is compatible with older versions of SCons.
275 Please note the following important changes since release 0.97.0d20070918:
277 -- SCons REDEFINES PYTHON open() AND file() ON Windows TO NOT PASS
278 ON OPEN FILE HANDLES TO CREATED PROCESSES
280 On Windows systems, SCons now redefines the Python open()
281 and file() functions so that, if the Python Win32 extensions
282 are available, the file handles for any opened files will *not*
283 be inherited by subprocesses, such as the spawned compilers and
284 other tools invoked to build the software.
286 This prevents certain race conditions where a file handle for
287 a file opened by Python (either in a Python function action,
288 or directly in a SConscript file) could be inherited and help
289 open by a subprocess, interfering with the ability of other
290 processes to create or modify the file.
292 In general, this should not cause problems for the vast majority
293 of configurations. The only time this would be a problem would be
294 in the unlikely event that a process spawned by SCons specifically
295 *expected* to use an inherited file handle opened by SCons.
297 If the Python Win32 extensions are not installed or are an
298 earlier version that does not have the ability to disable file
299 handle inheritance, SCons will print a warning message when the
300 -j option is used. The warning message may be suppressed by
301 specifying --warn=no-parallel-support.
303 Please note the following important changes since release 0.97.0d20070809:
305 -- "content" SIGNATURES ARE NOW THE DEFAULT BEHAVIOR
307 The default behavior of SCons is now to use the MD5 checksum of
308 all file contents to decide if any files have changed and should
309 cause rebuilds of their source files. This means that SCons may
310 decide not to rebuild "downstream" targets if a a given input
311 file is rebuilt to the exact same contents as the last time.
312 The old behavior may preserved by explicity specifying:
314 TargetSignatures("build")
316 In any of your SConscript files.
318 -- TARGETS NOW IMPLICITLY DEPEND ON THE COMMAND THAT BUILDS THEM
320 For all targets built by calling external commands (such as a
321 compiler or other utility), SCons now adds an implicit dependency
322 on the command(s) used to build the target.
324 This will cause rebuilds of all targets built by external commands
325 when running SCons in a tree built by previous version of SCons,
326 in order to update the recorded signatures.
328 The old behavior of not having targets depend on the external
329 commands that build them can be preserved by setting a new
330 $IMPLICIT_COMMAND_DEPENDENCIES construction variable to a
333 env = Environment(IMPLICIT_COMMAND_DEPENDENCIES = 0)
335 or by adding Ignore() calls for any targets where the behavior
338 Ignore('/usr/bin/gcc', 'foo.o')
340 Both of these settings are compatible with older versions
343 -- CHANGING SourceSignature() MAY CAUSE "UNECESSARY" REBUILDS
345 If you change the SourceSignature() value from 'timestamp' to
346 'MD5', SCons will now rebuild targets that were already up-to-date
347 with respect to their source files.
349 This will happen because SCons did not record the content
350 signatures of the input source files when the target was last
351 built--it only recorded the timestamps--and it must record them
352 to make sure the signature information is correct. However,
353 the content of source files may have changed since the last
354 timestamp build was performed, and SCons would not have any way to
355 verify that. (It would have had to open up the file and record
356 a content signature, which is one of the things you're trying to
357 avoid by specifying use of timestamps....) So in order to make
358 sure the built targets reflect the contents of the source files,
359 the targets must be rebuilt.
361 Change the SourceSignature() value from 'MD5' to 'timestamp'
362 should correctly not rebuild target files, because the timestamp
363 of the files is always recorded.
365 In previous versions of SCons, changing the SourceSignature()
366 value would lead to unpredictable behavior, usually including
369 -- THE Return() FUNCTION NOW ACTUALLY RETURNS IMMEDIATELY
371 The Return() function now immediately stops processing the
372 SConscript file in which it appears and returns the values of the
373 variables named in its arguments. It used to continue processing
374 the rest of the SConscript file, and then return the values of the
375 specified variables at the point the Return() function was called.
377 The old behavior may be requested by adding a "stop=False"
378 keyword argument to the Return() call:
380 Return('value', stop=False)
382 The "stop=" keyword argument is *not* compatible with SCons
383 versions 0.97.0d20070809 or earlier.
385 Please note the following important changes since release 0.97:
387 -- env.CacheDir() NOW ONLY AFFECTS CONSTRUCTION ENVIRONMENT TARGETS
389 The env.CacheDir() method now only causes derived files to be
390 retrieved from the specified cache directory for targets built
391 with the specified specified construction environment ("env").
393 Previously, any call to env.CacheDir() or CacheDir() would modify
394 a global setting and cause all built targets to be retrieved
395 from the specified cache directory. This behavior was changed so
396 that env.CacheDir() would be consistent with other construction
397 environment methods, which only affect targets built with the
398 specified construction environment.
400 The old behavior of changing the global behavior may be preserved
401 by changing any env.CacheDir() calls to:
403 CacheDir('/path/to/cache/directory')
405 The above change is backwards-compatible and works in all earlier
406 versions of SCons that support CacheDir().
408 -- INTERPRETATION OF SUFFIX-LESS SOURCE ARGUMENTS HAS CHANGED
410 The interpretation of source arguments (files) without suffixes
411 has changed in one specific configuration.
413 Previously, if a Builder had a src_suffix specified (indicating
414 that source files without suffixes should have that suffix
415 appended), the suffix would only be applied to suffix-less source
416 arguments if the Builder did *not* have one or more attached
417 source Builders (that is, the Builder was not a "multi-stage"
418 Builder). So in the following configuration:
420 build_foo = Builder(src_suffix = '.foo')
421 build_bar = Builder(src_suffix = '.bar',
422 src_builder = build_bar)
424 env = Environment(BUILDERS = {
429 env.Foo('tgt1', 'src1')
430 env.Bar('tgt2', 'src2')
432 SCons would have expected to find a source file 'src1.foo' for the
433 env.Foo() call, but a source file 'src2' for the env.Bar() call.
435 This behavior has now been made consistent, so that the two
436 above calls would expect source files named 'src1.foo' and
437 'src2.bar', respectively.
439 Note that, if genuinely desired, the old behavior of building
440 from a source file without a suffix at all (when the Builder has
441 a src_suffix *and* a src_builder) can be specified explicity by
442 turning the string into a File Node directly:
444 env.Bar('tgt2', File('src2'))
446 The above use of File() is backwards-compatible and will work
447 on earlier versions of SCons.
449 -- THE DEFAULT EXECUTION PATH FOR Solaris HAS CHANGED
451 On Solaris systems, SCons now adds the "/opt/SUNWspro/bin"
452 directory to the default execution $PATH variable before the
453 "/usr/ccs/bin" directory. This was done to reflect the fact
454 that /opt/SUNWspro/ is the default for SUN tools, but it may
455 cause a different compiler to be used if you have compilers
456 installed in both directories.
458 -- GENERATED config.h FILES NOW SAY "#define HAVE_{FEATURE} 1"
460 When generating a "config.h" file, SCons now defines values that
461 record the existence of a feature with a "1" value:
463 #define HAVE_FEATURE 1
465 Instead of printing the line without a "1", as it used to:
469 This should not cause any problems in the normal use of "#ifdef
470 HAVE_{FEATURE}" statements interpreted by a C preprocessor, but
471 might cause a compatibility issue if a script or other utility
472 looks for an exact match of the previous text.
474 Please note the following planned, future changes:
476 -- THE Options OBJECT AND RELATED FUNCTIONS WILL BE DEPRECATED
478 The Options object is being replaced by a new Variables
479 object, which uses a new Variables.AddVariable() method
480 where the previous interface used Options.AddOptions().
482 Similarly, the following utility functions are being replaced
483 by the following similarly-named functions:
485 BoolOption() BoolVariable()
486 EnumOption() EnumVariable()
487 ListOption() ListVariable()
488 PackageOption() PackageVariable()
489 PathOption() PathVariable()
491 And also related, the options= keyword argument when creating
492 construction environments with the Environment() functions is
493 being replaced with a variables= keyword argument.
495 In some future release a deprecation warning will be added to
496 existing uses of the Options object, its methods, the above
497 utility functions, and the options= keyword argument of the
498 Environment() function. At some point after the deprecation
499 warning is added, the Options object, related functions and
500 options= keyword argument will be removed entirely.
502 You can prepare for this by changing all your uses of the Options
503 object and related functions to the Variables object and the new
504 function names, and changing any uses of the options= keyword
505 argument to variables=.
507 NOTE: CONVERTING TO USING THE NEW Variables OBJECT OR THE
508 RELATED *Variable() FUNCTIONS, OR USING THE NEW variable=
509 KEYWORD ARGUMENT, IS NOT BACKWARDS COMPATIBLE TO VERSIONS OF
510 SCons BEFORE 0.98. YOUR SConscript FILES WILL NOT WORK ON
511 EARLIER VERSIONS OF SCons AFTER MAKING THIS CHANGE.
513 If you change SConscript files in software that you make available
514 for download or otherwise distribute, other users may try to
515 build your software with an earlier version of SCons that does
516 not have the Variables object or related *Variable() functions.
517 We recommend preparing for this in one of two ways:
519 -- Make your SConscript files backwards-compatible by
520 modifying your calls with Python try:-except: blocks
524 vars = Variables('custom.py', ARGUMENTS)
526 BoolVariable('WARNINGS', 'cmopile with -Wall', 1),
527 EnumVariable('DEBUG', 'debug version', 'no'
528 allowed_values=('yes', 'no', 'full'),
529 map={}, ignorecase=0),
530 ListVariable('SHAREDLIBS',
531 'libraries to build shared',
533 names = list_of_libs),
534 PackageVariable('X11',
537 PathVariable('QTDIR', 'root of Qt', qtdir),
540 vars = Options('custom.py', ARGUMENTS)
542 BoolOption('WARNINGS', 'cmopile with -Wall', 1),
543 EnumOption('DEBUG', 'debug version', 'no'
544 allowed_values=('yes', 'no', 'full'),
545 map={}, ignorecase=0),
546 ListOption('SHAREDLIBS',
547 'libraries to build shared',
549 names = list_of_libs),
553 PathOption('QTDIR', 'root of Qt', qtdir),
556 Additionally, you can check for availability of the new
557 variables= keyword argument as follows:
560 env = Environment(variables=vars)
562 env = Environment(options=vars)
564 (Note that we plan to maintain the existing Options object
565 name for some time, to ensure backwards compatibility,
566 so in practice it may be easier to just continue to use
567 the old name until you're reasonably sure you won't have
568 people trying to build your software with versions of
569 SCons earlier than 0.98.1.)
571 -- Use the EnsureSConsVersion() function to provide a
572 descriptive error message if your SConscript files
573 are executed by an earlier version of SCons:
575 EnsureSConsVersion(0, 98, 1)
577 -- THE BuildDir() METHOD AND FUNCTION WILL BE DEPRECATED
579 The env.BuildDir() method and BuildDir() function are being
580 replaced by the new env.VariantDir() method and VariantDir()
583 In some future release a deprecation warning will be added
584 to existing uses of the env.BuildDir() method and BuildDir()
585 function. At some point after the deprecation warning, the
586 env.Builder() method and BuildDir() function will either
587 be removed entirely or have their behavior changed.
589 You can prepare for this by changing all your uses of the
590 env.BuildDir() method to env.VariantDir() and uses of the
591 global BuildDir() function to VariantDir(). If you use a
592 named keyword argument of "build_dir" when calling
593 env.BuildDir() or BuildDir():
595 env.BuildDir(build_dir='opt', src_dir='src')
597 The keyword must be changed to "variant_dir":
599 env.VariantDir(variant_dir='opt', src_dir='src')
601 NOTE: CHANGING USES OF env.BuildDir() AND BuildDir() to
602 env.VariantDir() AND VariantDir() IS NOT BACKWARDS COMPATIBLE
603 TO VERSIONS OF SCons BEFORE 0.98. YOUR SConscript FILES
604 WILL NOT WORK ON EARLIER VERSIONS OF SCons AFTER MAKING
607 If you change SConscript files in software that you make
608 available for download or otherwise distribute, other users
609 may try to build your software with an earlier version of
610 SCons that does not have the env.VariantDir() method or
611 VariantDir() fnction. We recommend preparing for this in
614 -- Make your SConscript files backwards-compatible by
615 including the following code near the beginning of your
616 top-level SConstruct file:
618 import SCons.Environment
620 SCons.Environment.Environment.VariantDir
621 except AttributeError:
622 SCons.Environment.Environment.VariantDir = \
623 SCons.Environment.Environment.BuildDir
625 -- Use the EnsureSConsVersion() function to provide a
626 descriptive error message if your SConscript files
627 are executed by an earlier version of SCons:
629 EnsureSConsVersion(0, 98)
631 -- THE SConscript() "build_dir" KEYWORD ARGUMENT WILL BE DEPRECATED
633 The "build_dir" keyword argument of the SConscript function
634 and env.SConscript() method are being replaced by a new
635 "variant_dir" keyword argument.
637 In some future release a deprecation warning will be added
638 to existing uses of the SConscript()/env.SConscript()
639 "build_dir" keyword argument. At some point after the
640 deprecation warning, support for this keyword argument will
643 You can prepare for this by changing all your uses of the
644 SConscript()/env.SConscript() 'build_dir" keyword argument:
646 SConscript('src/SConscript', build_dir='opt')
648 To use the new "variant_dir" keyword argument:
650 SConscript('src/SConscript', variant_dir='opt')
652 NOTE: USING THE NEW "variant_dir" KEYWORD IS NOT BACKWARDS
653 COMPATIBLE TO VERSIONS OF SCons BEFORE 0.98. YOUR SConscript
654 FILES WILL NOT WORK ON EARLIER VERSIONS OF SCons AFTER
657 If you change SConscript files in software that you make
658 available for download or otherwise distribute, other users
659 may try to build your software with an earlier version of
660 SCons that does not support the "variant_dir" keyword.
662 If you can insist that users use a recent version of SCons
663 that supports "variant_dir", we recommend using the
664 EnsureSConsVersion() function to provide a descriptive error
665 message if your SConscript files are executed by an earlier
668 EnsureSConsVersion(0, 98)
670 If you want to make sure that your SConscript files will
671 still work with earlier versions of SCons, then your best
672 bet is to continue to use the "build_dir" keyword until the
673 support is removed (which, in all likelihood, won't happen
674 for quite some time).
676 -- SCANNER NAMES HAVE BEEN DEPRECATED AND WILL BE REMOVED
678 Several internal variable names in SCons.Defaults for various
679 pre-made default Scanner objects have been deprecated and will
680 be removed in a future revision. In their place are several new
681 global variable names that are now part of the publicly-supported
684 NEW NAME DEPRECATED NAME
685 -------- ----------------------------
686 CScanner SCons.Defaults.CScan
687 DSCanner SCons.Defaults.DScan
688 SourceFileScanner SCons.Defaults.ObjSourceScan
689 ProgramScanner SCons.Defaults.ProgScan
691 Of these, only ObjSourceScan was probably used at all, to add
692 new mappings of file suffixes to other scanners for use by the
693 Object() Builder. This should now be done as follows:
695 SourceFileScanner.add_scanner('.x', XScanner)
697 -- THE env.Copy() METHOD WILL CHANGE OR GO AWAY ENTIRELY
699 The env.Copy() method (to make a copy of a construction
700 environment) is being replaced by the env.Clone() method.
702 As of SCons 0.98, a deprecation warning has been added to
703 current uses of the env.Copy() method. At some point in
704 the future, the env.Copy() method will either be removed
705 entirely or have its behavior changed.
707 You can prepare for this by changing all your uses of env.Copy()
708 to env.Clone(), which has the exact same calling arguments.
710 NOTE: CHANGING USES OF env.Copy() TO env.Clone() WILL MAKE
711 YOUR SConscript FILES NOT WORK ON VERSIONS OF SCons BEFORE
714 If you change SConscript files in software that you make
715 available for download or otherwise distribute, other users
716 may try to build your software with an earlier version of
717 SCons that does not have the env.Clone() method. We recommend
718 preparing for this in one of two ways:
720 -- Make your SConscript files backwards-compatible by
721 including the following code near the beginning of your
722 top-level SConstruct file:
724 import SCons.Environment
726 SCons.Environment.Environment.Clone
727 except AttributeError:
728 SCons.Environment.Environment.Clone = \
729 SCons.Environment.Environment.Copy
731 -- Use the EnsureSConsVersion() function to provide a
732 descriptive error message if your SConscript files
733 are executed by an earlier version of SCons:
735 EnsureSConsVersion(0, 96, 93)
737 SCons is developed with an extensive regression test suite, and a
738 rigorous development methodology for continually improving that suite.
739 Because of this, SCons is of sufficient quality that you can use it
740 for real work. The "beta" status of the release reflects that we
741 still may change interfaces in future releases, which may require
742 modifications to your SConscript files. We strive to hold these
743 changes to a minimum.
745 Nevertheless, please heed the following disclaimers:
747 - Please report any bugs or other problems that you find to our bug
748 tracker at our SourceForge project page:
750 http://sourceforge.net/tracker/?func=add&group_id=30337&atid=398971
752 We have a reliable bug-fixing methodology already in place and
753 strive to respond to problems relatively quickly.
755 - Documentation is spottier than we'd like. You may need to dive
756 into the source code to figure out how to do something. Asking
757 questions on the scons-users mailing list is also welcome. We
758 will be addressing the documentation in upcoming releases, but
759 would be more than glad to have your assistance in correcting this
762 In particular, the "SCons Design" documentation on the SCons web
763 site is currently out of date, as we made significant changes to
764 portions of the interface as we figured out what worked and what
765 didn't during implementation.
767 - There may be performance issues. Improving SCons performance
768 is an ongoing priority. If you still find the performance
769 unacceptable, we would very much like to hear from you and learn
770 more about your configuration so we can optimize the right things.
772 - Error messages don't always exist where they'd be helpful.
773 Please let us know about any errors you ran into that would
774 have benefitted from a (more) descriptive message.
776 KNOWN PROBLEMS IN THIS RELEASE:
778 For a complete list of known problems, consult the SCons Issue Tracker
781 http://scons.tigris.org/project_issues.html
783 - Support for parallel builds (-j) does not work on WIN32 systems
784 prior to *official* Python release 2.2 (not 2.2 pre-releases).
786 Prior to Python 2.2, there is a bug in Python's Win32
787 implementation such that when a thread spawns an external command,
788 it blocks all threads from running. This breaks the SCons
789 multithreading architecture used to support -j builds.
791 We have included a patch file, os_spawnv_fix.diff, that you can
792 use if you you want to fix your version of Python to support
793 parallel builds in SCons.
795 - Again, the "SCons Design" documentation on the SCons web
796 site is currently out of date. Take what you read there with a
799 - On Win32 systems, you must put a space between the redirection
800 characters < and >, and the specified files (or construction
801 variable expansions):
803 command < $SOURCE > $TARGET
805 If you don't supply a space (for example, "<$SOURCE"), SCons will
806 not recognize the redirection.
808 - MSVC .res files are not rebuilt when icons change.
810 - The -c option does not clean up .sconsign files or directories
811 created as part of the build, and also does not clean up
812 SideEffect files (for example, Visual Studio .pdb files).
814 - When using multiple Repositories, changing the name of an include
815 file can cause an old version of the file to be used.
817 - There is currently no way to force use of a relative path (../*)
818 for directories outside the top-level SConstruct file.
820 - The Jar() Builder will, on its second or subsequent invocation,
821 package up the .sconsign files that SCons uses to track signatures.
822 You can work around this by using the SConsignFile() function
823 to collect all of the .sconsign information into a single file
824 outside of the directory being packaged by Jar().
826 - SCons does not currently have a way to detect that an intermediate
827 file has been corrupted from outside and should be rebuilt.
829 - Unicode characters in path names do not work in all circumstances.
831 - SCons does not currently automatically check out SConstruct or
832 SConscript files from SCCS, RCS or BitKeeper.
834 - No support yet for the following planned command-line options:
836 -d -e -l --list-actions --list-derived --list-where
837 -o --override -p -r -R -w --write-filenames
838 -W --warn-undefined-variables
842 Thank you for your interest, and please let us know how we can help
843 improve SCons for your needs.
846 knight at baldmt dot com
847 http://www.baldmt.com/~knight/
849 With plenty of help from the SCons Development team: