Better documentation of exporting variables to SConscript files.

git-svn-id: http://scons.tigris.org/svn/scons/trunk@602 fdb21ef1-2011-0410-befe-b5e4ea1792b1

diff --git a/doc/man/scons.1 b/doc/man/scons.1
index 0bfb13b4c078819b3dc8e6f597931741c825020d..f9a6ea984a82d634d0ea48c851a2f6b29948d428 100644 (file)
--- a/doc/man/scons.1
+++ b/doc/man/scons.1
@@ -3082,18 +3082,36 @@ EnsureSConsVersion(0,9)
 This tells 
 .B scons
 to export a list of variables from the current
-SConscript file to all other SConscript files. The exported variables
-are kept in a global collection, so subsequent exports
+SConscript file to all other SConscript files.
+The exported variables are kept in a global collection,
+so subsequent calls to
+.BR Export ()
 will over-write previous exports that have the same name. 
 Multiple variable names should be passed to
 .BR Export ()
 as separate arguments. Examples:
 
 .ES
+env = Environment()
+# Make env available for all SConscript files to Import().
 Export("env")
-Export("env", "variable")
+
+package = 'my_name'
+# Make env and package available for all SConscript files to Import().
+Export("env", "package")
 .EE
 
+.IP
+Note that the
+.BR SConscript ()
+function supports an
+.I exports
+argument that makes it easier to to export a variable or
+set of variables to a single SConscript file.
+See the description of the
+.BR SConscript ()
+function, below.
+
 .TP 
 .RI File( name ", [" directory ])
 This returns an object that represents a given file 
@@ -3286,12 +3304,24 @@ This tells
 .B scons
 to execute
 .I script
-as a SConscript (configuration) file. The optional 
+as a SConscript (configuration) file.
+
+The optional 
 .I exports
 argument provides a list of variable names to export to
 .IR script ". "
+These variables are locally exported only to the specified
+.IR script ,
+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.
+The subsidiary
 .I script
-must use the
+file must use the
 .BR Import ()
 function to import the variables.
 
@@ -3332,7 +3362,7 @@ 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.
+are generated by the build.)
 
 Any variables returned by 
 .I script 
@@ -3344,9 +3374,11 @@ will be returned by the call to
 Examples:
 
 .ES
-SConscript('dir/SConscript')
-foo = SConscript('subdir/SConscript', "env")
+SConscript('subdir/SConscript')
+foo = SConscript('sub/SConscript', exports='env')
+SConscript('dir/SConscript', exports=['env', 'variable'])
 SConscript('src/SConscript', build_dir='build', duplicate=0)
+SConscript('bld/SConscript', src_dir='src', exports='env')
 .EE
 
 .TP

diff --git a/src/CHANGES.txt b/src/CHANGES.txt
index ccdf1595e564e016ad8e8ec525417f3c68327929..0ac801ceaf9fc8fe509ee401adef288fab6b7dba 100644 (file)
--- a/src/CHANGES.txt
+++ b/src/CHANGES.txt
@@ -44,6 +44,9 @@ RELEASE 0.12 - XXX
 
   - Add support for Tar and Zip files.
 
+  - Better documentation of the different ways to export variables to a
+    subsidiary SConscript file.
+
   From Lachlan O'Dea:
 
   - Add SharedObject() support to the masm tool.