From 440e378dfbd9742b4e8fb215f00ebde10df982f6 Mon Sep 17 00:00:00 2001
From: stevenknight <stevenknight@fdb21ef1-2011-0410-befe-b5e4ea1792b1>
Date: Sat, 9 Aug 2003 04:05:57 +0000
Subject: [PATCH] Man page fixes.  (Gary Oberbrunner, SK)

git-svn-id: http://scons.tigris.org/svn/scons/trunk@763 fdb21ef1-2011-0410-befe-b5e4ea1792b1
---
 doc/man/scons.1 | 42 ++++++++++++++++++++++++++++++++++++++++--
 src/CHANGES.txt |  5 ++++-
 2 files changed, 44 insertions(+), 3 deletions(-)

diff --git a/doc/man/scons.1 b/doc/man/scons.1
index 13320203..8df46cf5 100644
--- a/doc/man/scons.1
+++ b/doc/man/scons.1
@@ -98,7 +98,7 @@ so you may use normal Python scripting capabilities
 (such as flow control, data manipulation, and imported Python libraries)
 to handle complicated build situations.
 .BR scons ,
-however, reads all of the SConscript files
+however, reads and executes all of the SConscript files
 .I before
 it begins building any targets.
 To make this obvious,
@@ -121,6 +121,34 @@ may be suppressed using the
 .B -Q
 option.
 
+.B scons
+does not automatically propagate
+the external environment used to execute
+.B scons
+to the commands used to build target files.
+This is so that builds will be guaranteed
+repeatable regardless of the environment
+variables set at the time
+.B scons
+is invoked.
+This also means that if the compiler or other commands
+that you want to use to build your target files
+are not in standard system locations,
+.B scons
+will not find them unless
+you explicitly set the PATH
+to include those locations.
+Whenever you create an
+.B scons
+construction environment,
+you can propagate the value of PATH
+from your external environment as follows:
+
+.ES
+import os
+env = Environment(ENV = {'PATH' : os.environ['PATH']})
+.EE
+
 .B scons
 can scan known input files automatically for dependency
 information (for example, #include statements
@@ -1939,7 +1967,17 @@ USERNAME.
 .RI AlwaysBuild( target ", ...)"
 Marks each given
 .I target
-so that it will always be rebuilt.
+so that it is always assumed to be out of date,
+and will always be rebuilt if needed.
+Note, however, that
+.BR AlwaysBuild ()
+does not add its target(s) to the default target list,
+so the targets will only be built
+if they are specified on the command line,
+or are a dependent of a target specified on the command line--but
+they will
+.I always
+be built if so specified.
 Multiple targets can be passed in to a single call to
 .BR AlwaysBuild ().
 
diff --git a/src/CHANGES.txt b/src/CHANGES.txt
index 9e9e7747..3df58e6e 100644
--- a/src/CHANGES.txt
+++ b/src/CHANGES.txt
@@ -32,7 +32,8 @@ RELEASE 0.XX - XXX
   - Make builder prefixes work correctly when deducing a target
     from a source file name in another directory.
 
-  - Documentation fixes:  typo in the man page.
+  - Documentation fixes: typo in the man page; explain up-front about
+    not propagating the external environment.
 
   - Use "cvs co -d" instead of "cvs co -p >" when checking out something
     from CVS with a specified module name.  This avoids zero-length
@@ -112,6 +113,8 @@ RELEASE 0.XX - XXX
   - Initialize the LIB environment variable when using the Intel
     compiler (icl).
 
+  - Documentation fixes:  better explain the AlwaysBuild() function.
+
   From Laurent Pelecq:
 
   - When the -debug=pdb option is specified, use pdb.Pdb().runcall() to
-- 
2.26.2