diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/man/scons.1 | 130 |
1 files changed, 113 insertions, 17 deletions
diff --git a/doc/man/scons.1 b/doc/man/scons.1 index 257dbd6..19237dc 100644 --- a/doc/man/scons.1 +++ b/doc/man/scons.1 @@ -2399,10 +2399,10 @@ can be converted into an Action object .TP .RI BuildDir( build_dir ", " src_dir ", [" duplicate ]) -This specifies a build directory to use for all derived files. +This specifies a build directory .I build_dir -specifies the build directory to be used for all derived files that would -normally be built under +in which to build all derived files +that would normally be built under .IR src_dir . Multiple build directories can be set up for multiple build variants, for example. @@ -2413,20 +2413,80 @@ and may not be underneath the .I src_dir . +The default behavior is for .B scons -will link or copy (depending on the platform) all the source files into the -build directory if -.I duplicate -is set to 1 (the default). If +to duplicate all of the files in the tree underneath +.I src_dir +into +.IR build_dir , +and then build the derived files within the copied tree. +(The duplication is performed by +linking or copying, +depending on the platform.) +This guarantees correct builds +regardless of whether intermediate source files +are generated during the build, +where preprocessors or other scanners search +for included files, +or whether individual compilers or other invoked tools +are hard-coded to put derived files in the same directory as source files. + +This behavior of making a complete copy of the source tree +may be disabled by setting .I duplicate -is set to 0, then -.B scons -will not copy or link any source files, which may cause build problems in -certain situations (e.g. C source files that are generated by the -build). -.IR duplicate =0 -is usually safe, and is always more efficient than -.IR duplicate =1. +to 0. +This will cause +.B scons +to invoke Builders using the +path names of source files in +.I src_dir +and the path names of derived files within +.IR build_dir . +This is always more efficient than +.IR duplicate =1, +and is usually safe for most builds. +Specifying +.IR duplicate =0, +however, +may cause build problems +if source files are generated during the build, +if any invoked tools are hard-coded to +put derived files in the same directory as the source files. + +Note that specifying a +.B BuildDir +works most naturally +with a subsidiary SConscript file +in the source directory. +However, +you would then call the subsidiary SConscript file +not in the source directory, +but in the +.I build_dir , +as if +.B scons +had made a virtual copy of the source tree +regardless of the value of +.IR duplicate . +This is how you tell +.B scons +which variant of a source tree to build. +For example: + +.ES +BuildDir('build-variant1', 'src') +SConscript('build-variant1/SConscript') +BuildDir('build-variant2', 'src') +SConscript('build-variant2/SConscript') +.EE + +See also the +.BR SConscript () +function, described below, +for another way to +specify a build directory +in conjunction with calling a subsidiary +SConscript file.) .TP .RI AddPostAction ( target, action ) @@ -2820,7 +2880,7 @@ Return(["foo", "bar"]) .EE .TP -.RI SConscript( script ", [" exports ]) +.RI SConscript( script ", [" exports ", " build_dir ", " duplicate ]) This tells .B scons to execute @@ -2832,17 +2892,53 @@ argument provides a list of variable names to export to .I script must use the .BR Import () -function to import the variables. Any variables returned by +function to import the variables. + +The optional +.I build_dir +argument specifies that all of the target files +(for example, object files and executables) +that would normally be built in the subdirectory in which +.I script +resides should actually +be built in +.IR build_dir . +By default, +.B scons +will link or copy (depending on the platform) +all the source files into the build directory. +This behavior may be disabled by +setting the optional +.I duplicate +argument to 0 +(it is set to 1 by default), +in which case +.B scons +will refer directly to +the source files in their source directory +when building target files. +(Setting +.IR duplicate =0 +is usually safe, and always more efficient +than the default of +.IR duplicate =1, +but it may cause build problems in certain end-cases, +such as compiling from source files that +are generated by the build. + +Any variables returned by .I script using .BR Return () will be returned by the call to .BR SConscript (). + Examples: .ES SConscript('dir/SConscript') foo = SConscript('subdir/SConscript', "env") +SConscript('src/SConscript', build_dir='build', duplicate=0) .EE .TP |