Commits

Anonymous committed 93ac83a

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
........

  • Participants
  • Parent commits de95880

Comments (0)

Files changed (1)

 .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 should actually
-be built in
+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
+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
-.B scons
-will refer directly to
-the source files in their source directory
+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.)
+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