summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorSteven Knight <knight@baldmt.com>2006-07-25 02:30:45 (GMT)
committerSteven Knight <knight@baldmt.com>2006-07-25 02:30:45 (GMT)
commitdd9bbc79353ae90b2402c16b1613dad4e502d250 (patch)
tree42f857f72bb4dcab6d876d1f9c73e0a1dd70d8c2 /doc
parent57fcbbc5d24fb16f988e4fe3294d5d49abef8e2a (diff)
downloadSCons-dd9bbc79353ae90b2402c16b1613dad4e502d250.zip
SCons-dd9bbc79353ae90b2402c16b1613dad4e502d250.tar.gz
SCons-dd9bbc79353ae90b2402c16b1613dad4e502d250.tar.bz2
Merged revisions 1441-1539 via svnmerge from
http://scons.tigris.org/svn/scons/branches/core ........ r1441 | stevenknight | 2006-04-22 23:06:53 -0400 (Sat, 22 Apr 2006) | 1 line 0.96.D397 - The scons command, branch 0.96.91. ........ r1442 | stevenknight | 2006-04-27 00:45:12 -0400 (Thu, 27 Apr 2006) | 1 line 0.96.D398 - The scons command, branch 0.96.92. ........ r1443 | stevenknight | 2006-04-27 00:49:25 -0400 (Thu, 27 Apr 2006) | 1 line 0.96.D399 - Taskmaster clean-ups in anticipation of refactoring speedups. ........ r1450 | stevenknight | 2006-05-02 00:04:55 -0400 (Tue, 02 May 2006) | 1 line 0.96.D400 - Fix VC+++ 2005 Express detection. (Atul Varma) Fix parsing Intel C compiler Li ........ r1451 | stevenknight | 2006-05-02 01:14:24 -0400 (Tue, 02 May 2006) | 1 line 0.96.D401 - Enhance ParseConfig() to understand -arch and -isysroot options. (Gary Oberbrun ........ r1458 | stevenknight | 2006-05-02 23:21:04 -0400 (Tue, 02 May 2006) | 1 line 0.96.D402 - Make strfunction handling consistent. (David Gruener) ........ r1459 | stevenknight | 2006-05-02 23:37:08 -0400 (Tue, 02 May 2006) | 1 line 0.96.D403 - Comment out the test of CVS checkout from the old tigris.org repository. ........ r1460 | stevenknight | 2006-05-03 23:47:54 -0400 (Wed, 03 May 2006) | 1 line 0.96.D404 - Preserve white space in display Action string. (David Gruener) ........ r1461 | stevenknight | 2006-05-04 09:16:15 -0400 (Thu, 04 May 2006) | 1 line 0.96.D405 - Add MergeFlags() and AddFlags() methods. (Greg Noel) Support recognizing compi ........ r1462 | stevenknight | 2006-05-04 23:46:53 -0400 (Thu, 04 May 2006) | 1 line 0.96.D406 - Fix stack trace when ParseFlags has a null string. ........ r1464 | stevenknight | 2006-05-05 17:21:27 -0400 (Fri, 05 May 2006) | 1 line 0.96.D408 - Fix the string displayed by InstallAs() when called through the default construc ........ r1465 | stevenknight | 2006-05-05 18:30:28 -0400 (Fri, 05 May 2006) | 1 line 0.96.D409 - Fix test/ParseConfig.py, broken in the previous checkin by ParseFlags() changes. ........ r1466 | stevenknight | 2006-05-05 20:42:35 -0400 (Fri, 05 May 2006) | 1 line 0.96.D407 - Avoid recursive calls to main() in SConf test programs. (Karol Pietrzak) ........ r1467 | stevenknight | 2006-05-06 00:27:21 -0400 (Sat, 06 May 2006) | 1 line 0.96.D410 - Catch errors from commands that ParseConfig() calls. (John Pye) ........ r1468 | stevenknight | 2006-05-06 10:55:38 -0400 (Sat, 06 May 2006) | 1 line 0.96.D411 - Significant taskmaster speedup by using reference counts, not list manipulation. ........ r1469 | stevenknight | 2006-05-06 18:38:02 -0400 (Sat, 06 May 2006) | 1 line 0.96.D413 - TeX improvements. ........ r1471 | stevenknight | 2006-05-07 09:07:58 -0400 (Sun, 07 May 2006) | 2 lines Delete properties interfering with clean .jpg checkout. ........ r1472 | stevenknight | 2006-05-07 09:23:54 -0400 (Sun, 07 May 2006) | 1 line 0.96.D412 - Windows portability fixes for two tests and ParseConfig() execution. ........ r1473 | stevenknight | 2006-05-07 09:30:11 -0400 (Sun, 07 May 2006) | 1 line 0.96.D414 - Various man page and documentation updates. ........ r1474 | stevenknight | 2006-05-07 23:53:12 -0400 (Sun, 07 May 2006) | 1 line 0.96.D415 - Initial infrastructure for executing tests under QMTest. (Stefan Seefeld) ........ r1476 | stevenknight | 2006-05-09 00:03:47 -0400 (Tue, 09 May 2006) | 1 line 0.96.D416 - Fix QMTest infrastructure to avoid listing directories with no tests and to find ........ r1477 | stevenknight | 2006-05-16 06:47:51 -0400 (Tue, 16 May 2006) | 1 line 0.96.D417 - Fix Alias turning Entries into Nodes or Dirs too soon. ........ r1478 | stevenknight | 2006-05-17 08:32:58 -0400 (Wed, 17 May 2006) | 1 line 0.96.D418 - Next QMTest changes (including fixing copyrights). ........ r1479 | stevenknight | 2006-05-18 05:07:06 -0400 (Thu, 18 May 2006) | 1 line 0.96.D419 - Fix DVIPDF tests after recent changes. ........ r1497 | stevenknight | 2006-05-23 08:47:01 -0400 (Tue, 23 May 2006) | 1 line 0.96.D420 - Better error message when trying to build a file from an unknown sufix. (Gary O ........ r1498 | stevenknight | 2006-05-23 09:38:52 -0400 (Tue, 23 May 2006) | 1 line 0.96.D421 - Suppress duplicate entries in latest TeX patch. (Joel B. Mohler) ........ r1499 | stevenknight | 2006-05-23 22:00:06 -0400 (Tue, 23 May 2006) | 1 line 0.96.D422 - Add tests for tuple variable expansion. (Gary Oberbrunner) ........ r1515 | stevenknight | 2006-06-12 06:44:24 -0400 (Mon, 12 Jun 2006) | 1 line 0.96.D423 - More QMTest work: start giving runtest.py its own tests, more functionality for ........ r1517 | stevenknight | 2006-06-21 07:34:30 -0400 (Wed, 21 Jun 2006) | 1 line 0.96.D424 - Move test/Configure.py and test/Options.py to avoid confusion with similarly-nam ........ r1518 | stevenknight | 2006-06-21 12:40:37 -0400 (Wed, 21 Jun 2006) | 1 line 0.96.D425 - Change the QMTest infrastructure to use File naming, not Python. Rename tests w ........ r1533 | stevenknight | 2006-07-23 20:10:08 -0400 (Sun, 23 Jul 2006) | 1 line 0.96.D426 - Fix ramifications of changing when Node disambiguation happens. ........ r1535 | stevenknight | 2006-07-24 06:40:43 -0400 (Mon, 24 Jul 2006) | 3 lines Initialized merge tracking via "svnmerge" with revisions "1-1534" from http://scons.tigris.org/svn/scons/trunk ........ r1536 | stevenknight | 2006-07-24 21:45:40 -0400 (Mon, 24 Jul 2006) | 2 lines Remove svnmerge-integrated property to start over. ........ r1538 | stevenknight | 2006-07-24 21:51:32 -0400 (Mon, 24 Jul 2006) | 3 lines Initialized merge tracking via "svnmerge" with revisions "1-1440" from http://scons.tigris.org/svn/scons/trunk ........
Diffstat (limited to 'doc')
-rw-r--r--doc/SConscript17
-rw-r--r--doc/man/scons.1340
2 files changed, 297 insertions, 60 deletions
diff --git a/doc/SConscript b/doc/SConscript
index de8e21e..6162f93 100644
--- a/doc/SConscript
+++ b/doc/SConscript
@@ -382,10 +382,10 @@ for m in man_page_list:
orig_env.SCons_revision(os.path.join(build, 'man', m),
os.path.join('man', m))
-man_intermediate_files = ['builders.man', 'tools.man', 'variables.man']
+man_i_files = ['builders.man', 'tools.man', 'variables.man']
man_intermediate_files = map(lambda x: os.path.join(build, 'man', x),
- man_intermediate_files)
+ man_i_files)
cmd = "python $SCONS_PROC_PY --man -b ${TARGETS[0]} -t ${TARGETS[1]} -v ${TARGETS[2]} $( $SOURCES $)"
man_intermediate_files = env.Command(man_intermediate_files,
@@ -417,7 +417,18 @@ for man_1 in man_page_list:
if man2html:
html = os.path.join(build, 'HTML' , '%s-man.html' % man)
- cmds = [ "( cd ${SOURCES.dir} && man2html ${SOURCES.dir} ) > $TARGET" ]
+ def strip_to_first_html_tag(target, source, env):
+ t = str(target[0])
+ contents = open(t).read()
+ contents = contents[string.find(contents, '<HTML>'):]
+ open(t, 'w').write(contents)
+ return 0
+
+ cmds = [
+ "( cd build/doc/man && cp %s .. )" % string.join(man_i_files),
+ "( cd ${SOURCE.dir} && man2html ${SOURCE.file} ) > $TARGET",
+ Action(strip_to_first_html_tag),
+ ]
if tidy:
cmds.append("tidy -m -q $TARGET || true")
b = env.Command(html, man_1, cmds)
diff --git a/doc/man/scons.1 b/doc/man/scons.1
index 45d7a5b..49f9a30 100644
--- a/doc/man/scons.1
+++ b/doc/man/scons.1
@@ -2182,6 +2182,32 @@ env.Command('baz.out', 'baz.in',
rename ])
.EE
+Note that the
+.BR Command ()
+function will usually assume, by default,
+that the specified targets and/or sources are Files,
+if no other part of the configuration
+identifies what type of entry it is.
+If necessary, you can explicitly specify
+that targets or source nodes should
+be treated as directoriese
+by using the
+.BR Dir ()
+or
+.BR env.Dir ()
+functions:
+
+.ES
+env.Command('ddd.list', Dir('ddd'), 'ls -l $SOURCE > $TARGET')
+
+env['DISTDIR'] = 'destination/directory'
+env.Command(env.Dir('$DISTDIR')), None, make_distdir)
+.EE
+
+(Also note that SCons will usually
+automatically create any directory necessary to hold a target file,
+so you normally don't need to create directories by hand.)
+
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
.RI Configure( env ", [" custom_tests ", " conf_dir ", " log_file ", " config_h ])
@@ -2782,6 +2808,56 @@ Returns a list of the target Node or Nodes.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
+.RI env.MergeFlags( arg ", [" unique ])
+Merges the specified
+.I arg
+values to the construction envrionment's construction variables.
+If the
+.I arg
+argument is not a dictionary,
+it is converted to one by calling
+.B env.ParseFlags()
+on the argument
+before the values are merged.
+Note that
+.I arg
+must be a single value,
+so multiple strings must
+be passed in as a list,
+not as separate arguments to
+.BR env.MergeFlags ().
+
+By default,
+duplicate values are eliminated;
+you can, however, specify
+.B unique=0
+to allow duplicate
+values to be added.
+When eliminating duplicate values,
+any construction variables that end with
+the string
+.B PATH
+keep the left-most unique value.
+All other construction variables keep
+the right-most unique value.
+
+Examples:
+
+.ES
+# Add an optimization flag to $CCFLAGS.
+env.MergeFlags('-O3')
+
+# Combine the flags returned from running pkg-config with an optimization
+# flag and merge the result into the construction variables.
+env.MergeFlags(['!pkg-config gtk+-2.0 --cflags', '-O3'])
+
+env.MergeFlags(['-O3',
+ '!pkg-config gtk+-2.0 --cflags --libs',
+ '!pkg-config libpng12 --cflags --libs'])
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
.RI NoClean( target ", ...)"
.TP
.RI env.NoClean( target ", ...)"
@@ -2836,7 +2912,9 @@ to modify the environment as specified by the output of
.I command .
The default
.I function
-expects the output of a typical
+is
+.BR env.MergeFlags (),
+which expects the output of a typical
.I *-config command
(for example,
.BR gtk-config )
@@ -2850,42 +2928,13 @@ you can specify
to allow duplicate
values to be added.
-By default,
-.BR -L ,
-.BR -l ,
-.BR -Wa ,
-.BR -Wl ,
-.BR -Wp ,
-.B -I
-and other options,
-are add to the
-.BR LIBPATH ,
-.BR LIBS ,
-.BR ASFLAGS ,
-.BR LINKFLAGS ,
-.BR CPPFLAGS ,
-.B CPPPATH
-and
-.B CCFLAGS
-construction variables,
-respectively.
-A returned
-.B -pthread
-option gets added to both the
-.B CCFLAGS
-and
-.B LINKFLAGS
-variables.
-A returned
-.B -framework
-option gets added to the
-.B LINKFLAGS
-variable.
-Any other strings not associated with options
-are assumed to be the names of libraries
-and added to the
-.B LIBS
-construction variable.
+Interpreted options
+and the construction variables they affect
+are as specified for the
+.BR env.ParseFlags ()
+method (which thie method calls).
+See that method's description, below,
+for a table of options and construction variables.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
@@ -2946,6 +2995,73 @@ function.
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.TP
+.RI env.ParseFlags( flags ", ...)"
+Parses one or more strings containing
+typical command-line flags for GCC tool chains
+and returns a dictionary with the flag values
+separated into the appropriate SCons construction variables.
+This is intended as a companion to the
+.BR env.MergeFlags ()
+method, but allows for the values in the returned dictionary
+to be modified, if necessary,
+before merging them into the construction environment.
+(Note that
+.BR env.MergeFlags ()
+will call this method if its argument is not a dictionary,
+so it is usually not necessary to call
+.BR env.ParseFlags ()
+directly unless you want to manipulate the values.)
+
+If the first character in any string is
+an exclamation mark (!),
+the rest of the string is executed as a command,
+and the output from the command is
+parsed as GCC tool chain command-line flags
+and added to the resulting dictionary.
+
+Flag values are translated accordig to the prefix found,
+and added to the following construction variables:
+
+.ES
+-arch CCFLAGS, LINKFLAGS
+-D CPPDEFINES
+-framework FRAMEWORKS
+-frameworkdir= FRAMEWORKPATH
+-include CCFLAGS
+-isysroot CCFLAGS, LINKFLAGS
+-I CPPPATH
+-l LIBS
+-L LIBPATH
+-mno-cygwin CCFLAGS, LINKFLAGS
+-mwindows LINKFLAGS
+-pthread CCFLAGS, LINKFLAGS
+-Wa, ASFLAGS, CCFLAGS
+-Wl,-rpath= RPATH
+-Wl,-R, RPATH
+-Wl,-R RPATH
+-Wl, LINKFLAGS
+-Wp, CPPFLAGS
+- CCFLAGS
++ CCFLAGS, LINKFLAGS
+.EE
+
+Any other strings not associated with options
+are assumed to be the names of libraries
+and added to the
+.B LIBS
+construction variable.
+
+Examples (all of which produce the same result):
+
+.ES
+dict = env.ParseFlags('-O2 -Dfoo -Dbar=1')
+dict = env.ParseFlags('-O2', '-Dfoo', '-Dbar=1')
+dict = env.ParseFlags(['-O2', '-Dfoo -Dbar=1'])
+dict = env.ParseFlags('-O2', '!echo -Dfoo -Dbar=1')
+.EE
+
+'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
+.TP
env.Perforce()
A factory function that
returns a Builder object
@@ -4425,10 +4541,13 @@ or a list of library names,
in which case each library in the list
will be checked for
.IR symbol .
-The default
+If
.I symbol
-is "main",
-which just check if
+is not set or is
+.BR None ,
+then
+.BR Configure.CheckLib ()
+just checks if
you can link against the specified
.IR library .
The optional
@@ -4442,7 +4561,6 @@ the default is "C".
The default value for
.I autoadd
is 1.
-It is assumed, that the C-language is used.
This method returns 1 on success and 0 on error.
.TP
@@ -4468,7 +4586,13 @@ header line being checked for.
.I language
may be one of 'C','c','CXX','cxx','C++' and 'c++'.
.I call
-can be any valid expression (with a trailing ';'). The default is 'main();'.
+can be any valid expression (with a trailing ';').
+If
+.I call
+is not set,
+the default simply checks that you
+can link against the specified
+.IR library .
.I autoadd
specifies whether to add the library to the environment (only if the check
succeeds). This method returns 1 on success and 0 on error.
@@ -4705,13 +4829,30 @@ the construction variable will
be added to the construction environment.
.I validator
is called to validate the value of the variable, and should take three
-arguments: key, value, and environment
+arguments: key, value, and environment.
+The recommended way to handle an invalid value is
+to raise an exception (see example below).
.I converter
is called to convert the value before putting it in the environment, and
-should take a single argument: value. Example:
+should take a single argument: value.
+The
+.I converter
+must return a value,
+which will be converted into a string
+before being validated by the
+.I validator
+(if any)
+and then added to the environment.
+
+Examples:
.ES
opts.Add('CC', 'The C compiler')
+
+def validate_color(key, val, env):
+ if not val in ['red', 'blue', 'yellow']:
+ raise "Invalid color value '%s'" % val
+opts.Add('COLOR', validator=valid_color)
.EE
.TP
@@ -5472,6 +5613,48 @@ and
.I action
arguments must not both be used for the same Builder.
+.IP source_ext_match
+When the specified
+.I action
+argument is a dictionary,
+the default behavior when a builder is passed
+multiple source files is to make sure that the
+extensions of all the source files match.
+If it is legal for this builder to be
+called with a list of source files with different extensions,
+this check can be suppressed by setting
+.B source_ext_match
+to
+.B None
+or some other non-true value.
+When
+.B source_ext_match
+is disable,
+.B scons
+will use the suffix of the first specified
+source file to select the appropriate action from the
+.I action
+dictionary.
+
+In the following example,
+the setting of
+.B source_ext_match
+prevents
+.B scons
+from exiting with an error
+due to the mismatched suffixes of
+.B foo.in
+and
+.BR foo.extra .
+
+.ES
+b = Builder(action={'.in' : 'build $SOURCES > $TARGET'},
+ source_ext_match = None)
+
+env = Environment(BUILDERS = {'MyBuild':b})
+env.MyBuild('foo.out', ['foo.in', 'foo.extra'])
+.EE
+
.IP env
A construction environment that can be used
to fetch source code using this Builder.
@@ -5535,6 +5718,21 @@ env = Environment(BUILDERS = {'MyBuild' : b})
env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in')
.EE
+.B WARNING:
+Python only keeps one current directory
+location for all of the threads.
+This means that use of the
+.B chdir
+argument
+will
+.I not
+work with the SCons
+.B -j
+option,
+because individual worker threads spawned
+by SCons interfere with each other
+when they start changing directory.
+
.RE
Any additional keyword arguments supplied
when a Builder object is created
@@ -5694,9 +5892,18 @@ a = Action(build_it)
If the action argument is not one of the above,
None is returned.
+.PP
The second, optional argument
-is a Python function that returns
+is used to define the output which is printed
+when the Action is actually performed.
+In the absence of this parameter, or if it's an
+empty string, a default output depending on the type of the action
+is used. For example, a command-line action will print
+the executed command. The argument is either a python function
+or a string.
+
+In the first case, it's a function that returns
a string to be printed to describe the action being executed.
Like a function to build a file,
this function takes three arguments:
@@ -5713,6 +5920,13 @@ and
.B source
arguments may be lists of Node objects if there is
more than one target file or source file.
+
+In the second case, you provide the string itself.
+The string typically contains variables, notably
+$TARGET(S) and $SOURCE(S), or consists of just a single
+variable, which is optionally defined somewhere else.
+SCons itself heavily uses the latter variant.
+
Examples:
.ES
@@ -5724,10 +5938,15 @@ def string_it(target, source, env):
return "building '%s' from '%s'" % (target[0], source[0])
# Use a positional argument.
-a = Action(build_it, string_it)
+f = Action(build_it, string_it)
+s = Action(build_it, "building '$TARGET' from '$SOURCE'")
# Alternatively, use a keyword argument.
-a = Action(build_it, strfunction=string_it)
+f = Action(build_it, strfunction=string_it)
+s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'")
+
+# You can provide a configurable variable.
+l = Action(build_it, '$STRINGIT')
.EE
The third, also optional argument
@@ -5748,16 +5967,12 @@ def build_it(target, source, env):
open(target[0], 'w').write(env['XXX'])
return 0
-def string_it(target, source):
- return "building '%s' from '%s'" % (target[0], source[0])
-
# Use positional arguments.
-a = Action(build_it, string_it, ['XXX'])
+a = Action(build_it, '$STRINGIT', ['XXX'])
# Alternatively, use a keyword argument.
a = Action(build_it, varlist=['XXX'])
.EE
-.PP
The
.BR Action ()
@@ -5890,7 +6105,7 @@ that
env = Environment(TMPBUILD = '/tmp/builddir')
env.Command('foo.out', 'foo.in',
[Mkdir('$TMPBUILD'),
- Copy('$TMPBUILD', '${SOURCE.dir}')
+ Copy('$TMPBUILD', '${SOURCE.dir}'),
"cd $TMPBUILD && make",
Delete('$TMPBUILD')])
.EE
@@ -6301,6 +6516,13 @@ Use
to fetch the name of the file, and
.B node.get_contents()
to fetch contents of the file.
+Note that the file is
+.I not
+guaranteed to exist before the scanner is called,
+so the scanner function should check that
+if there's any chance that the scanned file
+might not exist
+(for example, if it's built from other files).
The
.B env
@@ -6348,10 +6570,14 @@ then it will be expanded
into a list by the current environment.
.IP path_function
-A Python function that takes
-two or three arguments:
-a construction environment, directory Node,
-and optional argument supplied
+A Python function that takes four or five arguments:
+a construction environment,
+a Node for the directory containing
+the SConscript file in which
+the first target was defined,
+a list of target nodes,
+a list of source nodes,
+and an optional argument supplied
when the scanner was created.
The
.B path_function