Document the fact that Builder calls return Node objects.

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

diff --git a/doc/man/scons.1 b/doc/man/scons.1
index 25b046c30a946dd798c0674b92d4f4eaae0cb30e..895742c61de244aecd4b2a7d040efb435f99959f 100644 (file)
--- a/doc/man/scons.1
+++ b/doc/man/scons.1
@@ -867,6 +867,28 @@ or generate a shared library with a nonstandard suffix:
 env.SharedLibrary('word', 'word.cpp', SHLIBSUFFIX='.ocx')
 .EE
 
+All builders return an object
+representing the target that will be created.
+This object may be used as a source for
+another build,
+or in any other context in
+which a file name would otherwise be specified.
+For example, if it were necessary
+to add a specific
+.B -D
+flag when compiling one specific object file:
+
+.ES
+bar_obj = env.StaticObject('bar.c', CCFLAGS='-DBAR')
+env.Program(source = ['foo.c', bar_obj, 'main.c'])
+.EE
+
+Using an object in this way
+makes for a more portable build
+by avoiding having to specify
+a platform-specific object suffix
+when calling the Program() builder.
+
 .B scons
 provides the following builders:
 

diff --git a/src/CHANGES.txt b/src/CHANGES.txt
index ebb9f72a581fc374e101c23e9f4681a58eec7ee3..957209f13ca16d90e137cfabdd2cf7eec2766698 100644 (file)
--- a/src/CHANGES.txt
+++ b/src/CHANGES.txt
@@ -54,6 +54,8 @@ RELEASE 0.09 -
   - Add separate $SHOBJPREFIX and $SHOBJSUFFIX construction variables
     (by default, the same as $OBJPREFIX and $OBJSUFFIX).
 
+  - Man page:  document the fact that Builder calls return Node objects.
+
  From Steve LeBlanc:
 
   - Refactor option processing to use our own version of Greg Ward's