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

1 files changed, 89 insertions, 105 deletions

diff --git a/doc/man/scons.1 b/doc/man/scons.1
index c06c447..cbc2569 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