From ba4425ab5227fd9597fccd368bffff6bf1032149 Mon Sep 17 00:00:00 2001
From: Luca Falavigna <dktrkranz@debian.org>
Date: Sat, 10 Sep 2011 11:25:53 +0200
Subject: Imported Upstream version 2.1.0

---
 doc/user/builders-writing.xml | 59 ++++++++++++++++++++++++++++---------------
 1 file changed, 38 insertions(+), 21 deletions(-)

(limited to 'doc/user/builders-writing.xml')

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>
 
-- 
cgit v1.2.3