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
25 This is a pre-release for testing the eighth beta release of SCons.
26 Please consult the CHANGES.txt file for a list of specific changes
29 Please note the following important changes since release 0.96:
31 -- DIRECTORY TREES ARE NO LONGER AUTOMATICALLY SCANNED FOR CHANGES
33 Custom builders and Command() calls that accept directories as
34 source arguments no longer scan entire on-disk directory trees
35 by default. This means that their targets will not be
36 automatically rebuilt if a file changes on disk, and SCons does
37 *not* already know about. Note that the targets will still be
38 rebuilt correctly if a file changes that SCons already knows
39 about due to a Builder or other call.
41 The existing behavior of scanning on-disk directory trees for
42 any changed file can be maintained by passing the new DirScanner
43 global directory scanner as the source_scanner keyword argument
46 bld = Builder("build < $SOURCE > $TARGET",
47 source_scanner = DirScanner)
49 The same keyword argument can also be supplied to any Command()
50 calls that need to scan directory trees on-disk for changed files:
52 env.Command("archive.out", "directory",
53 "archiver -o $TARGET $SOURCE",
54 source_scanner = DirScanner)
56 This change was made because scanning directories by default
57 could cause huge slowdowns if a configurable directory like /usr
58 or /usr/local was passed as the source to a Builder or Command()
59 call, in which case SCons would scan the entire directory tree.
61 -- CACHED Configure() RESULTS ARE STORED IN A DIFFERENT FILE
63 The Configure() subsystem now stores its cached results in a
64 different file. This may cause configuration tests to be re-run
65 the first time after you install 0.97.
67 -- setup.py NOW INSTALLS MAN PAGES ON UNIX AND Linux SYSTEMS
69 The SCons setup.py script now installs the "scons.1" and
70 "sconsign.1" man pages on UNIX and Linux systems. A
73 -- ParseConfig() METHOD ADDS LIBRARY FILE NAMES TO THE $LIBS VARIABLE
75 The ParseConfig() method now adds library file names returned
76 by the specified *-config command to the $LIBS construction
77 variable, instead of returning them (the same way it handles
80 -- ParseConfig() METHOD DOESN'T ADD DUPLICATES TO CONSTRUCTION VARIABLES
82 By default, the ParseConfig() method now avoids adding duplicate
83 entries to construction variables. The old behavior may be
84 specified using a new "unique=0" keyword argument.
86 -- WINDOWS %TEMP% and %TMP% VARIABLES ARE PROPAGATED AUTOMATICALLY
88 The %TEMP% and %TMP% external environment variables are now
89 propagated automatically to the command execution environment on
92 -- VISUAL STUDIO ATL AND MFC DIRECTORIES NOT ADDED BY DEFAULT
94 When compiling with Microsoft Visual Studio, SCons no longer
95 adds the ATL and MFC directories to the INCLUDE and LIB
96 environment variables by default. If you want these directories
97 included in your environment variables, you should now set the
98 $MSVS_USE_MFC_DIRS *construction* variable when initializing
101 env = Environment(MSVS_USE_MFC_DIRS = 1)
103 -- BUILDERS RETURN A LIST-LIKE OBJECT, NOT A REGULAR LIST
105 Builders calls now return an object that behaves like a list
106 (and which provides some other functionality), not an underlying
107 Python list. In general, this should not cause any problems,
108 although it introduces a subtle change in the following behavior:
110 obj += env.Object('foo.c')
112 If "obj" is a list, Python will no longer update the "obj" in
113 place, because the return value from env.Object() is no longer
114 the same type. Python will instead allocate a new object and
115 assign the local variable "obj" to it. If "obj" is defined in
116 an SConscript file that calls another SConscript file containing
117 the above code, "obj" in the first SConscript file will not
120 You can guarantee that a list will be updated in place regardless
121 of which SConscript file defines it and which adds to it by
122 using the list append() method as follows:
124 obj.append(env.Object('foo.c'))
126 -- OUTPUT OF Configure() SUBSYSTEM CHANGED SLIGHTLY
128 The Configure() subsystem now reports tests results as "yes" and
129 "no" instead of "ok" and "failed." This might interfere with any
130 scripts that automatically parse the Configure() output from SCons.
132 -- DEPRECATED GLOBAL FUNCTIONS HAVE BEEN REMOVED
134 The following deprecated global functions have been removed:
135 ParseConfig(), SetBuildSignatureType(), SetContentSignatureType(),
136 SetJobs() and GetJobs().
138 -- DEPRECATED "validater" KEYWORD HAS BEEN REMOVED
140 The deprecated "validater" keyword to the Options.Add() method
143 Please note the following important changes since release 0.95:
145 -- BUILDERS NOW ALWAYS RETURN A LIST OF TARGETS
147 All Builder calls (both built-in like Program(), Library(),
148 etc. and customer Builders) now always return a list of target
149 Nodes. If the Builder only builds one target, the Builder
150 call will now return a list containing that target Node, not
151 the target Node itself as it used to do.
153 This change should be invisibile to most normal uses of the
154 return values from Builder calls. It will cause an error if the
155 SConscript file was performing some direct manipulation of the
156 returned Node value. For example, an attempt to print the name
157 of a target returned by the Object() Builder:
159 target = Object('foo.c')
163 Will now need to access the first element in the list returned by
166 target = Object('foo.c')
170 This change was introduced to make the data type returned by Builder
171 calls consistent (always a list), regardless of platform or number
174 -- DEFAULT SConsignFile() DATABASE SCHEME HAS CHANGED
176 The SConsignFile() function now uses an internally-supplied
177 SCons.dblite module as the default DB scheme for the .sconsign file.
178 If you are using the SConsignFile() function without an explicitly
179 specified dbm_module argument, this will cause all of your targets
180 to be recompiled the first time you use SCons 0.96. To preserve the
181 previous behavior, specify the "anydbm" module explicitly:
184 SConsignFile('.sconsign_file_name', anydbm)
186 -- INTERNAL .sconsign FILE FORMAT HAS CHANGED
188 The internal format of .sconsign files has been changed. This might
189 cause warnings about "ignoring corrupt .sconsign files" and rebuilds
190 when you use SCons 0.96 for the first time in a tree that was
191 previously built with SCons 0.95 or earlier.
193 -- INTERFACE CHANGE OF scan_check FUNCTION TO CUSTOM SCANNERS
195 The scan_check function that can be supplied to a custom Scanner now
196 must take two arguments, the Node to be checked and a construction
197 environment. It previously only used the Node as an argument.
199 -- DEFAULT SCANNERS NO LONGER HEED INTERNAL Scanner.add_skey() METHOD
201 The internal Scanner.add_skey() method no longer works for the
202 default scanners, which now use construction variables to hold their
203 lists of suffixes. If you had a custom Tool specification that was
204 reaching into the internals in this way to add a suffix to one of
205 the following scanner, you must now add the suffix to a construction
206 environment through which you plan to call the scanner, as follows:
208 CScan.add_skey('.x') => env.Append(CPPSUFFIXES = ['.x'])
209 DScan.add_skey('.x') => env.Append(DSUFFIXES = ['.x'])
210 FortranScan.add_skey('.x') => env.Append(FORTRANSUFFIXES = ['.x'])
212 -- KEYWORD ARGUMENTS TO Builder() HAVE BEEN REMOVED
214 The "node_factory" and "scanner" keyword arguments to the Builder()
215 function have been removed. In their place, the separate and more
216 flexible "target_factory," "source_factory," "target_scanner" and
217 "source scanner" keywords should be used instead.
219 -- ALL-DIGIT FILE "EXTENSIONS" ARE NOW PART OF THE FILE BASENAME
221 SCons now treats file "extensions" that contain all digits (for
222 example, "file.123") as part of the file basename, for easier
223 handling of version numbers in the names of shared libraries
224 and other files. Builders will now add their file extensions to
225 file names specified with all-digit extensions. If you need to
226 generate a file with an all-digit extension using a Builder that
227 adds a file extension, you can preserve the previous behavior by
228 wrapping the file name in a File() call.
230 -- Append()/Prepend() METHODS CHANGED WHEN USING UserList OBJECTS
232 The behavior of the env.Append() and env.Prepend() methods has
233 changed when appending a string value to a UserList, or vice versa.
234 They now behave like normal Python addition of a string to
235 a UserList. Given an initialization and an env.Append() call like:
237 env = Environment(VAR1=UserList(['foo']), VAR2='foo')
238 env.Append(VAR1='bar', VAR2=UserList(['bar'])
240 The resulting values of $VAR1 and $VAR2 will now be ['foo', 'b',
241 'a', 'r'] and ['f', 'o', 'o', 'bar'], respectively. This is because
242 Python UserList objects treat strings as sequences of letters when
243 adding them to the value of the UserList.
245 The old behavior of yielding $VAR1 and $VAR2 values of ['foo',
246 'bar'] when either variable is a UserList object now requires that
247 the string variables be enclosed in a list:
249 env = Environment(VAR1=UserList(['foo']), VAR2=['foo'])
250 env.Append(VAR1='bar', VAR2=UserList(['bar']))
252 Note that the SCons behavior when appending to normal lists has
253 *not* changed, and the behavior of all of the default values that
254 SCons uses to initialize all construction variables has *not*
255 changed. This change *only* affects any cases where you explicitly
256 use UserList objects to initialize or append to a variable.
258 Please note the following planned, future changes:
260 -- SCANNER NAMES HAVE BEEN DEPRECATED AND WILL BE REMOVED
262 Several internal variable names in SCons.Defaults for various
263 pre-made default Scanner objects have been deprecated and will
264 be removed in a future revision. In their place are several new
265 global variable names that are now part of the publicly-supported
268 NEW NAME DEPRECATED NAME
269 -------- ----------------------------
270 CScanner SCons.Defaults.CScan
271 DSCanner SCons.Defaults.DScan
272 SourceFileScanner SCons.Defaults.ObjSourceScan
273 ProgramScanner SCons.Defaults.ProgScan
275 Of these, only ObjSourceScan was probably used at all, to add
276 new mappings of file suffixes to other scanners for use by the
277 Object() Builder. This should now be done as follows:
279 SourceFileScanner.add_scanner('.x', XScanner)
281 SCons is developed with an extensive regression test suite, and a
282 rigorous development methodology for continually improving that suite.
283 Because of this, SCons is of sufficient quality that you can use it
284 for real work. The "beta" status of the release reflects that we
285 still may change interfaces in future releases, which may require
286 modifications to your SConscript files. We strive to hold these
287 changes to a minimum.
289 Nevertheless, please heed the following disclaimers:
291 - Please report any bugs or other problems that you find to our bug
292 tracker at our SourceForge project page:
294 http://sourceforge.net/tracker/?func=add&group_id=30337&atid=398971
296 We have a reliable bug-fixing methodology already in place and
297 strive to respond to problems relatively quickly.
299 - Documentation is spottier than we'd like. You may need to dive
300 into the source code to figure out how to do something. Asking
301 questions on the scons-users mailing list is also welcome. We
302 will be addressing the documentation in upcoming releases, but
303 would be more than glad to have your assistance in correcting this
306 In particular, the "SCons Design" documentation on the SCons web
307 site is currently out of date, as we made significant changes to
308 portions of the interface as we figured out what worked and what
309 didn't during implementation.
311 - There may be performance issues. Improving SCons performance
312 is an ongoing priority. If you still find the performance
313 unacceptable, we would very much like to hear from you and learn
314 more about your configuration so we can optimize the right things.
316 - Error messages don't always exist where they'd be helpful.
317 Please let us know about any errors you ran into that would
318 have benefitted from a (more) descriptive message.
320 KNOWN PROBLEMS IN THIS RELEASE:
322 For a complete list of known problems, consult the SCons bug tracker
325 http://sourceforge.net/tracker/?atid=398971&group_id=30337&func=browse
327 - Support for parallel builds (-j) does not work on WIN32 systems
328 prior to *official* Python release 2.2 (not 2.2 pre-releases).
330 Prior to Python 2.2, there is a bug in Python's Win32
331 implementation such that when a thread spawns an external command,
332 it blocks all threads from running. This breaks the SCons
333 multithreading architecture used to support -j builds.
335 We have included a patch file, os_spawnv_fix.diff, that you can
336 use if you you want to fix your version of Python to support
337 parallel builds in SCons.
339 - Again, the "SCons Design" documentation on the SCons web
340 site is currently out of date. Take what you read there with a
343 - On Win32 systems, you must put a space between the redirection
344 characters < and >, and the specified files (or construction
345 variable expansions):
347 command < $SOURCE > $TARGET
349 If you don't supply a space (for example, "<$SOURCE"), SCons will
350 not recognize the redirection.
352 - MSVC .res files are not rebuilt when icons change.
354 - The -c option does not clean up .sconsign files or directories
355 created as part of the build, and also does not clean up
356 SideEffect files (for example, Visual Studio .pdb files).
358 - Switching content signatures from "MD5" to "timestamp" and back
359 again can cause unusual errors. These errors can be cleared up by
360 removing all .sconsign files.
362 - When using multiple Repositories, changing the name of an include
363 file can cause an old version of the file to be used.
365 - There is currently no way to force use of a relative path (../*)
366 for directories outside the top-level SConstruct file.
368 - The Jar() Builder will, on its second or subsequent invocation,
369 package up the .sconsign files that SCons uses to track signatures.
370 You can work around this by using the SConsignFile() function
371 to collect all of the .sconsign information into a single file
372 outside of the directory being packaged by Jar().
374 - SCons does not currently have a way to detect that an intermediate
375 file has been corrupted from outside and should be rebuilt.
377 - Unicode characters in path names do not work in all circumstances.
379 - A stray source file in a BuildDir can prevent targets from being
380 (re)built when they should.
382 - SCons does not automatically rebuild LaTeX files when the file
383 has an undefined reference on the first build.
385 - Use of --implicit-cache with TargetSignatures('content') can,
386 for some changes, not rebuild a file when necessary.
388 - SCons does not currently automatically check out SConstruct or
389 SConscript files from SCCS, RCS or BitKeeper.
391 - No support yet for the following planned command-line options:
393 -d -e -l --list-actions --list-derived --list-where
394 -o --override -p -r -R -w --write-filenames
395 -W --warn-undefined-variables
399 Thank you for your interest, and please let us know how we can help
400 improve SCons for your needs.
403 knight at baldmt dot com
404 http://www.baldmt.com/~knight/
406 With plenty of help from the SCons Development team: