summaryrefslogtreecommitdiffstats
path: root/doc/user/builders-writing.in
diff options
context:
space:
mode:
Diffstat (limited to 'doc/user/builders-writing.in')
-rw-r--r--doc/user/builders-writing.in158
1 files changed, 112 insertions, 46 deletions
diff --git a/doc/user/builders-writing.in b/doc/user/builders-writing.in
index d911f6c..50c9114 100644
--- a/doc/user/builders-writing.in
+++ b/doc/user/builders-writing.in
@@ -167,17 +167,22 @@ This functionality could be invoked as in the following example:
<file name="SConstruct">
bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
env = Environment(BUILDERS = {'Foo' : bld})
+ import os
+ env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd()
env.Foo('file.foo', 'file.input')
</file>
<file name="file.input">
file.input
</file>
+ <file name="foobuild" chmod="0755">
+ cat
+ </file>
</scons_example>
- <programlisting>
+ <sconstruct>
bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
env = Environment(BUILDERS = {'Foo' : bld})
- </programlisting>
+ </sconstruct>
<para>
@@ -197,7 +202,7 @@ This functionality could be invoked as in the following example:
</para>
<scons_output example="ex1">
- <command>scons</command>
+ <command>scons -Q</command>
</scons_output>
<para>
@@ -229,23 +234,8 @@ This functionality could be invoked as in the following example:
</file>
</scons_example>
- <!--
- scons: Reading SConscript files ...
- other errors
- Traceback (most recent call last):
- File "/usr/lib/scons/SCons/Script/__init__.py", line 901, in main
- _main()
- File "/usr/lib/scons/SCons/Script/__init__.py", line 762, in _main
- SCons.Script.SConscript.SConscript(script)
- File "/usr/lib/scons/SCons/Script/SConscript.py", line 207, in SConscript
- exec _file_ in stack[-1].globals
- File "SConstruct", line 4, in ?
- env.Program('hello.c')
- scons: Environment instance has no attribute 'Program'
- -->
-
<scons_output example="ex2">
- <command>scons</command>
+ <command>scons -Q</command>
</scons_output>
<para>
@@ -260,6 +250,8 @@ This functionality could be invoked as in the following example:
<scons_example name="ex3">
<file name="SConstruct">
env = Environment()
+ import os
+ env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd()
bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
env.Append(BUILDERS = {'Foo' : bld})
env.Foo('file.foo', 'file.input')
@@ -271,8 +263,19 @@ This functionality could be invoked as in the following example:
<file name="hello.c">
hello.c
</file>
+ <file name="foobuild" chmod="0755">
+ cat
+ </file>
</scons_example>
+ <sconstruct>
+ env = Environment()
+ bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
+ env.Append(BUILDERS = {'Foo' : bld})
+ env.Foo('file.foo', 'file.input')
+ env.Program('hello.c')
+ </sconstruct>
+
<para>
Or you can explicitly set the appropriately-named
@@ -280,13 +283,13 @@ This functionality could be invoked as in the following example:
</para>
- <programlisting>
+ <sconstruct>
env = Environment()
bld = Builder(action = 'foobuild < $SOURCE > $TARGET')
env['BUILDERS']['Foo'] = bld
env.Foo('file.foo', 'file.input')
env.Program('hello.c')
- </programlisting>
+ </sconstruct>
<para>
@@ -298,7 +301,7 @@ This functionality could be invoked as in the following example:
</para>
<scons_output example="ex3">
- <command>scons</command>
+ <command>scons -Q</command>
</scons_output>
</section>
@@ -324,11 +327,13 @@ This functionality could be invoked as in the following example:
</para>
<scons_example name="ex4">
- <file name="SConstruct" printme="1">
- bld = Builder(action = 'foobuild < $TARGET > $SOURCE',
+ <file name="SConstruct">
+ bld = Builder(action = 'foobuild < $SOURCE > $TARGET',
suffix = '.foo',
src_suffix = '.input')
env = Environment(BUILDERS = {'Foo' : bld})
+ import os
+ env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd()
env.Foo('file1')
env.Foo('file2')
</file>
@@ -338,10 +343,22 @@ This functionality could be invoked as in the following example:
<file name="file2.input">
file2.input
</file>
+ <file name="foobuild" chmod="0755">
+ cat
+ </file>
</scons_example>
+ <sconstruct>
+ bld = Builder(action = 'foobuild < $SOURCE > $TARGET',
+ suffix = '.foo',
+ src_suffix = '.input')
+ env = Environment(BUILDERS = {'Foo' : bld})
+ env.Foo('file1')
+ env.Foo('file2')
+ </sconstruct>
+
<scons_output example="ex4">
- <command>scons</command>
+ <command>scons -Q</command>
</scons_output>
<para>
@@ -370,7 +387,7 @@ This functionality could be invoked as in the following example:
<programlisting>
def build_function(target, source, env):
- # XXX
+ # Code to build "target" from "source"
return None
</programlisting>
@@ -459,7 +476,7 @@ This functionality could be invoked as in the following example:
<scons_example name="ex5">
<file name="SConstruct" printme="1">
def build_function(target, source, env):
- # XXX
+ # Code to build "target" from "source"
return None
bld = Builder(action = build_function,
suffix = '.foo',
@@ -482,7 +499,7 @@ This functionality could be invoked as in the following example:
</para>
<scons_output example="ex5">
- <command>scons</command>
+ <command>scons -Q</command>
</scons_output>
</section>
@@ -494,14 +511,16 @@ This functionality could be invoked as in the following example:
&SCons; Builder objects can create an action "on the fly"
by using a function called a &generator;.
- This provides a great deal of flexibility XXX
+ This provides a great deal of flexibility to
+ construct just the right list of commands
+ to build your target.
A &generator; looks like:
</para>
<programlisting>
def generate_actions(source, target, env, for_signature):
- return XXX
+ return 'foobuild < %s > %s' % (target[0], source[0])
</programlisting>
<para>
@@ -575,7 +594,7 @@ This functionality could be invoked as in the following example:
generator is being called to contribute to a build signature,
as opposed to actually executing the command.
- XXX
+ <!-- XXX NEED MORE HERE -->
</para>
</listitem>
@@ -602,20 +621,37 @@ This functionality could be invoked as in the following example:
</para>
<scons_example name="ex6">
- <file name="SConstruct" printme="1">
+ <file name="SConstruct">
+ def generate_actions(source, target, env, for_signature):
+ return 'foobuild < %s > %s' % (source[0], target[0])
bld = Builder(generator = generate_actions,
suffix = '.foo',
src_suffix = '.input')
env = Environment(BUILDERS = {'Foo' : bld})
+ import os
+ env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd()
env.Foo('file')
</file>
<file name="file.input">
file.input
</file>
+ <file name="foobuild" chmod="0755">
+ cat
+ </file>
</scons_example>
+ <sconstruct>
+ def generate_actions(source, target, env, for_signature):
+ return 'foobuild < %s > %s' % (source[0], target[0])
+ bld = Builder(generator = generate_actions,
+ suffix = '.foo',
+ src_suffix = '.input')
+ env = Environment(BUILDERS = {'Foo' : bld})
+ env.Foo('file')
+ </sconstruct>
+
<scons_output example="ex6">
- <command>scons</command>
+ <command>scons -Q</command>
</scons_output>
<para>
@@ -641,23 +677,46 @@ This functionality could be invoked as in the following example:
</para>
<scons_example name="ex7">
- <file name="SConstruct" printme="1">
- def modify_targets(XXX):
- return XXX
- bld = Builder(action = 'XXX',
+ <file name="SConstruct">
+ def modify_targets(target, source, env):
+ target.append('new_target')
+ source.append('new_source')
+ return target, source
+ bld = Builder(action = 'foobuild $TARGETS - $SOURCES',
suffix = '.foo',
src_suffix = '.input',
emitter = modify_targets)
env = Environment(BUILDERS = {'Foo' : bld})
+ import os
+ env['ENV']['PATH'] = env['ENV']['PATH'] + os.pathsep + os.getcwd()
env.Foo('file')
</file>
<file name="file.input">
file.input
</file>
- </programlisting>
+ <file name="new_source">
+ new_source
+ </file>
+ <file name="foobuild" chmod="0755">
+ cat
+ </file>
+ </scons_example>
+
+ <sconstruct>
+ def modify_targets(target, source, env):
+ target.append('new_target')
+ source.append('new_source')
+ return target, source
+ bld = Builder(action = 'foobuild $TARGETS - $SOURCES',
+ suffix = '.foo',
+ src_suffix = '.input',
+ emitter = modify_targets)
+ env = Environment(BUILDERS = {'Foo' : bld})
+ env.Foo('file')
+ </sconstruct>
<scons_output example="ex7">
- <command>scons</command>
+ <command>scons -Q</command>
</scons_output>
<programlisting>
@@ -665,10 +724,10 @@ This functionality could be invoked as in the following example:
suffix = '.foo',
src_suffix = '.input',
emitter = 'MY_EMITTER')
- def modify1(XXX):
- return XXX
- def modify2(XXX):
- return XXX
+ def modify1(target, source, env):
+ return target, source
+ def modify2(target, source, env):
+ return target, source
env1 = Environment(BUILDERS = {'Foo' : bld},
MY_EMITTER = modify1)
env2 = Environment(BUILDERS = {'Foo' : bld},
@@ -679,6 +738,8 @@ This functionality could be invoked as in the following example:
</section>
+ <!--
+
<section>
<title>Builders That Use Other Builders</title>
@@ -691,13 +752,18 @@ This functionality could be invoked as in the following example:
<scons_example name="ex8">
<file name="SConstruct" printme="1">
env = Environment()
- env.SourceCode('.', env.BitKeeper('XXX'))
+ #env.SourceCode('.', env.BitKeeper('XXX'))
env.Program('hello.c')
</file>
- </programlisting>
+ <file name="hello.c">
+ hello.c
+ </file>
+ </scons_example>
<scons_output example="ex8">
- <command>scons</command>
+ <command>scons -Q</command>
</scons_output>
</section>
+
+ -->