From 6c4dc321483d6a2a292fc5b83ccad761d4f5ed5a Mon Sep 17 00:00:00 2001
From: Gary Oberbrunner <garyo@oberbrunner.com>
Date: Thu, 17 Jun 2010 01:51:41 +0000
Subject: Add Users Guide example of generating source code.

---
 doc/user/tasks.in  | 67 +++++++++++++++++++++++++++++++++++++++++++++++++++++-
 doc/user/tasks.xml | 58 +++++++++++++++++++++++++++++++++++++++++++++-
 src/CHANGES.txt    |  4 ++++
 3 files changed, 127 insertions(+), 2 deletions(-)

diff --git a/doc/user/tasks.in b/doc/user/tasks.in
index 8823189..9608f6a 100644
--- a/doc/user/tasks.in
+++ b/doc/user/tasks.in
@@ -29,7 +29,7 @@ on as they become more complex. Most build tools have special
 purpose constructs for performing these tasks, but since &SConscript;
 files are &Python; scripts, you can use more flexible built-in &Python;
 services to perform these tasks. This appendix lists a number of these
-tasks and how to implement them in &Python;.
+tasks and how to implement them in &Python; and &Scons;.
 </para>
 
 <example>
@@ -79,3 +79,68 @@ output</title>
 output = os.popen(command).read()
 </programlisting>
 </example>
+
+<example>
+<title>Generating source code: how code can be generated and used by SCons</title>
+
+<para>
+
+The Copy builders here could be any arbitrary shell or python function
+that produces one or more files.  This example shows how to create
+those files and use them in &SCons;.
+
+</para>
+
+<scons_example name="ex1">
+<file name="SConstruct" printme="1">
+#### SConstruct
+env = Environment()
+env.Append(CPPPATH = "#")
+
+## Header example
+env.Append(BUILDERS =
+   {'Copy1' : Builder(action = 'cat < $SOURCE > $TARGET',
+                      suffix='.h', src_suffix='.bar')})
+env.Copy1('test.bar') # produces test.h from test.bar. 
+env.Program('app','main.cpp') # indirectly depends on test.bar
+
+## Source file example
+env.Append(BUILDERS =
+  {'Copy2' : Builder(action = 'cat < $SOURCE > $TARGET',
+                     suffix='.cpp', src_suffix='.bar2')})
+foo = env.Copy2('foo.bar2') # produces foo.cpp from foo.bar2. 
+env.Program('app2',['main2.cpp'] + foo) # compiles main2.cpp and foo.cpp into app2.
+</file>
+
+<file name="main.cpp">
+#include "test.h"
+</file>
+<file name="test.bar">
+// nothing here
+</file>
+<file name="main2.cpp">
+//// main2.cpp
+</file>
+<file name="foo.bar2">
+// nothing here
+</file>
+</scons_example>
+
+<para>
+
+Where main.cpp looks like this:
+
+</para>
+
+ <scons_example_file example="ex1" name="main.cpp">
+ </scons_example_file>
+
+<para>
+produces this:
+</para>
+
+ <scons_output example="ex1">
+    <scons_output_command>scons -Q</scons_output_command>
+ </scons_output>
+    
+</example>
diff --git a/doc/user/tasks.xml b/doc/user/tasks.xml
index 8823189..fe99fa6 100644
--- a/doc/user/tasks.xml
+++ b/doc/user/tasks.xml
@@ -29,7 +29,7 @@ on as they become more complex. Most build tools have special
 purpose constructs for performing these tasks, but since &SConscript;
 files are &Python; scripts, you can use more flexible built-in &Python;
 services to perform these tasks. This appendix lists a number of these
-tasks and how to implement them in &Python;.
+tasks and how to implement them in &Python; and &Scons;.
 </para>
 
 <example>
@@ -79,3 +79,59 @@ output</title>
 output = os.popen(command).read()
 </programlisting>
 </example>
+
+<example>
+<title>Generating source code: how code can be generated and used by SCons</title>
+
+<para>
+
+The Copy builders here could be any arbitrary shell or python function
+that produces one or more files.  This example shows how to create
+those files and use them in &SCons;.
+
+</para>
+
+<programlisting>
+#### SConstruct
+env = Environment()
+env.Append(CPPPATH = "#")
+
+## Header example
+env.Append(BUILDERS =
+   {'Copy1' : Builder(action = 'cat &lt; $SOURCE &gt; $TARGET',
+                      suffix='.h', src_suffix='.bar')})
+env.Copy1('test.bar') # produces test.h from test.bar. 
+env.Program('app','main.cpp') # indirectly depends on test.bar
+
+## Source file example
+env.Append(BUILDERS =
+  {'Copy2' : Builder(action = 'cat &lt; $SOURCE &gt; $TARGET',
+                     suffix='.cpp', src_suffix='.bar2')})
+foo = env.Copy2('foo.bar2') # produces foo.cpp from foo.bar2. 
+env.Program('app2',['main2.cpp'] + foo) # compiles main2.cpp and foo.cpp into app2.
+</programlisting>
+
+<para>
+
+Where main.cpp looks like this:
+
+</para>
+
+ 
+ <programlisting>
+#include "test.h"
+</programlisting>
+
+<para>
+produces this:
+</para>
+
+ <screen>
+    % <userinput>scons -Q</userinput>
+    cc -o app main.cpp
+    cat &lt; foo.bar2 &gt; foo.cpp
+    cc -o app2 main2.cpp foo.cpp
+    cat &lt; test.bar &gt; test.h
+ </screen>
+    
+</example>
diff --git a/src/CHANGES.txt b/src/CHANGES.txt
index f6a38e1..7962c57 100644
--- a/src/CHANGES.txt
+++ b/src/CHANGES.txt
@@ -7,6 +7,10 @@
 
 RELEASE 2.1.0.alpha.yyyymmdd - NEW DATE WILL BE INSERTED HERE
 
+  From Bauke Conijn:
+
+    - Added Users Guide example for auto-generated source code
+
   From Steven Knight:
 
     - Fix explicit dependencies (Depends()) on Nodes that don't have
-- 
cgit v0.12