diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/man/scons.1 | 58 | ||||
| -rw-r--r-- | doc/user/builders-writing.in | 26 |
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> |