.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.)
'\"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
.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.
.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
.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
.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
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
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
projects / scons.git / commitdiff