X-Git-Url: http://git.tremily.us/?a=blobdiff_plain;f=doc%2Fman%2Fscons.1;h=9c5e5de1514a854865391ded2e9e9943332836d2;hb=53fca3d683cd298983e74a2068e18acff133fb1f;hp=b605c8bcaf8423505a7a82766ee0c1cd7b1a1ab3;hpb=11983445c53bddbeef249929a316bba40ce1652c;p=scons.git diff --git a/doc/man/scons.1 b/doc/man/scons.1 index b605c8bc..9c5e5de1 100644 --- a/doc/man/scons.1 +++ b/doc/man/scons.1 @@ -73,7 +73,7 @@ The .I SConstruct file can specify subsidiary configuration files using the -.B SConscript() +.BR SConscript () function. By convention, these subsidiary files are named @@ -98,17 +98,20 @@ Before reading the .I SConstruct file, .B scons -adds looks for a dir named +looks for a directory named .I site_scons -in the dir containing the +in the directory containing the .I SConstruct -file; it adds that +file; if it exists, .I site_scons -to sys.path, reads the file +is added to sys.path, +the file .IR site_scons/site_init.py , -and adds the directory +is evaluated if it exists, +and the directory .I site_scons/site_tools -to the default toolpath, if those exist. See the +is added to the default toolpath if it exist. +See the .I --no-site-dir and .I --site-dir @@ -801,6 +804,12 @@ the mechanisms in the specified order. Use .I file as the initial SConscript file. +Multiple +.B -f +options may be specified, +in which case +.B scons +will read all of the specified files. .TP -h, --help @@ -1067,6 +1076,19 @@ signature and to ignore the cached value if there already is one. A value of 0 means to always use the cached signature, no matter how old the file is. +.TP +.RI --md5-chunksize= KILOBYTES +Set the block size used to compute MD5 signatures to +.IR KILOBYTES . +This value determines the size of the chunks which are read in at once when +computing MD5 signatures. Files below that size are fully stored in memory +before performing the signature computation while bigger files are read in +block-by-block. A huge block-size leads to high memory consumption while a very +small block-size slows down the build considerably. + +The default value is to use a chunk size of 64 kilobytes, which should +be appropriate for most uses. + .TP -n, --just-print, --dry-run, --recon No execute. Print the commands that would be executed to build @@ -1330,30 +1352,43 @@ These warnings are disabled by default. .TP --warn=deprecated, --warn=no-deprecated -Enables or disables all warnings about use of deprecated features. +Enables or disables all warnings about use of +currently deprecated features. These warnings are enabled by default. +Note that the +.B --warn=no-deprecated +option does not disable warnings about absolutely all deprecated features. +Warnings for some deprecated features that have already been through +several releases with deprecation warnings +may be mandatory for a release or two +before they are officially no longer supported by SCons. Warnings for some specific deprecated features may be enabled or disabled individually; see below. +.RS +.TP --warn=deprecated-copy, --warn=no-deprecated-copy Enables or disables warnings about use of the deprecated .B env.Copy() method. +.TP --warn=deprecated-source-signatures, --warn=no-deprecated-source-signatures Enables or disables warnings about use of the deprecated -SourceSignatures() function -or +.B SourceSignatures() +function or .B env.SourceSignatures() method. +.TP --warn=deprecated-target-signatures, --warn=no-deprecated-target-signatures Enables or disables warnings about use of the deprecated -TargetSignatures() function -or +.B TargetSignatures() +function or .B env.TargetSignatures() method. +.RE .TP --warn=duplicate-environment, --warn=no-duplicate-environment @@ -1368,6 +1403,18 @@ Enables or disables the specific warning about linking Fortran and C++ object files in a single executable, which can yield unpredictable behavior with some compilers. +.TP +--warn=future-deprecated, --warn=no-future-deprecated +Enables or disables warnings about features +that will be deprecated in the future. +These warnings are disabled by default. +Enabling this warning is especially +recommended for projects that redistribute +SCons configurations for other users to build, +so that the project can be warned as soon as possible +about to-be-deprecated features +that may require changes to the configuration. + .TP --warn=link, --warn=no-link Enables or disables warnings about link steps. @@ -1434,11 +1481,15 @@ These warnings are enabled by default. --warn=reserved-variable, --warn=no-reserved-variable Enables or disables warnings about attempts to set the reserved construction variable names +.BR CHANGED_SOURCES , +.BR CHANGED_TARGETS , .BR TARGET , .BR TARGETS , -.BR SOURCE +.BR SOURCE , +.BR SOURCES , +.BR UNCHANGED_SOURCES or -.BR SOURCES . +.BR UNCHANGED_TARGETS . These warnings are disabled by default. .TP @@ -1521,7 +1572,7 @@ env = Environment(parse_flags = '-Iinclude -DEBUG -lm') This example adds 'include' to .BR CPPPATH , -\'EBUG' to +\&'EBUG' to .BR CPPDEFINES , and 'm' to .BR LIBS . @@ -1549,9 +1600,9 @@ and suffixes appropriate for the platform. Note that the .B win32 platform adds the -.B SYSTEMDRIVE +.B SystemDrive and -.B SYSTEMROOT +.B SystemRoot variables from the user's external environment to the construction environment's .B ENV @@ -1725,6 +1776,7 @@ midl mingw mslib mslink +mssdk msvc msvs mwcc @@ -1749,6 +1801,7 @@ sunlink swig tar tex +textfile tlib yacc zip @@ -1788,9 +1841,7 @@ and a same-named environment method that split a single string into a list, separated on strings of white-space characters. -(These are similar to the -string.split() method -from the standard Python library, +(These are similar to the split() member function of Python strings but work even if the input isn't a string.) Like all Python arguments, @@ -1809,7 +1860,7 @@ env.Program('bar', env.Split('bar.c foo.c')) env.Program(source = ['bar.c', 'foo.c'], target = 'bar') env.Program(target = 'bar', Split('bar.c foo.c')) env.Program(target = 'bar', env.Split('bar.c foo.c')) -env.Program('bar', source = string.split('bar.c foo.c')) +env.Program('bar', source = 'bar.c foo.c'.split()) .EE Target and source file names @@ -1944,7 +1995,7 @@ env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm') This example adds 'include' to .BR CPPPATH , -\'EBUG' to +\&'EBUG' to .BR CPPDEFINES , and 'm' to .BR LIBS . @@ -2302,9 +2353,9 @@ include: '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .TP -.RI Action( action ", [" strfunction ", " varlist ]) +.RI Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])" .TP -.RI env.Action( action ", [" strfunction ", " varlist ]) +.IR env .Action( action ", [" cmd/str/fun ", [" var ", ...]] [" option = value ", ...])" Creates an Action object for the specified .IR action . @@ -2314,13 +2365,12 @@ below, for a complete explanation of the arguments and behavior. Note that the .BR env.Action () form of the invocation will expand -construction variables in any arguments strings, +construction variables in any argument strings, including the .I action -argument, -at the time it is called +argument, at the time it is called using the construction variables in the -.B env +.I env construction environment through which .BR env.Action () was called. @@ -2674,7 +2724,7 @@ env.Append(CCFLAGS = ' -g', FOO = ['foo.yyy']) '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .TP -.RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ]) +.RI env.AppendENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ]) This appends new path elements to the given path in the specified external environment .RB ( ENV @@ -2691,6 +2741,11 @@ This can also handle the case where the given old path variable is a list instead of a string, in which case a list will be returned instead of a string. +If +.I delete_existing +is 0, then adding a path that already exists +will not move it to the end; it will stay where it is in the list. + Example: .ES @@ -2706,7 +2761,7 @@ after: /biz:/foo/bar:/foo '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .TP -.RI env.AppendUnique( key = val ", [...])" +.RI env.AppendUnique( key = val ", [...], delete_existing=0)" Appends the specified keyword arguments to the end of construction variables in the environment. If the Environment does not have @@ -2717,6 +2772,9 @@ then any value(s) that already exist in the construction variable will .I not be added again to the list. +However, if delete_existing is 1, +existing matching values are removed first, so +existing values in the arg list move to the end of the list. Example: @@ -2941,6 +2999,14 @@ Clean('dist', env.Program('hello', 'hello.c')) Clean(['foo', 'bar'], 'something_else_to_clean') .EE +In this example, +installing the project creates a subdirectory for the documentation. +This statement causes the subdirectory to be removed +if the project is deinstalled. +.ES +Clean(docdir, os.path.join(docdir, projectname)) +.EE + '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .TP .RI Command( target ", " source ", " action ", [" key = val ", ...])" @@ -3454,7 +3520,7 @@ print env.Dump('CCCOM') .IP will print: .ES -\&'$CC $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES' +\&'$CC -c -o $TARGET $CCFLAGS $CPPFLAGS $_CPPDEFFLAGS $_CPPINCFLAGS $SOURCES' .EE .ES @@ -3545,6 +3611,33 @@ The exit value of the command or return value of the Python function will be returned. +Note that +.B scons +will print an error message if the executed +.I action +fails--that is, +exits with or returns a non-zero value. +.B scons +will +.I not , +however, +automatically terminate the build +if the specified +.I action +fails. +If you want the build to stop in response to a failed +.BR Execute () +call, +you must explicitly check for a non-zero return value: + +.ES +Execute(Copy('file.out', 'file.in')) + +if Execute("mkdir sub/dir/ectory"): + # The mkdir failed, don't try to build. + Exit(1) +.EE + '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .TP .RI Exit([ value ]) @@ -3575,9 +3668,10 @@ so subsequent calls to will over-write previous exports that have the same name. Multiple variable names can be passed to .BR Export () -as separate arguments or as a list. A dictionary can be used to map -variables to a different name when exported. Both local variables and -global variables can be exported. +as separate arguments or as a list. +Keyword arguments can be used to provide names and their values. +A dictionary can be used to map variables to a different name when exported. +Both local variables and global variables can be exported. Examples: @@ -3593,7 +3687,10 @@ Export("env", "package") # Make env and package available for all SConscript files: Export(["env", "package"]) -# Make env available using the name debug:. +# Make env available using the name debug: +Export(debug = env) + +# Make env available using the name debug: Export({"debug":env}) .EE @@ -3644,10 +3741,11 @@ Search for .I file in the path specified by .IR dirs . -.I file -may be a list of file names or a single file name. In addition to searching -for files that exist in the filesytem, this function also searches for -derived files that have not yet been built. +.I dirs +may be a list of directory names or a single directory name. +In addition to searching for files that exist in the filesytem, +this function also searches for derived files +that have not yet been built. Example: @@ -3965,7 +4063,6 @@ The options supported are: .RS 10 .TP 6 .B cache_debug -.TP 6 which corresponds to --cache-debug; .TP 6 .B cache_disable @@ -4090,6 +4187,8 @@ uses Unix shell style metacharacters for matching: .EE .IP +If the first character of a filename is a dot, +it must be matched explicitly. Character matches do .I not span directory separators. @@ -4161,10 +4260,11 @@ not the original .B SConscript directory.) -Example: +Examples: .ES Program('foo', Glob('*.c')) +Zip('/tmp/everything', Glob('.??*') + Glob('*')) .EE '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" @@ -4211,9 +4311,9 @@ The specified dependency file(s) will be ignored when deciding if the target file(s) need to be rebuilt. -You can also use -.B Ignore - to remove a target from the default build. +You can also use +.BR Ignore() +to remove a target from the default build. In order to do this you must specify the directory the target will be built in as the target, and the file you want to skip building as the dependency. @@ -4285,12 +4385,51 @@ even if an already up-to-date copy exists in a repository. Returns a list of the target Node or Nodes. +'\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" +\" .TP +\" .RI env.MergeShellPaths( arg ", [" prepend ]) +\" Merges the elements of the specified +\" .IR arg , +\" which must be a dictionary, to the construction +\" environment's copy of the shell environment +\" in env['ENV']. +\" (This is the environment which is passed +\" to subshells spawned by SCons.) +\" 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.MergeShellPaths (). + +\" New values are prepended to the environment variable by default, +\" unless prepend=0 is specified. +\" Duplicate values are always eliminated, +\" since this function calls +\" .B AppendENVPath +\" or +\" .B PrependENVPath +\" depending on the +\" .I prepend +\" argument. See those functions for more details. + +\" Examples: + +\" .ES +\" # Prepend a path to the shell PATH. +\" env.MergeShellPaths({'PATH':'/usr/local/bin'} ) +\" # Append two dirs to the shell INCLUDE. +\" env.MergeShellPaths({'INCLUDE':['c:/inc1', 'c:/inc2']}, prepend=0 ) + +.EE + '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .TP .RI env.MergeFlags( arg ", [" unique ]) Merges the specified .I arg -values to the construction envrionment's construction variables. +values to the construction environment's construction variables. If the .I arg argument is not a dictionary, @@ -4606,7 +4745,7 @@ P4LANGUAGE, P4PASSWD, P4PORT, P4USER, -SYSTEMROOT, +SystemRoot, USER, and USERNAME. @@ -4637,9 +4776,9 @@ env.Platform('posix') Note that the .B win32 platform adds the -.B SYSTEMDRIVE +.B SystemDrive and -.B SYSTEMROOT +.B SystemRoot variables from the user's external environment to the construction environment's .B ENV @@ -4807,7 +4946,7 @@ env.Prepend(CCFLAGS = '-g ', FOO = ['foo.yyy']) '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .TP -.RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ]) +.RI env.PrependENVPath( name ", " newpath ", [" envname ", " sep ", " delete_existing ]) This appends new path elements to the given path in the specified external environment .RB ( ENV @@ -4824,6 +4963,12 @@ This can also handle the case where the given old path variable is a list instead of a string, in which case a list will be returned instead of a string. +If +.I delete_existing +is 0, then adding a path that already exists +will not move it to the beginning; +it will stay where it is in the list. + Example: .ES @@ -4842,7 +4987,7 @@ after: /foo/bar:/foo:/biz '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .TP -.RI env.PrependUnique( key = val ", [...])" +.RI env.PrependUnique( key = val ", delete_existing=0, [...])" Appends the specified keyword arguments to the beginning of construction variables in the environment. If the Environment does not have @@ -4853,6 +4998,9 @@ then any value(s) that already exist in the construction variable will .I not be added again to the list. +However, if delete_existing is 1, +existing matching values are removed first, so +existing values in the arg list move to the front of the list. Example: @@ -5171,17 +5319,24 @@ The '\" .I src_dir '\" arguments are interpreted relative to the directory of the calling argument is interpreted relative to the directory of the calling -.BR SConscript file. +.B SConscript +file. See the description of the .BR VariantDir () function below for additional details and restrictions. If -'\" .IR variant_dir " is present, but" +.I variant_dir +is present, +'\" but '\" .IR src_dir " is not," -.IR variant_dir " is present," -the source directory is relative to the called -.BR SConscript " file." +the source directory is the directory in which the +.B SConscript +file resides and the +.B SConscript +file is evaluated as if it were in the +.I variant_dir +directory: .ES SConscript('src/SConscript', variant_dir = 'build') .EE @@ -5192,7 +5347,7 @@ SConscript('build/SConscript') .EE This later paradigm is often used when the sources are in the same directory as the -.BR SConstruct file: +.BR SConstruct: .ES SConscript('SConscript', variant_dir = 'build') .EE @@ -5377,7 +5532,7 @@ The following statements are equivalent: .ES env.SetDefault(FOO = 'foo') -if not env.has_key('FOO'): env['FOO'] = 'foo' +if 'FOO' not in env: env['FOO'] = 'foo' .EE '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" @@ -6830,6 +6985,54 @@ or .B C++ and selects the compiler to be used for the check; the default is "C". +Example: +.ES +sconf.CheckType('foo_type', '#include "my_types.h"', 'C++') +.EE + +.TP +.RI Configure.CheckCC( self ) +Checks whether the C compiler (as defined by the CC construction variable) works +by trying to compile a small source file. + +By default, SCons only detects if there is a program with the correct name, not +if it is a functioning compiler. + +This uses the exact same command than the one used by the object builder for C +source file, so it can be used to detect if a particular compiler flag works or +not. + +.TP +.RI Configure.CheckCXX( self ) +Checks whether the C++ compiler (as defined by the CXX construction variable) +works by trying to compile a small source file. By default, SCons only detects +if there is a program with the correct name, not if it is a functioning compiler. + +This uses the exact same command than the one used by the object builder for +CXX source files, so it can be used to detect if a particular compiler flag +works or not. + +.TP +.RI Configure.CheckSHCC( self ) +Checks whether the C compiler (as defined by the SHCC construction variable) works +by trying to compile a small source file. By default, SCons only detects if +there is a program with the correct name, not if it is a functioning compiler. + +This uses the exact same command than the one used by the object builder for C +source file, so it can be used to detect if a particular compiler flag works or +not. This does not check whether the object code can be used to build a shared +library, only that the compilation (not link) succeeds. + +.TP +.RI Configure.CheckSHCXX( self ) +Checks whether the C++ compiler (as defined by the SHCXX construction variable) +works by trying to compile a small source file. By default, SCons only detects +if there is a program with the correct name, not if it is a functioning compiler. + +This uses the exact same command than the one used by the object builder for +CXX source files, so it can be used to detect if a particular compiler flag +works or not. This does not check whether the object code can be used to build +a shared library, only that the compilation (not link) succeeds. .EE Example of a typical Configure usage: @@ -6992,8 +7195,8 @@ will be displayed to the user, e.g. 'Checking for library X...' Usually called after the check is done. .I res -can be either an integer or a string. In the former case, 'ok' (res != 0) -or 'failed' (res == 0) is displayed to the user, in the latter case the +can be either an integer or a string. In the former case, 'yes' (res != 0) +or 'no' (res == 0) is displayed to the user, in the latter case the given string is displayed. .TP @@ -7801,7 +8004,7 @@ may be indicated by a dictionary entry with a key value of None. .P .ES -b = Builder("build_it < $SOURCE > $TARGET" +b = Builder("build_it < $SOURCE > $TARGET", prefix = "file-") def gen_prefix(env, sources): @@ -8087,7 +8290,7 @@ multi-stage builder. .IP single_source Specifies that this builder expects exactly one source file per call. Giving -more than one source files without target files results in implicitely calling +more than one source file without target files results in implicitely calling the builder multiple times (once for each source given). Giving multiple source files together with target files results in a UserError exception. @@ -8247,7 +8450,7 @@ and emitter functions. .SS Action Objects The -.BR Builder() +.BR Builder () function will turn its .B action keyword argument into an appropriate @@ -8280,18 +8483,15 @@ the object is simply returned. .IP String If the first argument is a string, a command-line Action is returned. -Note that the command line string +Note that the command-line string may be preceded by an .B @ (at-sign) -to suppress printing of the -specified command line, +to suppress printing of the specified command line, or by a .B \- (hyphen) -to ignore the exit status from -the specified command. -Examples: +to ignore the exit status from the specified command: .ES Action('$CC -c -o $TARGET $SOURCES') @@ -8299,10 +8499,9 @@ Action('$CC -c -o $TARGET $SOURCES') # Doesn't print the line being executed. Action('@build $TARGET $SOURCES') -# Ignores +# Ignores return value Action('-build $TARGET $SOURCES') .EE - .\" XXX From Gary Ruben, 23 April 2002: .\" What would be useful is a discussion of how you execute command .\" shell commands ie. what is the process used to spawn the shell, pass @@ -8312,7 +8511,6 @@ Action('-build $TARGET $SOURCES') .\" a build system. I'm sure you can do a better job of organising the .\" documentation than they have :-) - .IP List If the first argument is a list, then a list of Action objects is returned. @@ -8335,7 +8533,7 @@ Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']]) .IP Function If the first argument is a Python function, a function Action is returned. -The Python function takes three keyword arguments, +The Python function must take three keyword arguments, .B target (a Node object representing the target file), .B source @@ -8380,19 +8578,22 @@ If the action argument is not one of the above, None is returned. .PP -The second, optional argument -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. +The second argument is optional and 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 must be 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. +The function may also be specified by the +.IR strfunction = +keyword argument. Like a function to build a file, -this function takes three arguments: +this function must take three keyword arguments: .B target (a Node object representing the target file), .B source @@ -8408,6 +8609,9 @@ 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 may also be specified by the +.IR cmdstr = +keyword argument. The string typically contains variables, notably $TARGET(S) and $SOURCE(S), or consists of just a single variable, which is optionally defined somewhere else. @@ -8435,17 +8639,20 @@ s = Action(build_it, cmdstr="building '$TARGET' from '$SOURCE'") l = Action(build_it, '$STRINGIT') .EE -The third, also optional argument -is a list of construction variables -whose values will be included -in the signature of the Action -when deciding whether a target should -be rebuilt because the action changed. -This is necessary whenever you want a target to -be rebuilt when a specific -construction variable changes, -because the underlying Python code for a function -will not change when the value of the construction variable does. +The third and succeeding arguments, if present, +may either be a construction variable or a list of construction variables +whose values will be included in the signature of the Action +when deciding whether a target should be rebuilt because the action changed. +The variables may also be specified by a +.IR varlist = +keyword parameter; +if both are present, they are combined. +This is necessary whenever you want a target to be rebuilt +when a specific construction variable changes. +This is not often needed for a string action, +as the expanded variables will normally be part of the command line, +but may be needed if a Python function action uses +the value of a construction variable when generating the command line. .ES def build_it(target, source, env): @@ -8463,16 +8670,25 @@ a = Action(build_it, varlist=['XXX']) The .BR Action () global function -also takes a +can be passed the following +optional keyword arguments +to modify the Action object's behavior: + +.IP .B chdir -keyword argument -which specifies that +The +.B chdir +keyword argument specifies that scons will execute the action after changing to the specified directory. -If the chdir argument is +If the +.B chdir +argument is a string or a directory Node, scons will change to the specified directory. -If the chdir argument +If the +.B chdir +argument is not a string or Node and is non-zero, then scons will change to the @@ -8507,6 +8723,8 @@ a = Action("build < ${SOURCE.file} > ${TARGET.file}", chdir=1) .EE +.IP +.B exitstatfunc The .BR Action () global function @@ -8522,6 +8740,7 @@ or modified value. This can be used, for example, to specify that an Action object's return value should be ignored +under special conditions and SCons should, therefore, consider that the action always suceeds: @@ -8533,6 +8752,111 @@ a = Action("build < ${SOURCE.file} > ${TARGET.file}", exitstatfunc=always_succeed) .EE +.IP +.B batch_key +The +.B batch_key +keyword argument can be used +to specify that the Action can create multiple target files +by processing multiple independent source files simultaneously. +(The canonical example is "batch compilation" +of multiple object files +by passing multiple source files +to a single invocation of a compiler +such as Microsoft's Visual C / C++ compiler.) +If the +.B batch_key +argument is any non-False, non-callable Python value, +the configured Action object will cause +.B scons +to collect all targets built with the Action object +and configured with the same construction environment +into single invocations of the Action object's +command line or function. +Command lines will typically want to use the +.BR CHANGED_SOURCES +construction variable +(and possibly +.BR CHANGED_TARGETS +as well) +to only pass to the command line those sources that +have actually changed since their targets were built. + +Example: + +.ES +a = Action('build $CHANGED_SOURCES', batch_key=True) +.EE + +The +.B batch_key +argument may also be +a callable function +that returns a key that +will be used to identify different +"batches" of target files to be collected +for batch building. +A +.B batch_key +function must take the following arguments: + +.IP action +The action object. + +.IP env +The construction environment +configured for the target. + +.IP target +The list of targets for a particular configured action. + +.IP source +The list of source for a particular configured action. + +The returned key should typically +be a tuple of values derived from the arguments, +using any appropriate logic to decide +how multiple invocations should be batched. +For example, a +.B batch_key +function may decide to return +the value of a specific construction +variable from the +.B env +argument +which will cause +.B scons +to batch-build targets +with matching values of that variable, +or perhaps return the +.BR id () +of the entire construction environment, +in which case +.B scons +will batch-build +all targets configured with the same construction environment. +Returning +.B None +indicates that +the particular target should +.I not +be part of any batched build, +but instead will be built +by a separate invocation of action's +command or function. +Example: + +.ES +def batch_key(action, env, target, source): + tdir = target[0].dir + if tdir.name == 'special': + # Don't batch-build any target + # in the special/ subdirectory. + return None + return (id(action), id(env), tdir) +a = Action('build $CHANGED_SOURCES', batch_key=batch_key) +.EE + .SS Miscellaneous Action Functions .B scons @@ -8672,10 +8996,10 @@ Examples: Execute(Mkdir('/tmp/outputdir')) env.Command('foo.out', 'foo.in', - [Mkdir('/tmp/builddir', - Copy('$SOURCE', '/tmp/builddir/foo.in') + [Mkdir('/tmp/builddir'), + Copy('/tmp/builddir/foo.in', '$SOURCE'), "cd /tmp/builddir && make", - Copy('/tmp/builddir/foo.out', '$TARGET')]) + Copy('$TARGET', '/tmp/builddir/foo.out')]) .EE .TP @@ -8725,20 +9049,42 @@ prefix. Besides construction variables, scons provides the following variables for each command execution: -.IP TARGET -The file name of the target being built, or the file name of the first -target if multiple targets are being built. +.IP CHANGED_SOURCES +The file names of all sources of the build command +that have changed since the target was last built. -.IP TARGETS -The file names of all targets being built. +.IP CHANGED_TARGETS +The file names of all targets that would be built +from sources that have changed since the target was last built. .IP SOURCE -The file name of the source of the build command, or the file name of the -first source if multiple sources are being built. +The file name of the source of the build command, +or the file name of the first source +if multiple sources are being built. .IP SOURCES The file names of the sources of the build command. +.IP TARGET +The file name of the target being built, +or the file name of the first target +if multiple targets are being built. + +.IP TARGETS +The file names of all targets being built. + +.IP UNCHANGED_SOURCES +The file names of all sources of the build command +that have +.I not +changed since the target was last built. + +.IP UNCHANGED_TARGETS +The file names of all targets that would be built +from sources that have +.I not +changed since the target was last built. + (Note that the above variables are reserved and may not be set in a construction environment.) @@ -9210,7 +9556,7 @@ source files of different types: .ES def xyz_scan(node, env, path): - contents = node.get_contents() + contents = node.get_text_contents() # Scan the contents and return the included files. XYZScanner = Scanner(xyz_scan) @@ -9482,7 +9828,7 @@ import re include_re = re.compile(r'^include\\s+(\\S+)$', re.M) def kfile_scan(node, env, path, arg): - contents = node.get_contents() + contents = node.get_text_contents() includes = include_re.findall(contents) return includes @@ -9511,7 +9857,7 @@ for files that actually exist: include_re = re.compile(r'^include\\s+(\\S+)$', re.M) def my_scan(node, env, path, arg): - contents = node.get_contents() + contents = node.get_text_contents() includes = include_re.findall(contents) if includes == []: return [] @@ -9553,7 +9899,7 @@ as follows: def pf(env, dir, target, source, arg): top_dir = Dir('#').abspath results = [] - if env.has_key('MYPATH'): + if 'MYPATH' in env: for p in env['MYPATH']: results.append(top_dir + os.sep + p) return results