From 4e1e98a120c8679d5492d308b7061a71dd47408d Mon Sep 17 00:00:00 2001 From: Gary Oberbrunner Date: Sun, 4 Jul 2010 17:23:01 +0000 Subject: Users Guide updates re: Tools as packages. Also updates UG xml files for my previous patch. Closes issue 2642. --- doc/user/builders-writing.in | 29 +++++++++++++--------- doc/user/builders-writing.xml | 57 ++++++++++++++++++++++++++++--------------- src/CHANGES.txt | 5 ++++ 3 files changed, 61 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: The site_scons 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 (site_scons), add-on tools that can integrate into &SCons; (site_scons/site_tools), @@ -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 site_scons 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, exists() and generate(). @@ -983,16 +983,23 @@ This functionality could be invoked as in the following example: --> - Similarly, a more full-fledged tool with + A more full-fledged tool with exists() and generate() - methods can be installed in - site_scons/site_tools/toolname.py. Since - site_scons/site_tools 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 + site_scons/site_tools/toolname.py or as a + package in the + directory site_scons/site_tools/toolname. In + the case of using a package, the exists() + and generate() are in the + file site_scons/site_tools/toolname/__init__.py. + (In all the above case toolname is replaced + by the name of the tool.) + Since site_scons/site_tools 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. 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: % scons -Q - 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') @@ -779,8 +779,8 @@ This functionality could be invoked as in the following example: - The site_scons directory gives you a place to - put Python modules you can import into your &SConscript; files + The site_scons directories give you a place to + put Python modules and packages that you can import into your &SConscript; files (site_scons), add-on tools that can integrate into &SCons; (site_scons/site_tools), @@ -792,11 +792,21 @@ This functionality could be invoked as in the following example: + 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. + + + + + 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 site_scons 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, exists() and generate(). @@ -846,16 +856,23 @@ This functionality could be invoked as in the following example: --> - Similarly, a more full-fledged tool with + A more full-fledged tool with exists() and generate() - methods can be installed in - site_scons/site_tools/toolname.py. Since - site_scons/site_tools 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 + site_scons/site_tools/toolname.py or as a + package in the + directory site_scons/site_tools/toolname. In + the case of using a package, the exists() + and generate() are in the + file site_scons/site_tools/toolname/__init__.py. + (In all the above case toolname is replaced + by the name of the tool.) + Since site_scons/site_tools 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. @@ -911,13 +928,15 @@ This functionality could be invoked as in the following example: - If you have a machine-wide site dir you'd like to use instead of - ./site_scons, use the - --site-dir option to point to your dir. + You can use any of the user- or machine-wide site dirs such as + ~/.scons/site_scons instead of + ./site_scons, or use the + --site-dir option to point to your own dir. site_init.py and site_tools will be located under that dir. - To avoid using a site_scons dir at all, even - if it exists, use the --no-site-dir option. + To avoid using a site_scons dir at all, + even if it exists, use the --no-site-dir + option. diff --git a/src/CHANGES.txt b/src/CHANGES.txt index 9435482..c63f206 100644 --- a/src/CHANGES.txt +++ b/src/CHANGES.txt @@ -7,6 +7,11 @@ RELEASE 2.1.0.alpha.yyyymmdd - NEW DATE WILL BE INSERTED HERE + From Russel Winder: + + - Users Guide updates explaining that Tools can be packages as + well as python modules. + From Gary Oberbrunner: - New systemwide and per-user site_scons dirs. -- cgit v0.12