diff options
Diffstat (limited to 'doc/user/builders-writing.in')
| -rw-r--r-- | doc/user/builders-writing.in | 63 |
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" > $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> |