summaryrefslogtreecommitdiffstats
path: root/doc/user
diff options
context:
space:
mode:
Diffstat (limited to 'doc/user')
-rw-r--r--doc/user/MANIFEST1
-rw-r--r--doc/user/README19
-rw-r--r--doc/user/add-method.in105
-rw-r--r--doc/user/add-method.xml100
-rw-r--r--doc/user/main.in8
-rw-r--r--doc/user/main.xml8
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()