diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/user/builders-writing.in | 29 | ||||
| -rw-r--r-- | doc/user/builders-writing.xml | 57 |
2 files changed, 56 insertions, 30 deletions
diff --git a/doc/user/builders-writing.in b/doc/user/builders-writing.in index 59c1117..93a183c 100644 --- a/doc/user/builders-writing.in +++ b/doc/user/builders-writing.in @@ -898,7 +898,7 @@ This functionality could be invoked as in the following example: <para> The <filename>site_scons</filename> directories give you a place to - put Python modules you can import into your &SConscript; files + 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>), @@ -924,7 +924,7 @@ This functionality could be invoked as in the following example: 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> @@ -983,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> diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml index 21aa656..c8ff003 100644 --- a/doc/user/builders-writing.xml +++ b/doc/user/builders-writing.xml @@ -233,7 +233,7 @@ This functionality could be invoked as in the following example: <screen> % <userinput>scons -Q</userinput> - AttributeError: SConsEnvironment instance has no attribute 'Program': + AttributeError: 'SConsEnvironment' object has no attribute 'Program': File "/home/my/project/SConstruct", line 4: env.Program('hello.c') </screen> @@ -779,8 +779,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>), @@ -792,11 +792,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> @@ -846,16 +856,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> @@ -911,13 +928,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> |