summaryrefslogtreecommitdiffstats
path: root/doc/user
diff options
context:
space:
mode:
authorSteven Knight <knight@baldmt.com>2010-01-11 16:47:36 (GMT)
committerSteven Knight <knight@baldmt.com>2010-01-11 16:47:36 (GMT)
commita62d7407d4db87ca70a74b659cd947fedbd84d16 (patch)
tree53f7150e9dcb92ab6060c845417212a9b267ac7c /doc/user
parentebf6882d790093652da274d22c17d849a1236d4b (diff)
downloadSCons-a62d7407d4db87ca70a74b659cd947fedbd84d16.zip
SCons-a62d7407d4db87ca70a74b659cd947fedbd84d16.tar.gz
SCons-a62d7407d4db87ca70a74b659cd947fedbd84d16.tar.bz2
Propagate doc about site_scons to builders-writing.xml. Typographic edits.
Diffstat (limited to 'doc/user')
-rw-r--r--doc/user/builders-writing.in20
-rw-r--r--doc/user/builders-writing.xml260
2 files changed, 161 insertions, 119 deletions
diff --git a/doc/user/builders-writing.in b/doc/user/builders-writing.in
index 19c91de..2c5cce2 100644
--- a/doc/user/builders-writing.in
+++ b/doc/user/builders-writing.in
@@ -900,11 +900,13 @@ This functionality could be invoked as in the following example:
<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.
+ put Python modules you can import into your &SConscript; files
+ (<filename>site_scons</filename>),
+ add-on tools that can integrate into &SCons;
+ (<filename>site_scons/site_tools</filename>),
+ and a <filename>site_scons/site_init.py</filename> file that
+ gets read before any &SConstruct; or &SConscript; file,
+ allowing you to change &SCons;'s default behavior.
</para>
@@ -914,8 +916,8 @@ This functionality could be invoked as in the following example:
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().
+ an &Environment; or a Python file containing two functions,
+ <function>exists()</function> and <function>generate()</function>.
</para>
@@ -990,7 +992,9 @@ This functionality could be invoked as in the following example:
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 build_id and MakeWorkDir functions:
+ <filename>site_scons/my_utils.py</filename> to add
+ <function>build_id</function> and <function>MakeWorkDir</function>
+ functions:
</para>
<scons_example name="site2">
diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml
index 265357d..3932181 100644
--- a/doc/user/builders-writing.xml
+++ b/doc/user/builders-writing.xml
@@ -742,148 +742,186 @@ This functionality could be invoked as in the following example:
</section>
+ <!--
+
+ <section>
+ <title>target_factor=, source_factory=</title>
+
+ </section>
+
+ <section>
+ <title>target_scanner=, source_scanner=</title>
+
+ </section>
+
+ <section>
+ <title>multi=</title>
+
+ </section>
+
+ <section>
+ <title>single_source=</title>
+
+ </section>
+
+ <section>
+ <title>src_builder=</title>
+
+ </section>
+
+ <section>
+ <title>ensure_suffix=</title>
+
+ </section>
+
+ -->
+
<section>
<title>Where To Put Your Custom Builders and Tools</title>
- <para>
+ <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.
+ The <filename>site_scons</filename> directory gives you a place to
+ put Python modules you can import into your &SConscript; files
+ (<filename>site_scons</filename>),
+ add-on tools that can integrate into &SCons;
+ (<filename>site_scons/site_tools</filename>),
+ and a <filename>site_scons/site_init.py</filename> file that
+ gets read before any &SConstruct; or &SConscript; file,
+ allowing you to change &SCons;'s default behavior.
- </para>
+ </para>
- <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().
+ 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,
+ <function>exists()</function> and <function>generate()</function>.
- </para>
+ </para>
- <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:
+ 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>
+ </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" &gt; $TARGET',
- 'cat $SOURCE &gt;&gt; $TARGET'])
- env.Append(BUILDERS = {'AddHeader' : add_header})
- env['HEADER'] = '' # set default value
- </programlisting>
+ <programlisting>
+ def TOOL_ADD_HEADER(env):
+ """A Tool to add a header from $HEADER to the source file"""
+ add_header = Builder(action=['echo "$HEADER" &gt; $TARGET',
+ 'cat $SOURCE &gt;&gt; $TARGET'])
+ env.Append(BUILDERS = {'AddHeader' : add_header})
+ env['HEADER'] = '' # set default value
+ </programlisting>
- <para>
+ <para>
- and a &SConstruct; like this:
+ and a &SConstruct; like this:
- </para>
+ </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>
+ <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>
+ <para>
- The <function>TOOL_ADD_HEADER</function> tool method will be
- called to add the <function>AddHeader</function> tool to the
- environment.
+ The <function>TOOL_ADD_HEADER</function> tool method will be
+ called to add the <function>AddHeader</function> tool to the
+ environment.
- </para>
+ </para>
- <!--
- <scons_output example="site1" os="posix">
- <scons_output_command>scons -Q</scons_output_command>
- </scons_output>
- -->
+ <!--
+ <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>
+ 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 build_id and MakeWorkDir functions:
- </para>
-
- <programlisting>
- from SCons.Script import * # for Execute and Mkdir
- def build_id():
- """Return a build ID (stub version)"""
- return "100"
- def MakeWorkDir(workdir):
- """Create the specified dir immediately"""
- Execute(Mkdir(workdir))
- </programlisting>
+ <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
+ <function>build_id</function> and <function>MakeWorkDir</function>
+ functions:
+ </para>
+
+ <programlisting>
+ from SCons.Script import * # for Execute and Mkdir
+ def build_id():
+ """Return a build ID (stub version)"""
+ return "100"
+ def MakeWorkDir(workdir):
+ """Create the specified dir immediately"""
+ Execute(Mkdir(workdir))
+ </programlisting>
- <para>
+ <para>
- And then in your &SConscript; or any sub-&SConscript; anywhere in
- your build, you can import <filename>my_utils</filename> and use it:
+ And then in your &SConscript; or any sub-&SConscript; anywhere in
+ your build, you can import <filename>my_utils</filename> and use it:
- </para>
+ </para>
- <programlisting>
- import my_utils
- print "build_id=" + my_utils.build_id()
- my_utils.MakeWorkDir('/tmp/work')
- </programlisting>
+ <programlisting>
+ import my_utils
+ print "build_id=" + my_utils.build_id()
+ my_utils.MakeWorkDir('/tmp/work')
+ </programlisting>
- <para>
- Note that although you can put this library in
- <filename>site_scons/site_init.py</filename>,
- it is no better there than <filename>site_scons/my_utils.py</filename>
- since you still have to import that module into your &SConscript;.
- Also note that in order to refer to objects in the SCons namespace
- such as &Environment; or &Mkdir; or &Execute; in any file other
- than a &SConstruct; or &SConscript; you always need to do
- </para>
- <programlisting>
- from SCons.Script import *
- </programlisting>
+ <para>
+ Note that although you can put this library in
+ <filename>site_scons/site_init.py</filename>,
+ it is no better there than <filename>site_scons/my_utils.py</filename>
+ since you still have to import that module into your &SConscript;.
+ Also note that in order to refer to objects in the SCons namespace
+ such as &Environment; or &Mkdir; or &Execute; in any file other
+ than a &SConstruct; or &SConscript; you always need to do
+ </para>
+ <programlisting>
+ from SCons.Script import *
+ </programlisting>
- <para>
- This is true in modules in <filename>site_scons</filename> such as
- <filename>site_scons/site_init.py</filename> as well.
- </para>
+ <para>
+ This is true in modules in <filename>site_scons</filename> such as
+ <filename>site_scons/site_init.py</filename> as well.
+ </para>
- <para>
+ <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.
+ 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>
+ </para>
</section>