summaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorGary Oberbrunner <garyo@oberbrunner.com>2010-07-04 00:14:53 (GMT)
committerGary Oberbrunner <garyo@oberbrunner.com>2010-07-04 00:14:53 (GMT)
commit13c61768b4ff739e2599b0de3f90a8efe15dd9fc (patch)
treebc12280e536e0d896be304026cd1e1e0e0bd2915 /doc
parent89eaa55eb76fdb8ea6368e0a720420f6bf8624f1 (diff)
downloadSCons-13c61768b4ff739e2599b0de3f90a8efe15dd9fc.zip
SCons-13c61768b4ff739e2599b0de3f90a8efe15dd9fc.tar.gz
SCons-13c61768b4ff739e2599b0de3f90a8efe15dd9fc.tar.bz2
Add all the per-system and per-user site_scons dirs, per discussion in SEP 002.
Diffstat (limited to 'doc')
-rw-r--r--doc/man/scons.158
-rw-r--r--doc/user/builders-writing.in26
2 files changed, 69 insertions, 15 deletions
diff --git a/doc/man/scons.1 b/doc/man/scons.1
index da6c918..4f3b1a3 100644
--- a/doc/man/scons.1
+++ b/doc/man/scons.1
@@ -100,17 +100,17 @@ file,
.B scons
looks for a directory named
.I site_scons
-in the directory containing the
+in various system directories (see below) and the directory containing the
.I SConstruct
-file; if it exists,
+file; for each of those dirs which exists,
.I site_scons
-is added to sys.path,
+is prepended to sys.path,
the file
.IR site_scons/site_init.py ,
is evaluated if it exists,
and the directory
.I site_scons/site_tools
-is added to the default toolpath if it exist.
+is prepended to the default toolpath if it exists.
See the
.I --no-site-dir
and
@@ -1095,13 +1095,13 @@ any out-of-date target files, but do not execute the commands.
.RI --no-site-dir
Prevents the automatic addition of the standard
.I site_scons
-dir to
+dirs to
.IR sys.path .
Also prevents loading the
.I site_scons/site_init.py
-module if it exists, and prevents adding
+modules if they exist, and prevents adding their
.I site_scons/site_tools
-to the toolpath.
+dirs to the toolpath.
.\" .TP
.\" .RI -o " file" ", --old-file=" file ", --assume-old=" file
@@ -1182,7 +1182,7 @@ Ignored for compatibility with GNU
.RI --site-dir= dir
Uses the named dir as the site dir rather than the default
.I site_scons
-dir. This dir will get prepended to
+dirs. This dir will get prepended to
.IR sys.path ,
the module
.IR dir /site_init.py
@@ -1190,6 +1190,48 @@ will get loaded if it exists, and
.IR dir /site_tools
will get added to the default toolpath.
+The default set of
+.I site_scons
+dirs used when
+.I --site-dir
+is not specified depends on the system platform, as follows. Note
+that the directories are examined in the order given, from most
+generic to most specific, so the last-executed site_init.py file is
+the most specific one (which gives it the chance to override
+everything else), and the dirs are prepended to the paths, again so
+the last dir examined comes first in the resulting path.
+
+.IP "Windows:"
+.nf
+ %ALLUSERSPROFILE/Application Data/scons/site_scons
+ %USERPROFILE%/Local Settings/Application Data/scons/site_scons
+ %APPDATA%/scons/site_scons
+ %HOME%/.scons/site_scons
+ ./site_scons
+.fi
+.IP "Mac OS X:"
+.nf
+ /Library/Application Support/SCons/site_scons
+ /opt/local/share/scons/site_scons (for MacPorts)
+ /sw/share/scons/site_scons (for Fink)
+ $HOME/Library/Application Support/SCons/site_scons
+ $HOME/.scons/site_scons
+ ./site_scons
+.fi
+.IP "Solaris:"
+.nf
+ /opt/sfw/scons/site_scons
+ /usr/share/scons/site_scons
+ $HOME/.scons/site_scons
+ ./site_scons
+.fi
+.IP "Linux, HPUX, and other Posix-like systems:"
+.nf
+ /usr/share/scons/site_scons
+ $HOME/.scons/site_scons
+ ./site_scons
+.fi
+
.TP
.RI --stack-size= KILOBYTES
Set the size stack used to run threads to
diff --git a/doc/user/builders-writing.in b/doc/user/builders-writing.in
index 1da45a5..59c1117 100644
--- a/doc/user/builders-writing.in
+++ b/doc/user/builders-writing.in
@@ -897,7 +897,7 @@ This functionality could be invoked as in the following example:
<para>
- The <filename>site_scons</filename> directory gives you a place to
+ The <filename>site_scons</filename> directories give you a place to
put Python modules you can import into your &SConscript; files
(<filename>site_scons</filename>),
add-on tools that can integrate into &SCons;
@@ -910,8 +910,18 @@ 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,
@@ -1045,13 +1055,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>