diff options
Diffstat (limited to 'doc/user')
| -rw-r--r-- | doc/user/MANIFEST | 1 | ||||
| -rw-r--r-- | doc/user/README | 19 | ||||
| -rw-r--r-- | doc/user/add-method.in | 105 | ||||
| -rw-r--r-- | doc/user/add-method.xml | 100 | ||||
| -rw-r--r-- | doc/user/main.in | 8 | ||||
| -rw-r--r-- | doc/user/main.xml | 8 |
6 files changed, 237 insertions, 4 deletions
diff --git a/doc/user/MANIFEST b/doc/user/MANIFEST index 565298f..b3106af 100644 --- a/doc/user/MANIFEST +++ b/doc/user/MANIFEST @@ -1,4 +1,5 @@ actions.xml +add-method.xml alias.xml ant.xml builders.xml diff --git a/doc/user/README b/doc/user/README new file mode 100644 index 0000000..7bca314 --- /dev/null +++ b/doc/user/README @@ -0,0 +1,19 @@ +# __COPYRIGHT__ + +When adding a new file, add it to main.xml and MANIFEST. + +To build the .xml files from the .in files: + scons -D . BUILDDOC=1 + +Writing examples: here's a simple template. + + <scons_example name="Foo"> + <file name="SConstruct"> + env = Environment() + print env.Dump("CC") + </file> + </scons_example> + + <scons_output example="Foo"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> diff --git a/doc/user/add-method.in b/doc/user/add-method.in new file mode 100644 index 0000000..853b9a8 --- /dev/null +++ b/doc/user/add-method.in @@ -0,0 +1,105 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + + <para> + + The env.AddMethod(function, [name]) function is used to add a method + to an environment. It's typically used to add a "pseudo-builder" or + wrap up a call to multiple builders. In the first example, we want + to install the program into the standard bin dir, but also copy it + into a local install/bin dir that might be used to build a package + from. + + </para> + + <scons_example name="ex1"> + <file name="SConstruct" printme="1"> + def install_in_bin_dirs(env, source): + """Install source in both bin dirs""" + i1 = env.Install("$BIN", source) + i2 = env.Install("$LOCALBIN", source) + return [i1[0], i2][0] # Return a list, like a normal builder + env = Environment(BIN='/usr/bin', LOCALBIN='#install/bin') + env.AddMethod(install_in_bin_dirs, "InstallInBinDirs") + env.InstallInBinDirs(Program('hello.c')) # installs hello in both bin dirs + </file> + <file name="hello.c"> + int main() { printf("Hello, world!\n"); } + </file> + </scons_example> + + <para> + This produces the following: + </para> + + <scons_output example="ex1"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + + <para> + + It also gives more flexibility in parsing arguments than you can get + with a builder. The next example shows a pseudo-builder with a + named argument that modifies the filename, and a separate argument + for the resource file (rather than having the builder figure it out + by file extension). Also this example demonstrates using the global + AddMethod function to add a method to the global Environment class, + so it will be used in all subsequently created environments. + + </para> + + <scons_example name="ex2"> + <file name="SConstruct" printme="1"> + import sys; + def BuildTestProg(env, testfile, resourcefile, testdir="tests"): + """Build the test program; + prepends "test_" to src and target, and puts target into testdir.""" + srcfile="test_%s.c"%testfile + if sys.platform=='win32': + target="%s/test_%s$EXESUFFIX"%(testdir,[testfile, resourcefile]) + else: + target="%s/test_%s$EXESUFFIX"%(testdir,testfile) + p = env.Program(target, srcfile) + return p + AddMethod(Environment, BuildTestProg) + + # Now use it + env=Environment() + env.BuildTestProg('stuff', resourcefile='res.rc') + </file> + <file name="test_stuff.c"> + int main() { printf("Hello, world!\n"); } + </file> + </scons_example> + + <para> + This produces the following (on Linux, anyway; Windows would include the + resource file): + </para> + + <scons_output example="ex2"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + diff --git a/doc/user/add-method.xml b/doc/user/add-method.xml new file mode 100644 index 0000000..22f5f1a --- /dev/null +++ b/doc/user/add-method.xml @@ -0,0 +1,100 @@ +<!-- + + __COPYRIGHT__ + + Permission is hereby granted, free of charge, to any person obtaining + a copy of this software and associated documentation files (the + "Software"), to deal in the Software without restriction, including + without limitation the rights to use, copy, modify, merge, publish, + distribute, sublicense, and/or sell copies of the Software, and to + permit persons to whom the Software is furnished to do so, subject to + the following conditions: + + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY + KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE + WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND + NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE + LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION + OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION + WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> + + <para> + + The env.AddMethod(function, [name]) function is used to add a method + to an environment. It's typically used to add a "pseudo-builder" or + wrap up a call to multiple builders. In the first example, we want + to install the program into the standard bin dir, but also copy it + into a local install/bin dir that might be used to build a package + from. + + </para> + + <programlisting> + def install_in_bin_dirs(env, source): + """Install source in both bin dirs""" + i1 = env.Install("$BIN", source) + i2 = env.Install("$LOCALBIN", source) + return [i1[0], i2][0] # Return a list, like a normal builder + env = Environment(BIN='/usr/bin', LOCALBIN='#install/bin') + env.AddMethod(install_in_bin_dirs, "InstallInBinDirs") + env.InstallInBinDirs(Program('hello.c')) # installs hello in both bin dirs + </programlisting> + + <para> + This produces the following: + </para> + + <screen> + % <userinput>scons -Q</userinput> + cc -o hello.o -c hello.c + cc -o hello hello.o + Install file: "hello" as "install/bin/hello" + </screen> + + <para> + + It also gives more flexibility in parsing arguments than you can get + with a builder. The next example shows a pseudo-builder with a + named argument that modifies the filename, and a separate argument + for the resource file (rather than having the builder figure it out + by file extension). Also this example demonstrates using the global + AddMethod function to add a method to the global Environment class, + so it will be used in all subsequently created environments. + + </para> + + <programlisting> + import sys + def BuildTestProg(env, testfile, resourcefile, testdir="tests"): + """Build the test program; + prepends "test_" to src and target, and puts target into testdir.""" + srcfile="test_%s.c"%testfile + if sys.platform=='win32': + target="%s/test_%s$EXESUFFIX"%(testdir,[testfile, resourcefile]) + else: + target="%s/test_%s$EXESUFFIX"%(testdir,testfile) + p = env.Program(target, srcfile) + return p + AddMethod(Environment, BuildTestProg) + + # Now use it + env=Environment() + env.BuildTestProg('stuff', resourcefile='res.rc') + </programlisting> + + <para> + This produces the following (on Linux, anyway; Windows would include the + resource file): + </para> + + <screen> + % <userinput>scons -Q</userinput> + cc -o test_stuff.o -c test_stuff.c + cc -o tests/test_stuff test_stuff.o + </screen> + diff --git a/doc/user/main.in b/doc/user/main.in index 4095e6b..8981b14 100644 --- a/doc/user/main.in +++ b/doc/user/main.in @@ -51,6 +51,7 @@ <!ENTITY builders-built-in SYSTEM "builders-built-in.xml"> <!ENTITY builders-commands SYSTEM "builders-commands.xml"> <!ENTITY builders-writing SYSTEM "builders-writing.xml"> + <!ENTITY add-method SYSTEM "add-method.xml"> <!ENTITY caching SYSTEM "caching.xml"> <!ENTITY command-line SYSTEM "command-line.xml"> <!ENTITY copyright SYSTEM "copyright.xml"> @@ -138,8 +139,6 @@ XXX Progress() - XXX AddMethod() - XXX - - diskcheck= XXX site_scons @@ -295,6 +294,11 @@ &builders-commands; </chapter> + <chapter id="chap-add-method"> + <title>Pseudo-Builders: the AddMethod function</title> + &add-method; + </chapter> + <!-- XXX Action() diff --git a/doc/user/main.xml b/doc/user/main.xml index 4095e6b..8981b14 100644 --- a/doc/user/main.xml +++ b/doc/user/main.xml @@ -51,6 +51,7 @@ <!ENTITY builders-built-in SYSTEM "builders-built-in.xml"> <!ENTITY builders-commands SYSTEM "builders-commands.xml"> <!ENTITY builders-writing SYSTEM "builders-writing.xml"> + <!ENTITY add-method SYSTEM "add-method.xml"> <!ENTITY caching SYSTEM "caching.xml"> <!ENTITY command-line SYSTEM "command-line.xml"> <!ENTITY copyright SYSTEM "copyright.xml"> @@ -138,8 +139,6 @@ XXX Progress() - XXX AddMethod() - XXX - - diskcheck= XXX site_scons @@ -295,6 +294,11 @@ &builders-commands; </chapter> + <chapter id="chap-add-method"> + <title>Pseudo-Builders: the AddMethod function</title> + &add-method; + </chapter> + <!-- XXX Action() |