diff options
Diffstat (limited to 'doc/user/builders-writing.xml')
| -rw-r--r-- | doc/user/builders-writing.xml | 59 |
1 files changed, 38 insertions, 21 deletions
diff --git a/doc/user/builders-writing.xml b/doc/user/builders-writing.xml index f364e27..d9bda79 100644 --- a/doc/user/builders-writing.xml +++ b/doc/user/builders-writing.xml @@ -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 @@ -703,7 +703,6 @@ This functionality could be invoked as in the following example: import os env1['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd() env2['ENV']['PATH'] = env2['ENV']['PATH'] + os.pathsep + os.getcwd() - </programlisting> @@ -722,7 +721,6 @@ This functionality could be invoked as in the following example: MY_EMITTER = modify2) env1.Foo('file1') env2.Foo('file2') - </programlisting> <para> @@ -781,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>), @@ -794,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> @@ -848,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> @@ -913,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> |