diff options
Diffstat (limited to 'doc/man/scons.1')
| -rw-r--r-- | doc/man/scons.1 | 340 |
1 files changed, 283 insertions, 57 deletions
diff --git a/doc/man/scons.1 b/doc/man/scons.1 index 45d7a5b2..49f9a305 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 |