From: stevenknight Date: Sun, 18 May 2008 05:13:15 +0000 (+0000) Subject: Merged revisions 2947-2948 via svnmerge from X-Git-Url: http://git.tremily.us/?a=commitdiff_plain;h=b1bcb1463dd3e508d62fbb98acd536a8997fed3d;p=scons.git Merged revisions 2947-2948 via svnmerge from http://scons.tigris.org/svn/scons/branches/core ........ r2947 | GregNoel | 2008-05-17 18:45:25 -0700 (Sat, 17 May 2008) | 1 line Revise text about VariantDir ........ git-svn-id: http://scons.tigris.org/svn/scons/trunk@2949 fdb21ef1-2011-0410-befe-b5e4ea1792b1 --- diff --git a/doc/man/scons.1 b/doc/man/scons.1 index c06c447f..cbc25696 100644 --- a/doc/man/scons.1 +++ b/doc/man/scons.1 @@ -2699,17 +2699,17 @@ env.SourceCode('.', env.BitKeeper()) .TP .RI env.BuildDir( build_dir ", " src_dir ", [" duplicate ]) Synonyms for -.B VariantDir() +.BR VariantDir () and -.BR env.VariantDir() . +.BR env.VariantDir (). The .I build_dir -argument bedomes the +argument becomes the .I variant_dir argument of -.B VariantDir() +.BR VariantDir () or -.BR env.VariantDir() . +.BR env.VariantDir (). (This will be officially deprecated some day.) '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" @@ -5027,39 +5027,43 @@ named values to export to the .IR script(s) ". " These variables are locally exported only to the specified .IR script(s) , -and do not affect the -global pool of variables used by -the +and do not affect the global pool of variables used by the .BR Export () function. -'\"If multiple dirs are provided, -'\"each script gets a fresh export. +'\"If multiple dirs are provided, each script gets a fresh export. The subsidiary .I script(s) must use the .BR Import () function to import the variables. -The optional +In effect, the optional .I variant_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 +argument causes the files (and subdirectories) in the directory where +.I script +resides to be copied to +.I variant_dir +and the build performed in +.IR variant_dir . +Thus, all of the targets (for example, object files and executables) +that would normally be built in (or underneath) the directory containing .I script -resides should actually -be built in +would actually be built in (or underneath) .IR variant_dir . +See the description of the +.BR VariantDir () +function below for the details and restrictions. .I variant_dir is interpreted relative to the directory of the calling SConscript file. -The optional +Normally, the source for the variant build is the directory containing +.IR script . +If the sources are not in +.IR script 's +directory, the optional .I src_dir -argument specifies that the -source files from which -the target files should be built -can be found in -.IR src_dir . +argument provides the location of the sources. .I src_dir is interpreted relative to the directory of the calling SConscript file. @@ -5068,24 +5072,15 @@ By default, .B scons will link or copy (depending on the platform) all the source files into the variant directory tree. -This behavior may be disabled by -setting the optional +This behavior may be disabled by setting the optional .I duplicate -argument to 0 -(it is set to 1 by default), -in which case +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 +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.) +See the description for +.BR VariantDir () +below for the details and restrictions. Any variables returned by .I script @@ -5896,75 +5891,62 @@ env.UpdateValue(target = Value(output), source = Value(input)) .RI VariantDir( variant_dir ", " src_dir ", [" duplicate ]) .TP .RI env.VariantDir( variant_dir ", " src_dir ", [" duplicate ]) -This specifies a variant directory tree +In effect, the +.I src_dir +directory tree is copied to .I variant_dir -in which to build all derived files -that would normally be built under -.IR src_dir . -Multiple directory trees -can be set up for multiple build variants. +so a build can be performed there. +.BR VariantDir () +can be called multiple times with the same +.I src_dir +to set up multiple builds with different options +.RI ( variants ). .I src_dir -must be underneath the SConstruct file's directory, -and +must be in or underneath the SConstruct file's directory, and .I variant_dir may not be underneath the .I src_dir . The default behavior is for .B scons -to duplicate all of the files in the tree underneath -.I src_dir -into -.IR variant_dir , -and then build the derived files within the copied tree. -(The duplication is performed by -linking or copying, -depending on the platform; see also the +to duplicate the source files in the variant tree +and then build the derived files within the variant tree. +This guarantees correct builds regardless of +whether intermediate source files are generated during the build, +whether preprocessors or other scanners search for included files +relative to the source file, +or whether individual compilers or other invoked tools are hard-coded +to put derived files in the same directory as source files. + +If possible on the platform, +the duplication is performed by linking rather than copying; +see also the .IR --duplicate -option.) -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 +command-line option. +Moreover, only the files needed for the build are duplicated; +files and directories that are not used are not present in +.IR variant_dir . + +Duplicating the source tree may be disabled by setting .I duplicate to 0. This will cause .B scons -to invoke Builders using the -path names of source files in +to invoke Builders using the path names of source files in .I src_dir and the path names of derived files within .IR variant_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, -or if any invoked tools are hard-coded to -put derived files in the same directory as the source files. - -Note that specifying a -.B VariantDir -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 +and is usually safe for most builds +(but see above for cases that may cause problems). + +Note that +.BR VariantDir () +works most naturally with a subsidiary SConscript file. +However, you would then call the subsidiary SConscript file +not in the source directory, but in the .I variant_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 @@ -5982,11 +5964,9 @@ SConscript('build-variant2/SConscript') .IP See also the .BR SConscript () -function, described below, -for another way to -specify a variant directory -in conjunction with calling a subsidiary -SConscript file.) +function, described above, +for another way to specify a variant directory +in conjunction with calling a subsidiary SConscript file. '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" .TP @@ -6343,7 +6323,7 @@ specifies a file which collects the output from commands that are executed to check for the existence of header files, libraries, etc. The default is the file #/config.log. If you are using the -.B VariantDir +.BR VariantDir () method, you may want to specify a subdirectory under your variant directory. .I config_h @@ -8592,26 +8572,30 @@ This is sometimes necessary on Windows systems when a path references a file on other (POSIX) systems. .IP srcpath -The directory and file name to the source file linked to this file -through VariantDir. If this file isn't linked, it just returns the -directory and filename unchanged. +The directory and file name to the source file linked to this file through +.BR VariantDir (). +If this file isn't linked, +it just returns the directory and filename unchanged. .IP srcdir -The directory containing the source file linked to this file -through VariantDir. If this file isn't linked, it just returns the -directory part of the filename. +The directory containing the source file linked to this file through +.BR VariantDir (). +If this file isn't linked, +it just returns the directory part of the filename. .IP rsrcpath -The directory and file name to the source file linked to this file -through VariantDir. If the file does not exist locally but exists in -a Repository, the path in the Repository is returned. +The directory and file name to the source file linked to this file through +.BR VariantDir (). +If the file does not exist locally but exists in a Repository, +the path in the Repository is returned. If this file isn't linked, it just returns the directory and filename unchanged. .IP rsrcdir -The Repository directory containing the source file linked to this file -through VariantDir. If this file isn't linked, it just returns the -directory part of the filename. +The Repository directory containing the source file linked to this file through +.BR VariantDir (). +If this file isn't linked, +it just returns the directory part of the filename. .LP For example, the specified target will