summaryrefslogtreecommitdiff
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.in63
1 files changed, 40 insertions, 23 deletions
diff --git a/doc/user/builders-writing.in b/doc/user/builders-writing.in
index 0bf6971..addc837 100644
--- a/doc/user/builders-writing.in
+++ b/doc/user/builders-writing.in
@@ -1,6 +1,6 @@
<!--
- Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010 The SCons Foundation
+ Copyright (c) 2001, 2002, 2003, 2004, 2005, 2006, 2007, 2008, 2009, 2010, 2011 The SCons Foundation
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
@@ -823,7 +823,6 @@ This functionality could be invoked as in the following example:
<file name="my_command" chmod="0755">
cat
</file>
- </file>
</scons_example>
@@ -842,7 +841,6 @@ This functionality could be invoked as in the following example:
MY_EMITTER = modify2)
env1.Foo('file1')
env2.Foo('file2')
- </file>
</sconstruct>
<para>
@@ -899,8 +897,8 @@ 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 &SConscript; files
+ The <filename>site_scons</filename> directories give you a place to
+ put Python modules and packages that 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>),
@@ -912,11 +910,21 @@ This functionality could be invoked as in the following example:
<para>
+ Each system type (Windows, Mac, Linux, etc.) searches a canonical
+ set of directories for site_scons; see the man page for details.
+ The top-level SConstruct's site_scons dir is always searched last,
+ and its dir is placed first in the tool path so it overrides all
+ others.
+
+ </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
+ for instance) and you'd like to use it in your project, a
<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,
+ an &Environment; or a Python module or package containing two functions,
<function>exists()</function> and <function>generate()</function>.
</para>
@@ -931,7 +939,7 @@ This functionality could be invoked as in the following example:
</para>
<scons_example name="site1">
- <file name="site_scons/site_init.py" printme=1>
+ <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" &gt; $TARGET',
@@ -975,16 +983,23 @@ This functionality could be invoked as in the following example:
-->
<para>
- Similarly, a more full-fledged tool with
+ 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.
+ methods can be installed either as a module in the file
+ <filename>site_scons/site_tools/toolname.py</filename> or as a
+ package in the
+ directory <filename>site_scons/site_tools/toolname</filename>. In
+ the case of using a package, the <function>exists()</function>
+ and <function>generate()</function> are in the
+ file <filename>site_scons/site_tools/toolname/__init__.py</filename>.
+ (In all the above case <filename>toolname</filename> is replaced
+ by the name of the tool.)
+ 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, <filename>site_scons</filename> gives you the hook you need.
</para>
<para>
@@ -998,7 +1013,7 @@ This functionality could be invoked as in the following example:
</para>
<scons_example name="site2">
- <file name="site_scons/my_utils.py" printme=1>
+ <file name="site_scons/my_utils.py" printme="1">
from SCons.Script import * # for Execute and Mkdir
def build_id():
"""Return a build ID (stub version)"""
@@ -1047,13 +1062,15 @@ This functionality could be invoked as in the following example:
<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.
+ You can use any of the user- or machine-wide site dirs such as
+ <filename>~/.scons/site_scons</filename> instead of
+ <filename>./site_scons</filename>, or use the
+ <literal>--site-dir</literal> option to point to your own 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.
+ To avoid using a <filename>site_scons</filename> dir at all,
+ even if it exists, use the <literal>--no-site-dir</literal>
+ option.
</para>