diff options
Diffstat (limited to 'doc/user')
| -rw-r--r-- | doc/user/add-method.in | 8 | ||||
| -rw-r--r-- | doc/user/add-method.xml | 6 | ||||
| -rw-r--r-- | doc/user/builders-writing.in | 138 | ||||
| -rw-r--r-- | doc/user/builders-writing.xml | 123 | ||||
| -rw-r--r-- | doc/user/main.in | 6 | ||||
| -rw-r--r-- | doc/user/main.xml | 6 |
6 files changed, 274 insertions, 13 deletions
diff --git a/doc/user/add-method.in b/doc/user/add-method.in index 853b9a8..a0a6039 100644 --- a/doc/user/add-method.in +++ b/doc/user/add-method.in @@ -72,7 +72,7 @@ <scons_example name="ex2"> <file name="SConstruct" printme="1"> - import sys; + import sys def BuildTestProg(env, testfile, resourcefile, testdir="tests"): """Build the test program; prepends "test_" to src and target, and puts target into testdir.""" @@ -103,3 +103,9 @@ <scons_output_command>scons -Q</scons_output_command> </scons_output> + <para> + Using AddMethod is better than just adding an instance method to an + Environment because it gets called as a proper method, and AddMethod + provides for copying the method to any copies of the Environment + instance. + </para> diff --git a/doc/user/add-method.xml b/doc/user/add-method.xml index 22f5f1a..7e84b80 100644 --- a/doc/user/add-method.xml +++ b/doc/user/add-method.xml @@ -98,3 +98,9 @@ cc -o tests/test_stuff test_stuff.o </screen> + <para> + Using AddMethod is better than just adding an instance method to an + Environment because it gets called as a proper method, and AddMethod + provides for copying the method to any copies of the Environment + instance. + </para> diff --git a/doc/user/builders-writing.in b/doc/user/builders-writing.in index 2285ac8..67a95f9 100644 --- a/doc/user/builders-writing.in +++ b/doc/user/builders-writing.in @@ -761,6 +761,144 @@ This functionality could be invoked as in the following example: </section> + <section> + <title>Where To Put Your Custom Builders and Tools</title> + + <para> + + The <filename>site_scons</filename> directory gives you a place to + put Python modules you can import into your SConscripts + (site_scons), add-on tools that can integrate into &SCons; + (site_scons/site_tools), and a site_scons/site_init.py file that + gets read before any &SConstruct; or &SConscript;, allowing you to + change &SCons;'s default behavior. + + </para> + + <para> + + If you get a tool from somewhere (the &SCons; wiki or a third party, + for instance) and you'd like to use it in your project, the + <filename>site_scons</filename> dir is the simplest place to put it. + Tools come in two flavors; either a Python function that operates on + an &Environment; or a Python file containing two functions, exists() + and generate(). + + </para> + + <para> + + A single-function Tool can just be included in your + <filename>site_scons/site_init.py</filename> file where it will be + parsed and made available for use. For instance, you could have a + <filename>site_scons/site_init.py</filename> file like this: + + </para> + + <scons_example name="site1"> + <file name="site_scons/site_init.py" printme=1> + def TOOL_ADD_HEADER(env): + """A Tool to add a header from $HEADER to the source file""" + add_header = Builder(action=['echo "$HEADER" > $TARGET', + 'cat $SOURCE >> $TARGET']) + env.Append(BUILDERS = {'AddHeader' : add_header}) + env['HEADER'] = '' # set default value + </file> + <file name="SConstruct"> + env=Environment(tools=['default', TOOL_ADD_HEADER], HEADER="=====") + env.AddHeader('tgt', 'src') + </file> + <file name="src"> + hi there + </file> + </scons_example> + + <para> + + and a &SConstruct; like this: + + </para> + + <sconstruct> + # Use TOOL_ADD_HEADER from site_scons/site_init.py + env=Environment(tools=['default', TOOL_ADD_HEADER], HEADER="=====") + env.AddHeader('tgt', 'src') + </sconstruct> + + <para> + + The <function>TOOL_ADD_HEADER</function> tool method will be + called to add the <function>AddHeader</function> tool to the + environment. + + </para> + + <!-- + <scons_output example="site1" os="posix"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + --> + + <para> + Similarly, a more full-fledged tool with + <function>exists()</function> and <function>generate()</function> + methods can be installed in + <filename>site_scons/site_tools/toolname.py</filename>. Since + <filename>site_scons/site_tools</filename> is automatically added + to the head of the tool search path, any tool found there will be + available to all environments. Furthermore, a tool found there + will override a built-in tool of the same name, so if you need to + change the behavior of a built-in tool, site_scons gives you the + hook you need. + </para> + + <para> + Many people have a library of utility Python functions they'd like + to include in &SConscript;s; just put that module in + <filename>site_scons/my_utils.py</filename> or any valid Python module name of your + choice. For instance you can do something like this in + <filename>site_scons/my_utils.py</filename> to add a build_id method: + </para> + + <scons_example name="site2"> + <file name="site_scons/my_utils.py" printme=1> + def build_id(): + """Return a build ID (stub version)""" + return "100" + </file> + <file name="SConscript"> + import my_utils + print "build_id=" + my_utils.build_id() + </file> + </scons_example> + + <para> + + And then in your &SConscript; or any sub-&SConscript; anywhere in + your build, you can import <filename>my_utils</filename> and use it: + + </para> + + <sconstruct> + import my_utils + print "build_id=" + my_utils.build_id() + </sconstruct> + + <para> + + If you have a machine-wide site dir you'd like to use instead of + <filename>./site_scons</filename>, use the + <literal>--site-dir</literal> option to point to your dir. + <filename>site_init.py</filename> and + <filename>site_tools</filename> will be located under that dir. + To avoid using a <filename>site_scons</filename> dir at all, even + if it exists, use the <literal>--no-site-dir</literal> option. + + </para> + + </section> + + <!-- <section> diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml index 8ab4fca..df3affa 100644 --- a/doc/user/builders-writing.xml +++ b/doc/user/builders-writing.xml @@ -659,6 +659,129 @@ This functionality could be invoked as in the following example: </section> + <section> + <title>Where To Put Your Custom Builders and Tools</title> + + <para> + + The <filename>site_scons</filename> directory gives you a place to + put Python modules you can import into your SConscripts + (site_scons), add-on tools that can integrate into &SCons; + (site_scons/site_tools), and a site_scons/site_init.py file that + gets read before any &SConstruct; or &SConscript;, allowing you to + change &SCons;'s default behavior. + + </para> + + <para> + + If you get a tool from somewhere (the &SCons; wiki or a third party, + for instance) and you'd like to use it in your project, the + <filename>site_scons</filename> dir is the simplest place to put it. + Tools come in two flavors; either a Python function that operates on + an &Environment; or a Python file containing two functions, exists() + and generate(). + + </para> + + <para> + + A single-function Tool can just be included in your + <filename>site_scons/site_init.py</filename> file where it will be + parsed and made available for use. For instance, you could have a + <filename>site_scons/site_init.py</filename> file like this: + + </para> + + <programlisting> + def TOOL_ADD_HEADER(env): + """A Tool to add a header from $HEADER to the source file""" + add_header = Builder(action=['echo "$HEADER" > $TARGET', + 'cat $SOURCE >> $TARGET']) + env.Append(BUILDERS = {'AddHeader' : add_header}) + env['HEADER'] = '' # set default value + </programlisting> + + <para> + + and a &SConstruct; like this: + + </para> + + <programlisting> + # Use TOOL_ADD_HEADER from site_scons/site_init.py + env=Environment(tools=['default', TOOL_ADD_HEADER], HEADER="=====") + env.AddHeader('tgt', 'src') + </programlisting> + + <para> + + The <function>TOOL_ADD_HEADER</function> tool method will be + called to add the <function>AddHeader</function> tool to the + environment. + + </para> + + <!-- + <scons_output example="site1" os="posix"> + <scons_output_command>scons -Q</scons_output_command> + </scons_output> + --> + + <para> + Similarly, a more full-fledged tool with + <function>exists()</function> and <function>generate()</function> + methods can be installed in + <filename>site_scons/site_tools/toolname.py</filename>. Since + <filename>site_scons/site_tools</filename> is automatically added + to the head of the tool search path, any tool found there will be + available to all environments. Furthermore, a tool found there + will override a built-in tool of the same name, so if you need to + change the behavior of a built-in tool, site_scons gives you the + hook you need. + </para> + + <para> + Many people have a library of utility Python functions they'd like + to include in &SConscript;s; just put that module in + <filename>site_scons/my_utils.py</filename> or any valid Python module name of your + choice. For instance you can do something like this in + <filename>site_scons/my_utils.py</filename> to add a build_id method: + </para> + + <programlisting> + def build_id(): + """Return a build ID (stub version)""" + return "100" + </programlisting> + + <para> + + And then in your &SConscript; or any sub-&SConscript; anywhere in + your build, you can import <filename>my_utils</filename> and use it: + + </para> + + <programlisting> + import my_utils + print "build_id=" + my_utils.build_id() + </programlisting> + + <para> + + If you have a machine-wide site dir you'd like to use instead of + <filename>./site_scons</filename>, use the + <literal>--site-dir</literal> option to point to your dir. + <filename>site_init.py</filename> and + <filename>site_tools</filename> will be located under that dir. + To avoid using a <filename>site_scons</filename> dir at all, even + if it exists, use the <literal>--no-site-dir</literal> option. + + </para> + + </section> + + <!-- <section> diff --git a/doc/user/main.in b/doc/user/main.in index 8981b14..0dbadfc 100644 --- a/doc/user/main.in +++ b/doc/user/main.in @@ -135,16 +135,10 @@ XXX CheckTypeSize() - XXX Glob() - XXX Progress() XXX - - diskcheck= - XXX site_scons - XXX - - site-dir - XXX - - no-site-dir - XXX - - warn= XXX ARGLIST diff --git a/doc/user/main.xml b/doc/user/main.xml index 8981b14..0dbadfc 100644 --- a/doc/user/main.xml +++ b/doc/user/main.xml @@ -135,16 +135,10 @@ XXX CheckTypeSize() - XXX Glob() - XXX Progress() XXX - - diskcheck= - XXX site_scons - XXX - - site-dir - XXX - - no-site-dir - XXX - - warn= XXX ARGLIST |