diff options
author | Dirk Baechle <dl9obn@darc.de> | 2013-05-03 22:16:40 (GMT) |
---|---|---|
committer | Dirk Baechle <dl9obn@darc.de> | 2013-05-03 22:16:40 (GMT) |
commit | 5b4de675705f2cb7aea430e557b9c66475483522 (patch) | |
tree | 4b9a58463186fe081f15b8461868c00e36d5dbe5 /doc | |
parent | fc4b1a8ecb473afe0a01fee3c444d7952aac59e0 (diff) | |
download | SCons-5b4de675705f2cb7aea430e557b9c66475483522.zip SCons-5b4de675705f2cb7aea430e557b9c66475483522.tar.gz SCons-5b4de675705f2cb7aea430e557b9c66475483522.tar.bz2 |
- added Docbook Tool to the sources
- added SConstruct for the MAN pages
Diffstat (limited to 'doc')
-rw-r--r-- | doc/man/SConstruct | 44 | ||||
-rw-r--r-- | doc/man/html.xsl | 55 | ||||
-rw-r--r-- | doc/man/scons-time.xml | 404 | ||||
-rw-r--r-- | doc/man/scons.css | 263 | ||||
-rw-r--r-- | doc/man/scons.xml | 1894 | ||||
-rw-r--r-- | doc/man/sconsign.xml | 32 |
6 files changed, 1502 insertions, 1190 deletions
diff --git a/doc/man/SConstruct b/doc/man/SConstruct new file mode 100644 index 0000000..69ba449 --- /dev/null +++ b/doc/man/SConstruct @@ -0,0 +1,44 @@ +# +# SConstruct file for building SCons documentation. +# + +# +# __COPYRIGHT__ +# +# Permission is hereby granted, free of charge, to any person obtaining +# a copy of this software and associated documentation files (the +# "Software"), to deal in the Software without restriction, including +# without limitation the rights to use, copy, modify, merge, publish, +# distribute, sublicense, and/or sell copies of the Software, and to +# permit persons to whom the Software is furnished to do so, subject to +# the following conditions: +# +# The above copyright notice and this permission notice shall be included +# in all copies or substantial portions of the Software. +# +# THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY +# KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE +# WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND +# NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE +# LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION +# OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION +# WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +env = Environment(tools=['docbook'], + toolpath=['../../src/engine/SCons/Tool'], + DOCBOOK_DEFAULT_XSL_HTML='html.xsl') + +# Helper function, combining all the steps for a single target +def createManPages(env, target): + env.DocbookXInclude('%s_xi.xml' % target, '%s.xml' % target) + env.DocbookXslt('%s_db.xml' % target, '%s_xi.xml' % target, + xsl='../xslt/to_docbook.xslt') + env.DocbookHtml('%s.html' % target,'%s_db.xml' % target) + env.DocbookMan('%s.1' % target, '%s_db.xml' % target) + +# +# Create MAN pages +# +createManPages(env, "scons") +createManPages(env, "sconsign") +createManPages(env, "scons-time") diff --git a/doc/man/html.xsl b/doc/man/html.xsl new file mode 100644 index 0000000..74ea529 --- /dev/null +++ b/doc/man/html.xsl @@ -0,0 +1,55 @@ +<?xml version='1.0'?>
+<!--
+
+ __COPYRIGHT__
+
+ Permission is hereby granted, free of charge, to any person obtaining
+ a copy of this software and associated documentation files (the
+ "Software"), to deal in the Software without restriction, including
+ without limitation the rights to use, copy, modify, merge, publish,
+ distribute, sublicense, and/or sell copies of the Software, and to
+ permit persons to whom the Software is furnished to do so, subject to
+ the following conditions:
+
+ The above copyright notice and this permission notice shall be included
+ in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY
+ KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE
+ WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+ NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+ LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+ OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+ WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+-->
+<xsl:stylesheet
+ xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
+ xmlns:fo="http://www.w3.org/1999/XSL/Format"
+ version="1.0">
+
+ <xsl:import href="../../src/engine/SCons/Tool/docbook/docbook-xsl-1.76.1/html/docbook.xsl"/>
+
+<xsl:param name="l10n.gentext.default.language" select="'en'"/>
+<xsl:param name="section.autolabel" select="1"/>
+<xsl:param name="html.stylesheet" select="'scons.css'"/>
+<xsl:param name="generate.toc">
+/appendix toc,title
+article/appendix nop
+/article toc,title
+book toc,title,figure,table,example,equation
+/chapter toc,title
+part toc,title
+/preface toc,title
+reference toc,title
+/sect1 toc
+/sect2 toc
+/sect3 toc
+/sect4 toc
+/sect5 toc
+/section toc
+set toc,title
+</xsl:param>
+
+</xsl:stylesheet>
+
diff --git a/doc/man/scons-time.xml b/doc/man/scons-time.xml index 6227e25..ca7545e 100644 --- a/doc/man/scons-time.xml +++ b/doc/man/scons-time.xml @@ -54,79 +54,79 @@ <!-- body begins here --> <refsect1 id='generating_timing_information'><title>Generating Timing Information</title> -<para><emphasis remap='B'>scons-time run</emphasis> +<para><emphasis role="bold">scons-time run</emphasis> [<option>-hnqv</option>] [<option>--aegis=</option><replaceable>PROJECT</replaceable>] -[<option>-f </option><emphasis remap='I'>FILE</emphasis>] +[<option>-f </option><emphasis>FILE</emphasis>] [<option>--number=</option><replaceable>NUMBER</replaceable>] [<option>--outdir=</option><replaceable>OUTDIR</replaceable>] -[<option>-p </option><emphasis remap='I'>STRING</emphasis>] +[<option>-p </option><emphasis>STRING</emphasis>] [<option>--python=</option><replaceable>PYTHON</replaceable>] -[<option>-s </option><emphasis remap='I'>DIR</emphasis>] +[<option>-s </option><emphasis>DIR</emphasis>] [<option>--scons=</option><replaceable>SCONS</replaceable>] [<option>--svn=</option><replaceable>URL</replaceable>] -[<emphasis remap='I'>ARGUMENTS</emphasis>]</para> +[<emphasis>ARGUMENTS</emphasis>]</para> <!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> <refsect2 id='extracting_function_timings'><title>Extracting Function Timings</title> -<para><emphasis remap='B'>scons-time func</emphasis> +<para><emphasis role="bold">scons-time func</emphasis> [<option>-h</option>] [<option>--chdir=</option><replaceable>DIR</replaceable>] -[<option>-f </option><emphasis remap='I'>FILE</emphasis>] +[<option>-f </option><emphasis>FILE</emphasis>] [<option>--fmt=</option><replaceable>FORMAT</replaceable>] [<option>--func=</option><replaceable>NAME</replaceable>] -[<option>-p </option><emphasis remap='I'>STRING</emphasis>] -[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>] +[<option>-p </option><emphasis>STRING</emphasis>] +[<option>-t </option><emphasis>NUMBER</emphasis>] [<option>--title= TITLE</option>] -[<emphasis remap='I'>ARGUMENTS</emphasis>]</para> +[<emphasis>ARGUMENTS</emphasis>]</para> <!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> </refsect2> <refsect2 id='extracting_memory_statistics'><title>Extracting Memory Statistics</title> -<para><emphasis remap='B'>scons-time mem</emphasis> +<para><emphasis role="bold">scons-time mem</emphasis> [<option>-h</option>] [<option>--chdir=</option><replaceable>DIR</replaceable>] -[<option>-f </option><emphasis remap='I'>FILE</emphasis>] +[<option>-f </option><emphasis>FILE</emphasis>] [<option>--fmt=</option><replaceable>FORMAT</replaceable>] -[<option>-p </option><emphasis remap='I'>STRING</emphasis>] +[<option>-p </option><emphasis>STRING</emphasis>] [<option>--stage=</option><replaceable>STAGE</replaceable>] -[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>] +[<option>-t </option><emphasis>NUMBER</emphasis>] [<option>--title=</option><replaceable>TITLE</replaceable>] -[<emphasis remap='I'>ARGUMENTS</emphasis>]</para> +[<emphasis>ARGUMENTS</emphasis>]</para> <!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> </refsect2> <refsect2 id='extracting_object_counts'><title>Extracting Object Counts</title> -<para><emphasis remap='B'>scons-time obj</emphasis> +<para><emphasis role="bold">scons-time obj</emphasis> [<option>-h</option>] [<option>--chdir=</option><replaceable>DIR</replaceable>] -[<option>-f </option><emphasis remap='I'>FILE</emphasis>] +[<option>-f </option><emphasis>FILE</emphasis>] [<option>--fmt=</option><replaceable>FORMAT</replaceable>] -[<option>-p </option><emphasis remap='I'>STRING</emphasis>] +[<option>-p </option><emphasis>STRING</emphasis>] [<option>--stage=</option><replaceable>STAGE</replaceable>] -[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>] +[<option>-t </option><emphasis>NUMBER</emphasis>] [<option>--title=</option><replaceable>TITLE</replaceable>] -[<emphasis remap='I'>ARGUMENTS</emphasis>]</para> +[<emphasis>ARGUMENTS</emphasis>]</para> <!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> </refsect2> <refsect2 id='extracting_execution_times'><title>Extracting Execution Times</title> -<para><emphasis remap='B'>scons-time time</emphasis> +<para><emphasis role="bold">scons-time time</emphasis> [<option>-h</option>] [<option>--chdir=</option><replaceable>DIR</replaceable>] -[<option>-f </option><emphasis remap='I'>FILE</emphasis>] +[<option>-f </option><emphasis>FILE</emphasis>] [<option>--fmt=</option><replaceable>FORMAT</replaceable>] -[<option>-p </option><emphasis remap='I'>STRING</emphasis>] -[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>] +[<option>-p </option><emphasis>STRING</emphasis>] +[<option>-t </option><emphasis>NUMBER</emphasis>] [<option>--title=</option><replaceable>TITLE</replaceable>] [<option>--which=</option><replaceable>WHICH</replaceable>] -[<emphasis remap='I'>ARGUMENTS</emphasis>]</para> +[<emphasis>ARGUMENTS</emphasis>]</para> <!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> </refsect2> <refsect2 id='help_text'><title>Help Text</title> -<para><emphasis remap='B'>scons-time help</emphasis> -<emphasis remap='I'>SUBCOMMAND</emphasis> +<para><emphasis role="bold">scons-time help</emphasis> +<emphasis>SUBCOMMAND</emphasis> [...]</para> <!-- '\"========================================================================== --> </refsect2> @@ -151,7 +151,7 @@ of specific subcommands.</para> <para>The basic way to use <command>scons-time</command> is to run the -<emphasis remap='B'>scons-time run</emphasis> +<emphasis role="bold">scons-time run</emphasis> subcommand (possibly multiple times) to generate profile and log file output, @@ -161,19 +161,19 @@ captured in the profiles and log files for a particular kind of information: function timings (the -<emphasis remap='B'>scons-time func</emphasis> +<emphasis role="bold">scons-time func</emphasis> subcommand), total memory used (the -<emphasis remap='B'>scons-time mem</emphasis> +<emphasis role="bold">scons-time mem</emphasis> subcommand), object counts (the -<emphasis remap='B'>scons-time obj</emphasis> +<emphasis role="bold">scons-time obj</emphasis> subcommand) and overall execution time (the -<emphasis remap='B'>scons-time time</emphasis> +<emphasis role="bold">scons-time time</emphasis> subcommand). Options exist to place and find the profiles and log files in separate directories, @@ -184,7 +184,7 @@ program, and so on.</para> <para>There are two basic ways the -<emphasis remap='B'>scons-time run</emphasis> +<emphasis role="bold">scons-time run</emphasis> subcommand is intended to be used to gather timing statistics @@ -208,26 +208,26 @@ to look at the performance impact of changes you're making in the local tree. In this mode, you run the -<emphasis remap='B'>scons-time run</emphasis> +<emphasis role="bold">scons-time run</emphasis> subcommand -<emphasis remap='I'>without</emphasis> +<emphasis>without</emphasis> the <option>--svn=</option> option, in which case it simply looks in the profile/log file output directory (the current directory by default) and automatically figures out the -<emphasis remap='I'>next</emphasis> +<emphasis>next</emphasis> run number for the output profile and log file. Used in this way, the development cycle goes something like: make a change to SCons; run -<emphasis remap='B'>scons-time run</emphasis> +<emphasis role="bold">scons-time run</emphasis> to profile it against a specific configuration; make another change to SCons; run -<emphasis remap='B'>scons-time run</emphasis> +<emphasis role="bold">scons-time run</emphasis> again to profile it; etc.</para> <!-- '\"========================================================================== --> @@ -237,13 +237,13 @@ etc.</para> <para>The <command>scons-time</command> command only supports a few global options:</para> -<variablelist remap='TP'> +<variablelist> <varlistentry> <term>-h, --help</term> <listitem> <para>Displays the global help text and exits, identical to the -<emphasis remap='B'>scons-time help</emphasis> +<emphasis role="bold">scons-time help</emphasis> subcommand.</para> </listitem> </varlistentry> @@ -272,36 +272,36 @@ individual subcommands.</para> <!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> <refsect2 id='the_func_subcommand'><title>The func Subcommand</title> -<para><emphasis remap='B'>scons-time func</emphasis> +<para><emphasis role="bold">scons-time func</emphasis> [<option>-h</option>] [<option>--chdir=</option><replaceable>DIR</replaceable>] -[<option>-f </option><emphasis remap='I'>FILE</emphasis>] +[<option>-f </option><emphasis>FILE</emphasis>] [<option>--fmt=</option><replaceable>FORMAT</replaceable>] [<option>--func=</option><replaceable>NAME</replaceable>] -[<option>-p </option><emphasis remap='I'>STRING</emphasis>] -[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>] +[<option>-p </option><emphasis>STRING</emphasis>] +[<option>-t </option><emphasis>NUMBER</emphasis>] [<option>--title= TITLE</option>] -[<emphasis remap='I'>ARGUMENTS</emphasis>]</para> +[<emphasis>ARGUMENTS</emphasis>]</para> <para>The -<emphasis remap='B'>scons-time func</emphasis> +<emphasis role="bold">scons-time func</emphasis> subcommand displays timing information for a specific Python function within SCons. By default, it extracts information about the -<emphasis remap='B'>_main</emphasis>() +<emphasis role="bold">_main</emphasis>() function, which includes the Python profiler timing for all of SCons.</para> <para>The -<emphasis remap='B'>scons-time func</emphasis> +<emphasis role="bold">scons-time func</emphasis> subcommand extracts function timing information from all the specified file arguments, which should be Python profiler output files. (Normally, these would be -<emphasis remap='B'>*.prof</emphasis> +<emphasis role="bold">*.prof</emphasis> files generated by the -<emphasis remap='B'>scons-time run</emphasis> +<emphasis role="bold">scons-time run</emphasis> subcommand, but they can actually be generated by any Python profiler invocation.) @@ -311,7 +311,7 @@ globbed for on-disk files.</para> <para>If no arguments are specified, then function timing information will be extracted from all -<emphasis remap='B'>*.prof</emphasis> +<emphasis role="bold">*.prof</emphasis> files, or the subset of them with a prefix specified by the @@ -319,12 +319,12 @@ with a prefix specified by the option.</para> <para>Options include:</para> -<variablelist remap='TP'> +<variablelist> <varlistentry> <term>-C DIRECTORY, --chdir=DIRECTORY</term> <listitem> <para>Changes to the specified -<emphasis remap='I'>DIRECTORY</emphasis> +<emphasis>DIRECTORY</emphasis> before looking for the specified files (or files that match the specified patterns).</para> </listitem> @@ -333,28 +333,28 @@ before looking for the specified files <term>-f FILE, --file=FILE</term> <listitem> <para>Reads configuration information from the specified -<emphasis remap='I'>FILE</emphasis>.</para> +<emphasis>FILE</emphasis>.</para> </listitem> </varlistentry> <varlistentry> <term>-fmt=FORMAT, --format=FORMAT</term> <listitem> <para>Reports the output in the specified -<emphasis remap='I'>FORMAT</emphasis>. +<emphasis>FORMAT</emphasis>. The formats currently supported are -<emphasis remap='B'>ascii</emphasis> +<emphasis role="bold">ascii</emphasis> (the default) and -<emphasis remap='B'>gnuplot</emphasis>.</para> +<emphasis role="bold">gnuplot</emphasis>.</para> </listitem> </varlistentry> <varlistentry> <term>--func=NAME</term> <listitem> <para>Extracts timings for the specified function -<emphasis remap='I'>NAME</emphasis>. +<emphasis>NAME</emphasis>. The default is to report cumulative timings for the -<emphasis remap='B'>_main</emphasis>() +<emphasis role="bold">_main</emphasis>() function, which contains the entire SCons run.</para> </listitem> @@ -363,7 +363,7 @@ which contains the entire SCons run.</para> <term>-h, --help</term> <listitem> <para>Displays help text for the -<emphasis remap='B'>scons-time func</emphasis> +<emphasis role="bold">scons-time func</emphasis> subcommand.</para> </listitem> </varlistentry> @@ -380,7 +380,7 @@ if no arguments are specified on the command line.</para> <term>-t NUMBER, --tail=NUMBER</term> <listitem> <para>Only extracts function timings from the last -<emphasis remap='I'>NUMBER</emphasis> +<emphasis>NUMBER</emphasis> files.</para> <!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> </listitem> @@ -389,34 +389,34 @@ files.</para> </refsect2> <refsect2 id='the_help_subcommand'><title>The help Subcommand</title> -<para><emphasis remap='B'>scons-time help</emphasis> -<emphasis remap='I'>SUBCOMMAND</emphasis> +<para><emphasis role="bold">scons-time help</emphasis> +<emphasis>SUBCOMMAND</emphasis> [...] The -<emphasis remap='B'>help</emphasis> +<emphasis role="bold">help</emphasis> subcommand prints help text for any other subcommands listed as later arguments on the command line.</para> <!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> </refsect2> <refsect2 id='the_mem_subcommand'><title>The mem Subcommand</title> -<para><emphasis remap='B'>scons-time mem</emphasis> +<para><emphasis role="bold">scons-time mem</emphasis> [<option>-h</option>] [<option>--chdir=</option><replaceable>DIR</replaceable>] -[<option>-f </option><emphasis remap='I'>FILE</emphasis>] +[<option>-f </option><emphasis>FILE</emphasis>] [<option>--fmt=</option><replaceable>FORMAT</replaceable>] -[<option>-p </option><emphasis remap='I'>STRING</emphasis>] +[<option>-p </option><emphasis>STRING</emphasis>] [<option>--stage=</option><replaceable>STAGE</replaceable>] -[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>] +[<option>-t </option><emphasis>NUMBER</emphasis>] [<option>--title=</option><replaceable>TITLE</replaceable>] -[<emphasis remap='I'>ARGUMENTS</emphasis>]</para> +[<emphasis>ARGUMENTS</emphasis>]</para> <para>The -<emphasis remap='B'>scons-time mem</emphasis> +<emphasis role="bold">scons-time mem</emphasis> subcommand displays how much memory SCons uses.</para> <para>The -<emphasis remap='B'>scons-time mem</emphasis> +<emphasis role="bold">scons-time mem</emphasis> subcommand extracts memory use information from all the specified file arguments, which should be files containing output from @@ -424,9 +424,9 @@ running SCons with the <option>--debug=memory</option> option. (Normally, these would be -<emphasis remap='B'>*.log</emphasis> +<emphasis role="bold">*.log</emphasis> files generated by the -<emphasis remap='B'>scons-time run</emphasis> +<emphasis role="bold">scons-time run</emphasis> subcommand.) All file name arguments will be globbed for on-disk files.</para> @@ -434,19 +434,19 @@ globbed for on-disk files.</para> <para>If no arguments are specified, then memory information will be extracted from all -<emphasis remap='B'>*.log</emphasis> +<emphasis role="bold">*.log</emphasis> files, or the subset of them with a prefix specified by the <option>-p</option> option.</para> -<variablelist remap='TP'> +<variablelist> <varlistentry> <term>-C DIR, --chdir=DIR</term> <listitem> <para>Changes to the specified -<emphasis remap='I'>DIRECTORY</emphasis> +<emphasis>DIRECTORY</emphasis> before looking for the specified files (or files that match the specified patterns).</para> </listitem> @@ -455,26 +455,26 @@ before looking for the specified files <term>-f FILE, --file=FILE</term> <listitem> <para>Reads configuration information from the specified -<emphasis remap='I'>FILE</emphasis>.</para> +<emphasis>FILE</emphasis>.</para> </listitem> </varlistentry> <varlistentry> <term>-fmt=FORMAT, --format=FORMAT</term> <listitem> <para>Reports the output in the specified -<emphasis remap='I'>FORMAT</emphasis>. +<emphasis>FORMAT</emphasis>. The formats currently supported are -<emphasis remap='B'>ascii</emphasis> +<emphasis role="bold">ascii</emphasis> (the default) and -<emphasis remap='B'>gnuplot</emphasis>.</para> +<emphasis role="bold">gnuplot</emphasis>.</para> </listitem> </varlistentry> <varlistentry> <term>-h, --help</term> <listitem> <para>Displays help text for the -<emphasis remap='B'>scons-time mem</emphasis> +<emphasis role="bold">scons-time mem</emphasis> subcommand.</para> </listitem> </varlistentry> @@ -491,21 +491,21 @@ if no arguments are specified on the command line.</para> <term>--stage=STAGE</term> <listitem> <para>Prints the memory used at the end of the specified -<emphasis remap='I'>STAGE</emphasis>: -<emphasis remap='B'>pre-read</emphasis> +<emphasis>STAGE</emphasis>: +<emphasis role="bold">pre-read</emphasis> (before the SConscript files are read), -<emphasis remap='B'>post-read ,</emphasis> +<emphasis role="bold">post-read ,</emphasis> (after the SConscript files are read), -<emphasis remap='B'>pre-build</emphasis> +<emphasis role="bold">pre-build</emphasis> (before any targets are built) or -<emphasis remap='B'>post-build</emphasis> +<emphasis role="bold">post-build</emphasis> (after any targets are built). If no <option>--stage</option> option is specified, the default behavior is -<emphasis remap='B'>post-build</emphasis>, +<emphasis role="bold">post-build</emphasis>, which reports the final amount of memory used by SCons during each run.</para> </listitem> @@ -514,7 +514,7 @@ used by SCons during each run.</para> <term>-t NUMBER, --tail=NUMBER</term> <listitem> <para>Only reports memory statistics from the last -<emphasis remap='I'>NUMBER</emphasis> +<emphasis>NUMBER</emphasis> files.</para> <!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> </listitem> @@ -523,24 +523,24 @@ files.</para> </refsect2> <refsect2 id='the_obj_subcommand'><title>The obj Subcommand</title> -<para><emphasis remap='B'>scons-time obj</emphasis> +<para><emphasis role="bold">scons-time obj</emphasis> [<option>-h</option>] [<option>--chdir=</option><replaceable>DIR</replaceable>] -[<option>-f </option><emphasis remap='I'>FILE</emphasis>] +[<option>-f </option><emphasis>FILE</emphasis>] [<option>--fmt=</option><replaceable>FORMAT</replaceable>] -[<option>-p </option><emphasis remap='I'>STRING</emphasis>] +[<option>-p </option><emphasis>STRING</emphasis>] [<option>--stage=</option><replaceable>STAGE</replaceable>] -[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>] +[<option>-t </option><emphasis>NUMBER</emphasis>] [<option>--title=</option><replaceable>TITLE</replaceable>] -[<emphasis remap='I'>ARGUMENTS</emphasis>]</para> +[<emphasis>ARGUMENTS</emphasis>]</para> <para>The -<emphasis remap='B'>scons-time obj</emphasis> +<emphasis role="bold">scons-time obj</emphasis> subcommand displays how many objects of a specific named type are created by SCons.</para> <para>The -<emphasis remap='B'>scons-time obj</emphasis> +<emphasis role="bold">scons-time obj</emphasis> subcommand extracts object counts from all the specified file arguments, which should be files containing output from @@ -548,9 +548,9 @@ running SCons with the <option>--debug=count</option> option. (Normally, these would be -<emphasis remap='B'>*.log</emphasis> +<emphasis role="bold">*.log</emphasis> files generated by the -<emphasis remap='B'>scons-time run</emphasis> +<emphasis role="bold">scons-time run</emphasis> subcommand.) All file name arguments will be globbed for on-disk files.</para> @@ -558,18 +558,18 @@ globbed for on-disk files.</para> <para>If no arguments are specified, then object counts will be extracted from all -<emphasis remap='B'>*.log</emphasis> +<emphasis role="bold">*.log</emphasis> files, or the subset of them with a prefix specified by the <option>-p</option> option.</para> -<variablelist remap='TP'> +<variablelist> <varlistentry> <term>-C DIR, --chdir=DIR</term> <listitem> <para>Changes to the specified -<emphasis remap='I'>DIRECTORY</emphasis> +<emphasis>DIRECTORY</emphasis> before looking for the specified files (or files that match the specified patterns).</para> </listitem> @@ -578,26 +578,26 @@ before looking for the specified files <term>-f FILE, --file=FILE</term> <listitem> <para>Reads configuration information from the specified -<emphasis remap='I'>FILE</emphasis>.</para> +<emphasis>FILE</emphasis>.</para> </listitem> </varlistentry> <varlistentry> <term>-fmt=FORMAT, --format=FORMAT</term> <listitem> <para>Reports the output in the specified -<emphasis remap='I'>FORMAT</emphasis>. +<emphasis>FORMAT</emphasis>. The formats currently supported are -<emphasis remap='B'>ascii</emphasis> +<emphasis role="bold">ascii</emphasis> (the default) and -<emphasis remap='B'>gnuplot</emphasis>.</para> +<emphasis role="bold">gnuplot</emphasis>.</para> </listitem> </varlistentry> <varlistentry> <term>-h, --help</term> <listitem> <para>Displays help text for the -<emphasis remap='B'>scons-time obj</emphasis> +<emphasis role="bold">scons-time obj</emphasis> subcommand.</para> </listitem> </varlistentry> @@ -614,21 +614,21 @@ if no arguments are specified on the command line.</para> <term>--stage=STAGE</term> <listitem> <para>Prints the object count at the end of the specified -<emphasis remap='I'>STAGE</emphasis>: -<emphasis remap='B'>pre-read</emphasis> +<emphasis>STAGE</emphasis>: +<emphasis role="bold">pre-read</emphasis> (before the SConscript files are read), -<emphasis remap='B'>post-read ,</emphasis> +<emphasis role="bold">post-read ,</emphasis> (after the SConscript files are read), -<emphasis remap='B'>pre-build</emphasis> +<emphasis role="bold">pre-build</emphasis> (before any targets are built) or -<emphasis remap='B'>post-build</emphasis> +<emphasis role="bold">post-build</emphasis> (after any targets are built). If no <option>--stage</option> option is specified, the default behavior is -<emphasis remap='B'>post-build</emphasis>, +<emphasis role="bold">post-build</emphasis>, which reports the final object count during each run.</para> </listitem> </varlistentry> @@ -636,7 +636,7 @@ which reports the final object count during each run.</para> <term>-t NUMBER, --tail=NUMBER</term> <listitem> <para>Only reports object counts from the last -<emphasis remap='I'>NUMBER</emphasis> +<emphasis>NUMBER</emphasis> files.</para> <!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> </listitem> @@ -645,20 +645,20 @@ files.</para> </refsect2> <refsect2 id='the_run_subcommand'><title>The run Subcommand</title> -<para><emphasis remap='B'>scons-time run</emphasis> +<para><emphasis role="bold">scons-time run</emphasis> [<option>-hnqv</option>] [<option>--aegis=</option><replaceable>PROJECT</replaceable>] -[<option>-f </option><emphasis remap='I'>FILE</emphasis>] +[<option>-f </option><emphasis>FILE</emphasis>] [<option>--number=</option><replaceable>NUMBER</replaceable>] [<option>--outdir=</option><replaceable>OUTDIR</replaceable>] -[<option>-p </option><emphasis remap='I'>STRING</emphasis>] +[<option>-p </option><emphasis>STRING</emphasis>] [<option>--python=</option><replaceable>PYTHON</replaceable>] -[<option>-s </option><emphasis remap='I'>DIR</emphasis>] +[<option>-s </option><emphasis>DIR</emphasis>] [<option>--scons=</option><replaceable>SCONS</replaceable>] [<option>--svn=</option><replaceable>URL</replaceable>] -[<emphasis remap='I'>ARGUMENTS</emphasis>] +[<emphasis>ARGUMENTS</emphasis>] The -<emphasis remap='B'>scons-time run</emphasis> +<emphasis role="bold">scons-time run</emphasis> subcommand is the basic subcommand for profiling a specific configuration against a version of SCons.</para> @@ -669,7 +669,7 @@ or directories that will be unpacked or copied into a temporary directory in which SCons will be invoked. The -<emphasis remap='B'>scons-time run</emphasis> +<emphasis role="bold">scons-time run</emphasis> subcommand understands file suffixes like <markup>.tar</markup>, <markup>.tar.gz</markup>, @@ -687,12 +687,12 @@ specified archives share the same directory layout.</para> <para>Once the file or directory arguments are unpacked or copied to the temporary directory, the -<emphasis remap='B'>scons-time run</emphasis> +<emphasis role="bold">scons-time run</emphasis> subcommand runs the requested version of SCons against the configuration three times:</para> -<variablelist remap='TP'> +<variablelist> <varlistentry> <term>Startup</term> <listitem> @@ -710,7 +710,7 @@ and processing the SConscript files.</para> <para>SCons is run to build everything specified in the configuration. Specific targets to be passed in on the command l ine may be specified by the -<emphasis remap='B'>targets</emphasis> +<emphasis role="bold">targets</emphasis> keyword in a configuration file; see below for details.</para> </listitem> </varlistentry> @@ -727,17 +727,17 @@ this should be an up-to-date, "do nothing" rebuild.</para> <para>Each invocation captures the output log file and a profile.</para> <para>The -<emphasis remap='B'>scons-time run</emphasis> +<emphasis role="bold">scons-time run</emphasis> subcommand supports the following options:</para> -<variablelist remap='TP'> +<variablelist> <varlistentry> <term>--aegis=PROJECT</term> <listitem> <para>Specifies the Aegis -<emphasis remap='I'>PROJECT</emphasis> +<emphasis>PROJECT</emphasis> from which the version(s) of -<emphasis remap='B'>scons</emphasis> +<emphasis role="bold">scons</emphasis> being timed will be extracted. When <option>--aegis</option> @@ -752,14 +752,14 @@ If the option is not specified, then the default behavior is to time the tip of the specified -<emphasis remap='I'>PROJECT</emphasis>.</para> +<emphasis>PROJECT</emphasis>.</para> </listitem> </varlistentry> <varlistentry> <term>-f FILE, --file=FILE</term> <listitem> <para>Reads configuration information from the specified -<emphasis remap='I'>FILE</emphasis>. +<emphasis>FILE</emphasis>. This often provides a more convenient way to specify and collect parameters associated with a specific timing configuration than specifying them on the command line. @@ -773,7 +773,7 @@ for information about the configuration file parameters.</para> <term>-h, --help</term> <listitem> <para>Displays help text for the -<emphasis remap='B'>scons-time run</emphasis> +<emphasis role="bold">scons-time run</emphasis> subcommand.</para> </listitem> </varlistentry> @@ -788,7 +788,7 @@ script actually executes its actions in Python, where possible, for portability. The commands displayed are UNIX -<emphasis remap='I'>equivalents</emphasis> +<emphasis>equivalents</emphasis> of what it's doing.</para> </listitem> </varlistentry> @@ -804,29 +804,29 @@ the log files and profile outputs generated by this run.</para> <para>When used in conjuction with the <option>--aegis=</option><replaceable>PROJECT</replaceable> option, -<emphasis remap='I'>NUMBER</emphasis> +<emphasis>NUMBER</emphasis> specifies one or more comma-separated Aegis delta numbers that will be retrieved automatically from the specified Aegis -<emphasis remap='I'>PROJECT</emphasis>.</para> +<emphasis>PROJECT</emphasis>.</para> <para>When used in conjuction with the <option>--svn=</option><replaceable>URL</replaceable> option, -<emphasis remap='I'>NUMBER</emphasis> +<emphasis>NUMBER</emphasis> specifies one or more comma-separated Subversion revision numbers that will be retrieved automatically from the Subversion repository at the specified -<emphasis remap='I'>URL</emphasis>. +<emphasis>URL</emphasis>. Ranges of delta or revision numbers may be specified be separating two numbers with a hyphen -(<emphasis remap='B'>-</emphasis>).</para> +(<emphasis role="bold">-</emphasis>).</para> <para>Example:</para> -<literallayout remap='.nf'> +<literallayout> % scons-time run --svn=<ulink url='http://scons.tigris.org/svn/trunk'>http://scons.tigris.org/svn/trunk</ulink> --num=1247,1249-1252 . </literallayout> <!-- .fi --> -<variablelist remap='TP'> +<variablelist> <varlistentry> <term>-p STRING, --prefix=STRING</term> <listitem> @@ -880,10 +880,10 @@ The default is XXX</para> <term>--svn=URL, --subversion=URL</term> <listitem> <para>Specifies the -<emphasis remap='I'>URL</emphasis> +<emphasis>URL</emphasis> of the Subversion repository from which the version(s) of -<emphasis remap='B'>scons</emphasis> +<emphasis role="bold">scons</emphasis> being timed will be extracted. When <option>--svn</option> @@ -897,9 +897,9 @@ If the <option>--number=</option> option is not specified, then the default behavior is to time the -<emphasis remap='B'>HEAD</emphasis> +<emphasis role="bold">HEAD</emphasis> of the specified -<emphasis remap='I'>URL</emphasis>.</para> +<emphasis>URL</emphasis>.</para> </listitem> </varlistentry> <varlistentry> @@ -914,26 +914,26 @@ of the specified </refsect2> <refsect2 id='the_time_subcommand'><title>The time Subcommand</title> -<para><emphasis remap='B'>scons-time time</emphasis> +<para><emphasis role="bold">scons-time time</emphasis> [<option>-h</option>] [<option>--chdir=</option><replaceable>DIR</replaceable>] -[<option>-f </option><emphasis remap='I'>FILE</emphasis>] +[<option>-f </option><emphasis>FILE</emphasis>] [<option>--fmt=</option><replaceable>FORMAT</replaceable>] -[<option>-p </option><emphasis remap='I'>STRING</emphasis>] -[<option>-t </option><emphasis remap='I'>NUMBER</emphasis>] +[<option>-p </option><emphasis>STRING</emphasis>] +[<option>-t </option><emphasis>NUMBER</emphasis>] [<option>--title=</option><replaceable>TITLE</replaceable>] [<option>--which=</option><replaceable>WHICH</replaceable>] -[<emphasis remap='I'>ARGUMENTS</emphasis>]</para> +[<emphasis>ARGUMENTS</emphasis>]</para> <para>The -<emphasis remap='B'>scons-time time</emphasis> +<emphasis role="bold">scons-time time</emphasis> subcommand displays SCons execution times as reported by the <userinput>scons --debug=time</userinput> option.</para> <para>The -<emphasis remap='B'>scons-time time</emphasis> +<emphasis role="bold">scons-time time</emphasis> subcommand extracts SCons timing from all the specified file arguments, which should be files containing output from @@ -941,9 +941,9 @@ running SCons with the <option>--debug=time</option> option. (Normally, these would be -<emphasis remap='B'>*.log</emphasis> +<emphasis role="bold">*.log</emphasis> files generated by the -<emphasis remap='B'>scons-time run</emphasis> +<emphasis role="bold">scons-time run</emphasis> subcommand.) All file name arguments will be globbed for on-disk files.</para> @@ -951,18 +951,18 @@ globbed for on-disk files.</para> <para>If no arguments are specified, then execution timings will be extracted from all -<emphasis remap='B'>*.log</emphasis> +<emphasis role="bold">*.log</emphasis> files, or the subset of them with a prefix specified by the <option>-p</option> option.</para> -<variablelist remap='TP'> +<variablelist> <varlistentry> <term>-C DIR, --chdir=DIR</term> <listitem> <para>Changes to the specified -<emphasis remap='I'>DIRECTORY</emphasis> +<emphasis>DIRECTORY</emphasis> before looking for the specified files (or files that match the specified patterns).</para> </listitem> @@ -971,26 +971,26 @@ before looking for the specified files <term>-f FILE, --file=FILE</term> <listitem> <para>Reads configuration information from the specified -<emphasis remap='I'>FILE</emphasis>.</para> +<emphasis>FILE</emphasis>.</para> </listitem> </varlistentry> <varlistentry> <term>-fmt=FORMAT, --format=FORMAT</term> <listitem> <para>Reports the output in the specified -<emphasis remap='I'>FORMAT</emphasis>. +<emphasis>FORMAT</emphasis>. The formats currently supported are -<emphasis remap='B'>ascii</emphasis> +<emphasis role="bold">ascii</emphasis> (the default) and -<emphasis remap='B'>gnuplot</emphasis>.</para> +<emphasis role="bold">gnuplot</emphasis>.</para> </listitem> </varlistentry> <varlistentry> <term>-h, --help</term> <listitem> <para>Displays help text for the -<emphasis remap='B'>scons-time time</emphasis> +<emphasis role="bold">scons-time time</emphasis> subcommand.</para> </listitem> </varlistentry> @@ -1007,7 +1007,7 @@ if no arguments are specified on the command line.</para> <term>-t NUMBER, --tail=NUMBER</term> <listitem> <para>Only reports object counts from the last -<emphasis remap='I'>NUMBER</emphasis> +<emphasis>NUMBER</emphasis> files.</para> </listitem> </varlistentry> @@ -1015,23 +1015,23 @@ files.</para> <term>--which=WHICH</term> <listitem> <para>Prints the execution time for the specified -<emphasis remap='I'>WHICH</emphasis> +<emphasis>WHICH</emphasis> value: -<emphasis remap='B'>total</emphasis> +<emphasis role="bold">total</emphasis> (the total execution time), -<emphasis remap='B'>SConscripts</emphasis> +<emphasis role="bold">SConscripts</emphasis> (total execution time for the SConscript files themselves), -<emphasis remap='B'>SCons</emphasis> +<emphasis role="bold">SCons</emphasis> (exectuion time in SCons code itself) or -<emphasis remap='B'>commands</emphasis> +<emphasis role="bold">commands</emphasis> (execution time of the commands and other actions used to build targets). If no <option>--which</option> option is specified, the default behavior is -<emphasis remap='B'>total</emphasis>, +<emphasis role="bold">total</emphasis>, which reports the total execution time for each run.</para> <!-- '\"========================================================================== --> </listitem> @@ -1058,17 +1058,17 @@ command-line options or arguments for every run, and provides a handy way to "shrink-wrap" the necessary information for producing (and reporting) consistent timing runs for a given configuration.</para> -<variablelist remap='TP'> +<variablelist> <varlistentry> - <term><emphasis remap='B'>aegis</emphasis></term> + <term><emphasis role="bold">aegis</emphasis></term> <listitem> <para>The Aegis executable for extracting deltas. The default is simply -<emphasis remap='B'>aegis</emphasis>.</para> +<emphasis role="bold">aegis</emphasis>.</para> </listitem> </varlistentry> <varlistentry> - <term><emphasis remap='B'>aegis_project</emphasis></term> + <term><emphasis role="bold">aegis_project</emphasis></term> <listitem> <para>The Aegis project from which deltas should be extracted. The default is whatever is specified @@ -1078,7 +1078,7 @@ command-line option.</para> </listitem> </varlistentry> <varlistentry> - <term><emphasis remap='B'>archive_list</emphasis></term> + <term><emphasis role="bold">archive_list</emphasis></term> <listitem> <para>A list of archives (files or directories) that will be copied to the temporary directory @@ -1094,11 +1094,11 @@ Directory trees and files will be copied as-is.</para> </listitem> </varlistentry> <varlistentry> - <term><emphasis remap='B'>initial_commands</emphasis></term> + <term><emphasis role="bold">initial_commands</emphasis></term> <listitem> <para>A list of commands that will be executed before the actual timed -<emphasis remap='B'>scons</emphasis> +<emphasis role="bold">scons</emphasis> runs. This can be used for commands that are necessary to prepare the source tree-for example, @@ -1107,25 +1107,25 @@ that should not be part of the timed run.</para> </listitem> </varlistentry> <varlistentry> - <term><emphasis remap='B'>key_location</emphasis></term> + <term><emphasis role="bold">key_location</emphasis></term> <listitem> <para>The location of the key on Gnuplot graphing information generated with the <option>--format=gnuplot</option> option. The default is -<emphasis remap='B'>bottom left</emphasis>.</para> +<emphasis role="bold">bottom left</emphasis>.</para> </listitem> </varlistentry> <varlistentry> - <term><emphasis remap='B'>prefix</emphasis></term> + <term><emphasis role="bold">prefix</emphasis></term> <listitem> <para>The file name prefix to be used when running or extracting timing for this configuration.</para> </listitem> </varlistentry> <varlistentry> - <term><emphasis remap='B'>python</emphasis></term> + <term><emphasis role="bold">python</emphasis></term> <listitem> <para>The path name of the Python executable to be used when running or extracting information @@ -1135,30 +1135,30 @@ used to run the SCons</para> </listitem> </varlistentry> <varlistentry> - <term><emphasis remap='B'>scons</emphasis></term> + <term><emphasis role="bold">scons</emphasis></term> <listitem> <para>The path name of the SCons script to be used when running or extracting information for this configuration. The default is simply -<emphasis remap='B'>scons</emphasis>.</para> +<emphasis role="bold">scons</emphasis>.</para> </listitem> </varlistentry> <varlistentry> - <term><emphasis remap='B'>scons_flags</emphasis></term> + <term><emphasis role="bold">scons_flags</emphasis></term> <listitem> <para>The -<emphasis remap='B'>scons</emphasis> +<emphasis role="bold">scons</emphasis> flags used when running SCons to collect timing information. The default value is <option>--debug=count --debug=memory --debug=time --debug=memoizer</option>.</para> </listitem> </varlistentry> <varlistentry> - <term><emphasis remap='B'>scons_lib_dir</emphasis></term> - <term><emphasis remap='B'>scons_wrapper</emphasis></term> - <term><emphasis remap='B'>startup_targets</emphasis></term> - <term><emphasis remap='B'>subdir</emphasis></term> + <term><emphasis role="bold">scons_lib_dir</emphasis></term> + <term><emphasis role="bold">scons_wrapper</emphasis></term> + <term><emphasis role="bold">startup_targets</emphasis></term> + <term><emphasis role="bold">subdir</emphasis></term> <listitem> <para>The subdirectory of the project into which the <command>scons-time</command> @@ -1167,41 +1167,41 @@ before executing the SCons commands to time.</para> </listitem> </varlistentry> <varlistentry> - <term><emphasis remap='B'>subversion_url</emphasis></term> + <term><emphasis role="bold">subversion_url</emphasis></term> <listitem> <para>The Subversion URL from</para> </listitem> </varlistentry> <varlistentry> - <term><emphasis remap='B'>svn</emphasis></term> + <term><emphasis role="bold">svn</emphasis></term> <listitem> <para>The subversion executable used to check out revisions of SCons to be timed. The default is simple -<emphasis remap='B'>svn</emphasis>.</para> +<emphasis role="bold">svn</emphasis>.</para> </listitem> </varlistentry> <varlistentry> - <term><emphasis remap='B'>svn_co_flag</emphasis></term> - <term><emphasis remap='B'>tar</emphasis></term> - <term><emphasis remap='B'>targets</emphasis></term> + <term><emphasis role="bold">svn_co_flag</emphasis></term> + <term><emphasis role="bold">tar</emphasis></term> + <term><emphasis role="bold">targets</emphasis></term> <listitem> <para>A string containing the targets that should be added to the command line of every timed -<emphasis remap='B'>scons</emphasis> +<emphasis role="bold">scons</emphasis> run. This can be used to restrict what's being timed to a subset of the full build for the configuration.</para> </listitem> </varlistentry> <varlistentry> - <term><emphasis remap='B'>targets0</emphasis></term> - <term><emphasis remap='B'>targets1</emphasis></term> - <term><emphasis remap='B'>targets2</emphasis></term> - <term><emphasis remap='B'>title</emphasis></term> - <term><emphasis remap='B'>unzip</emphasis></term> - <term><emphasis remap='B'>verbose</emphasis></term> - <term><emphasis remap='B'>vertical_bars</emphasis></term> + <term><emphasis role="bold">targets0</emphasis></term> + <term><emphasis role="bold">targets1</emphasis></term> + <term><emphasis role="bold">targets2</emphasis></term> + <term><emphasis role="bold">title</emphasis></term> + <term><emphasis role="bold">unzip</emphasis></term> + <term><emphasis role="bold">verbose</emphasis></term> + <term><emphasis role="bold">vertical_bars</emphasis></term> <listitem> <!-- '\"\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\-\- --> <para></para> <!-- FIXME: blank list item --> @@ -1215,7 +1215,7 @@ subset of the full build for the configuration.</para> configuration file for a hypothetical sample project:</para> -<literallayout remap='.nf'> +<literallayout> # The project doesn't use SCons natively (yet), so we're # timing a separate set of SConscript files that we lay # on top of the vanilla unpacked project tarball. @@ -1252,15 +1252,15 @@ subversion_url = '<ulink url='http://scons.tigris.org/svn/scons/branches/core'>h <para>The <command>scons-time</command> script uses the following environment variables:</para> -<variablelist remap='TP'> +<variablelist> <varlistentry> - <term><emphasis remap='B'>PRESERVE</emphasis></term> + <term><emphasis role="bold">PRESERVE</emphasis></term> <listitem> <para>If this value is set, the <command>scons-time</command> script will -<emphasis remap='I'>not</emphasis> +<emphasis>not</emphasis> remove the temporary directory or directories in which it builds the specified configuration or downloads a specific version of SCons.</para> diff --git a/doc/man/scons.css b/doc/man/scons.css new file mode 100644 index 0000000..6941abb --- /dev/null +++ b/doc/man/scons.css @@ -0,0 +1,263 @@ +body { + background: #ffffff; + margin: 10px; + padding: 0; + font-family:palatino, georgia, verdana, arial, sans-serif; + } + + +a { + color: #80572a; + } + +a:hover { + color: #d72816; + text-decoration: none; + } + +tt { + color: #a14447; + } + +pre { + background: #e0e0e0; + } + +#main { + border: 1px solid; + border-color: black; + background-color: white; + background-image: url(../images/sconsback.png); + background-repeat: repeat-y 50% 0; + background-position: right top; + margin: 30px auto; + width: 750px; + } + +#banner { + background-image: url(../images/scons-banner.jpg); + border-bottom: 1px solid; + height: 95px; + } + +#menu { + font-family: sans-serif; + font-size: small; + line-height: 0.9em; + float: right; + width: 220px; + clear: both; + margin-top: 10px; + } + +#menu li { + margin-bottom: 7px; + } + +#menu li li { + margin-bottom: 2px; + } + +#menu li.submenuitems { + margin-bottom: 2px; + } + +#menu a { + text-decoration: none; + } + +#footer { + border-top: 1px solid black; + text-align: center; + font-size: small; + color: #822; + margin-top: 4px; + background: #eee; + } + +ul.hack { + list-style-position:inside; + } + +ul.menuitems { + list-style-type: none; + } + +ul.submenuitems { + list-style-type: none; + font-size: smaller; + margin-left: 0; + padding-left: 16px; + } + +ul.subsubmenuitems { + list-style-type: none; + font-size: smaller; + margin-left: 0; + padding-left: 16px; + } + +ol.upper-roman { + list-style-type: upper-roman; + } + +ol.decimal { + list-style-type: decimal; + } + +#currentpage { + font-weight: bold; + } + +#bodycontent { + margin: 15px; + width: 520px; + font-size: small; + line-height: 1.5em; + } + +#bodycontent li { + margin-bottom: 6px; + list-style-type: square; + } + +#sconsdownloadtable downloadtable { + display: table; + margin-left: 5%; + border-spacing: 12px 3px; + } + +#sconsdownloadtable downloadrow { + display: table-row; + } + +#sconsdownloadtable downloadentry { + display: table-cell; + text-align: center; + vertical-align: bottom; + } + +#sconsdownloadtable downloaddescription { + display: table-cell; + font-weight: bold; + text-align: left; + } + +#sconsdownloadtable downloadversion { + display: table-cell; + font-weight: bold; + text-align: center; + } + +#sconsdocversiontable sconsversiontable { + display: table; + margin-left: 10%; + border-spacing: 12px 3px; + } + +#sconsdocversiontable sconsversionrow { + display: table-row; + } + +#sconsdocversiontable docformat { + display: table-cell; + font-weight: bold; + text-align: center; + vertical-align: bottom; + } + +#sconsdocversiontable sconsversion { + display: table-cell; + font-weight: bold; + text-align: left; + } + +#sconsdocversiontable docversion { + display: table-cell; + font-weight: bold; + text-align: center; + } + +#osrating { + margin-left: 35px; + } + + +h2 { + color: #272; + color: #c01714; + font-family: sans-serif; + font-weight: normal; + } + +h2.pagetitle { + font-size: xx-large; + } +h3 { + margin-bottom: 10px; + } + +.date { + font-size: small; + color: gray; + } + +.link { + margin-bottom: 22px; + } + +.linkname { + } + +.linkdesc { + margin: 10px; + margin-top: 0; + } + +.quote { + margin-top: 20px; + margin-bottom: 10px; + background: #f8f8f8; + border: 1px solid; + border-color: #ddd; + } + +.quotetitle { + font-weight: bold; + font-size: large; + margin: 10px; + } + +.quotedesc { + margin-left: 20px; + margin-right: 10px; + margin-bottom: 15px; + } + +.quotetext { + margin-top: 20px; + margin-left: 20px; + margin-right: 10px; + font-style: italic; + } + +.quoteauthor { + font-size: small; + text-align: right; + margin-top: 10px; + margin-right: 7px; + } + +.sconslogo { + font-style: normal; + font-weight: bold; + color: #822; + } + +.downloadlink { + } + +.downloaddescription { + margin-left: 1em; + margin-bottom: 0.4em; + } diff --git a/doc/man/scons.xml b/doc/man/scons.xml index e1bbcd1..cb4169f 100644 --- a/doc/man/scons.xml +++ b/doc/man/scons.xml @@ -70,10 +70,10 @@ rebuild them.</para> <para>By default, <command>scons</command> searches for a file named -<emphasis remap='I'>SConstruct</emphasis>, -<emphasis remap='I'>Sconstruct</emphasis>, +<emphasis>SConstruct</emphasis>, +<emphasis>Sconstruct</emphasis>, or -<emphasis remap='I'>sconstruct</emphasis> +<emphasis>sconstruct</emphasis> (in that order) in the current directory and reads its configuration from the first file found. An alternate file name may be @@ -82,14 +82,14 @@ specified via the option.</para> <para>The -<emphasis remap='I'>SConstruct</emphasis> +<emphasis>SConstruct</emphasis> file can specify subsidiary configuration files using the -<emphasis remap='B'>SConscript</emphasis>() +<emphasis role="bold">SConscript</emphasis>() function. By convention, these subsidiary files are named -<emphasis remap='I'>SConscript</emphasis>, +<emphasis>SConscript</emphasis>, although any name may be used. (Because of this naming convention, the term "SConscript files" @@ -107,21 +107,21 @@ programs, object files, libraries), so that for most software projects, only the target and input files need be specified.</para> <para>Before reading the -<emphasis remap='I'>SConstruct</emphasis> +<emphasis>SConstruct</emphasis> file, <command>scons</command> looks for a directory named -<emphasis remap='I'>site_scons</emphasis> +<emphasis>site_scons</emphasis> in various system directories (see below) and the directory containing the -<emphasis remap='I'>SConstruct</emphasis> +<emphasis>SConstruct</emphasis> file; for each of those dirs which exists, -<emphasis remap='I'>site_scons</emphasis> +<emphasis>site_scons</emphasis> is prepended to sys.path, the file -<emphasis remap='I'>site_scons/site_init.py</emphasis>, +<emphasis>site_scons/site_init.py</emphasis>, is evaluated if it exists, and the directory -<emphasis remap='I'>site_scons/site_tools</emphasis> +<emphasis>site_scons/site_tools</emphasis> is prepended to the default toolpath if it exists. See the <option>--no-site-dir</option> @@ -136,13 +136,13 @@ so you may use normal Python scripting capabilities to handle complicated build situations. <command>scons</command>, however, reads and executes all of the SConscript files -<emphasis remap='I'>before</emphasis> +<emphasis>before</emphasis> it begins building any targets. To make this obvious, <command>scons</command> prints the following messages about what it is doing:</para> -<literallayout remap='.nf'> +<literallayout> $ scons foo.out scons: Reading SConscript files ... scons: done reading SConscript files. @@ -181,7 +181,7 @@ construction environment, you can propagate the value of PATH from your external environment as follows:</para> -<literallayout remap='.nf'> +<literallayout> import os env = Environment(ENV = {'PATH' : os.environ['PATH']}) </literallayout> <!-- .fi --> @@ -190,7 +190,7 @@ env = Environment(ENV = {'PATH' : os.environ['PATH']}) like $PATH, $HOME, $JAVA_HOME, $LANG, $SHELL, $TERM, etc., these variables can also be explicitly propagated:</para> -<literallayout remap='.nf'> +<literallayout> import os env = Environment(ENV = {'PATH' : os.environ['PATH'], 'HOME' : os.environ['HOME']}) @@ -199,7 +199,7 @@ env = Environment(ENV = {'PATH' : os.environ['PATH'], <para>Or you may explicitly propagate the invoking user's complete external environment:</para> -<literallayout remap='.nf'> +<literallayout> import os env = Environment(ENV = os.environ) </literallayout> <!-- .fi --> @@ -224,14 +224,14 @@ using SCCS, RCS or BitKeeper.</para> <para><command>scons</command> is normally executed in a top-level directory containing a -<emphasis remap='I'>SConstruct</emphasis> +<emphasis>SConstruct</emphasis> file, optionally specifying as command-line arguments the target file or files to be built.</para> <para>By default, the command</para> -<literallayout remap='.nf'> +<literallayout> scons </literallayout> <!-- .fi --> @@ -240,18 +240,18 @@ Explicit default targets (to be built when no targets are specified on the command line) may be defined the SConscript file(s) using the -<emphasis remap='B'>Default()</emphasis> +<emphasis role="bold">Default()</emphasis> function, described below.</para> <para>Even when -<emphasis remap='B'>Default()</emphasis> +<emphasis role="bold">Default()</emphasis> targets are specified in the SConscript file(s), all target files in or below the current directory may be built by explicitly specifying the current directory (.) as a command-line target:</para> -<literallayout remap='.nf'> +<literallayout> scons . </literallayout> <!-- .fi --> @@ -260,21 +260,21 @@ including any files outside of the current directory, may be specified by supplying a command-line target of the root directory (on POSIX systems):</para> -<literallayout remap='.nf'> +<literallayout> scons / </literallayout> <!-- .fi --> <para>or the path name(s) of the volume(s) in which all the targets should be built (on Windows systems):</para> -<literallayout remap='.nf'> +<literallayout> scons C:\ D:\ </literallayout> <!-- .fi --> <para>To build only specific targets, supply them as command-line arguments:</para> -<literallayout remap='.nf'> +<literallayout> scons foo bar </literallayout> <!-- .fi --> @@ -287,34 +287,34 @@ The flag removes all files necessary to build the specified target:</para> -<literallayout remap='.nf'> +<literallayout> scons -c . </literallayout> <!-- .fi --> <para>to remove all target files, or:</para> -<literallayout remap='.nf'> +<literallayout> scons -c build export </literallayout> <!-- .fi --> <para>to remove target files under build and export. Additional files or directories to remove can be specified using the -<emphasis remap='B'>Clean()</emphasis> +<emphasis role="bold">Clean()</emphasis> function. Conversely, targets that would normally be removed by the <option>-c</option> invocation can be prevented from being removed by using the -<emphasis remap='B'>NoClean</emphasis>() +<emphasis role="bold">NoClean</emphasis>() function.</para> <para>A subset of a hierarchical tree may be built by remaining at the top-level directory (where the -<emphasis remap='I'>SConstruct</emphasis> +<emphasis>SConstruct</emphasis> file lives) and specifying the subdirectory as the target to be built:</para> -<literallayout remap='.nf'> +<literallayout> scons src/subdir </literallayout> <!-- .fi --> @@ -322,11 +322,11 @@ scons src/subdir <option>-u</option> option, which traverses up the directory hierarchy until it finds the -<emphasis remap='I'>SConstruct</emphasis> +<emphasis>SConstruct</emphasis> file, and then builds targets relatively to the current subdirectory:</para> -<literallayout remap='.nf'> +<literallayout> cd src/subdir scons -u . </literallayout> <!-- .fi --> @@ -337,7 +337,7 @@ supports building multiple targets in parallel via a option that takes, as its argument, the number of simultaneous tasks that may be spawned:</para> -<literallayout remap='.nf'> +<literallayout> scons -j 4 </literallayout> <!-- .fi --> @@ -364,7 +364,7 @@ from trying to update the cache simultaneously.</para> <para>Values of variables to be passed to the SConscript file(s) may be specified on the command line:</para> -<literallayout remap='.nf'> +<literallayout> scons debug=1 . </literallayout> <!-- .fi --> @@ -373,7 +373,7 @@ through the ARGUMENTS dictionary, and can be used in the SConscript file(s) to modify the build in any way:</para> -<literallayout remap='.nf'> +<literallayout> if ARGUMENTS.get('debug', 0): env = Environment(CCFLAGS = '-g') else: @@ -394,7 +394,7 @@ does not exist.</para> <para><command>scons</command> requires Python version 2.4 or later. There should be no other dependencies or requirements to run -<emphasis remap='B'>scons.</emphasis></para> +<emphasis role="bold">scons.</emphasis></para> <!-- The following paragraph reflects the default tool search orders --> <!-- currently in SCons/Tool/__init__.py. If any of those search orders --> @@ -438,16 +438,16 @@ Environment construction variables.</para> <para>In general, <command>scons</command> supports the same command-line options as GNU -<emphasis remap='B'>make</emphasis>, +<emphasis role="bold">make</emphasis>, and many of those supported by -<emphasis remap='B'>cons</emphasis>.</para> +<emphasis role="bold">cons</emphasis>.</para> -<variablelist remap='TP'> +<variablelist> <varlistentry> <term>-b</term> <listitem> <para>Ignored for compatibility with non-GNU versions of -<emphasis remap='B'>make.</emphasis></para> +<emphasis role="bold">make.</emphasis></para> </listitem> </varlistentry> @@ -458,31 +458,31 @@ and many of those supported by command is specified. Also remove any files or directories associated to the construction command using the -<emphasis remap='B'>Clean</emphasis>() +<emphasis role="bold">Clean</emphasis>() function. Will not remove any targets specified by the -<emphasis remap='B'>NoClean</emphasis>() +<emphasis role="bold">NoClean</emphasis>() function.</para> </listitem> </varlistentry> <varlistentry> - <term>--cache-debug=<emphasis remap='I'>file</emphasis></term> + <term>--cache-debug=<emphasis>file</emphasis></term> <listitem> <para>Print debug information about the -<emphasis remap='B'>CacheDir</emphasis>() +<emphasis role="bold">CacheDir</emphasis>() derived-file caching to the specified -<emphasis remap='I'>file</emphasis>. +<emphasis>file</emphasis>. If -<emphasis remap='I'>file</emphasis> +<emphasis>file</emphasis> is -<emphasis remap='B'>-</emphasis> +<emphasis role="bold">-</emphasis> (a hyphen), the debug information are printed to the standard output. The printed messages describe what signature file names are being looked for in, retrieved from, or written to the -<emphasis remap='B'>CacheDir</emphasis>() +<emphasis role="bold">CacheDir</emphasis>() directory tree.</para> </listitem> @@ -491,7 +491,7 @@ directory tree.</para> <term>--cache-disable, --no-cache</term> <listitem> <para>Disable the derived-file caching specified by -<emphasis remap='B'>CacheDir</emphasis>(). +<emphasis role="bold">CacheDir</emphasis>(). <command>scons</command> will neither retrieve files from the cache nor copy files to the cache.</para> @@ -502,7 +502,7 @@ nor copy files to the cache.</para> <term>--cache-force, --cache-populate</term> <listitem> <para>When using -<emphasis remap='B'>CacheDir</emphasis>(), +<emphasis role="bold">CacheDir</emphasis>(), populate a cache by copying any already-existing, up-to-date derived files to the cache, in addition to files built by this invocation. @@ -519,7 +519,7 @@ option.</para> <term>--cache-show</term> <listitem> <para>When using -<emphasis remap='B'>CacheDir</emphasis>() +<emphasis role="bold">CacheDir</emphasis>() and retrieving a derived file from the cache, show the command that would have been executed to build the file, @@ -532,10 +532,10 @@ file was rebuilt or retrieved from the cache.</para> </listitem> </varlistentry> <varlistentry> - <term>--config=<emphasis remap='I'>mode</emphasis></term> + <term>--config=<emphasis>mode</emphasis></term> <listitem> <para>This specifies how the -<emphasis remap='B'>Configure</emphasis> +<emphasis role="bold">Configure</emphasis> call should use or generate the results of configuration tests. The option should be specified from @@ -585,15 +585,15 @@ yet have any results in the cache.</para> </listitem> </varlistentry> <varlistentry> - <term>-C<emphasis remap='I'> directory</emphasis>, --directory=<emphasis remap='I'>directory</emphasis></term> + <term>-C<emphasis> directory</emphasis>, --directory=<emphasis>directory</emphasis></term> <listitem> <para>Change to the specified -<emphasis remap='I'>directory</emphasis> +<emphasis>directory</emphasis> before searching for the -<emphasis remap='I'>SConstruct</emphasis>, -<emphasis remap='I'>Sconstruct</emphasis>, +<emphasis>SConstruct</emphasis>, +<emphasis>Sconstruct</emphasis>, or -<emphasis remap='I'>sconstruct</emphasis> +<emphasis>sconstruct</emphasis> file, or doing anything else. Multiple <option>-C</option> @@ -604,10 +604,10 @@ option wins. (This option is nearly equivalent to <option>-f directory/SConstruct</option>, except that it will search for -<emphasis remap='I'>SConstruct</emphasis>, -<emphasis remap='I'>Sconstruct</emphasis>, +<emphasis>SConstruct</emphasis>, +<emphasis>Sconstruct</emphasis>, or -<emphasis remap='I'>sconstruct</emphasis> +<emphasis>sconstruct</emphasis> in the specified directory.)</para> <!-- .TP --> @@ -631,10 +631,10 @@ directory.</para> </listitem> </varlistentry> <varlistentry> - <term>--debug=<emphasis remap='I'>type</emphasis></term> + <term>--debug=<emphasis>type</emphasis></term> <listitem> <para>Debug the build process. -<emphasis remap='I'>type</emphasis> +<emphasis>type</emphasis> specifies what type of debugging:</para> </listitem> @@ -652,7 +652,7 @@ This is not supported when SCons is executed with the Python or when the SCons modules have been compiled with optimization (that is, when executing from -<emphasis remap='B'>*.pyo</emphasis> +<emphasis role="bold">*.pyo</emphasis> files).</para> </listitem> @@ -685,7 +685,7 @@ and ultimately removed.</para> is deciding to (re-)build any targets. (Note: this does not print anything for targets that are -<emphasis remap='I'>not</emphasis> +<emphasis>not</emphasis> rebuilt.)</para> </listitem> @@ -707,7 +707,7 @@ and about the actual libraries it finds.</para> This is generally used to find out what files are included by the sources of a given derived file:</para> -<literallayout remap='.nf'> +<literallayout> $ scons --debug=includes foo.o </literallayout> <!-- .fi --> @@ -778,7 +778,7 @@ is at least considering them or not.</para> before the construction environment variables are substituted. Also shows which targets are being built by this command. Output looks something like this:</para> -<literallayout remap='.nf'> +<literallayout> $ scons --debug=presub Building myprog.o with action(s): $SHCC $SHCFLAGS $SHCCFLAGS $CPPFLAGS $_CPPINCFLAGS -c -o $TARGET $SOURCES @@ -830,7 +830,7 @@ in between executing each command. When <command>scons</command> is executed -<emphasis remap='I'>with</emphasis> +<emphasis>with</emphasis> the <option>-j</option> option, @@ -856,7 +856,7 @@ and ultimately removed.</para> </listitem> </varlistentry> <varlistentry> - <term>--diskcheck=<emphasis remap='I'>types</emphasis></term> + <term>--diskcheck=<emphasis>types</emphasis></term> <listitem> <para>Enable specific checks for whether or not there is a file on disk @@ -865,20 +865,20 @@ where the SCons configuration expects a directory and whether or not RCS or SCCS sources exist when searching for source and include files. The -<emphasis remap='I'>types</emphasis> +<emphasis>types</emphasis> argument can be set to: -<emphasis remap='B'>all</emphasis>, +<emphasis role="bold">all</emphasis>, to enable all checks explicitly (the default behavior); -<emphasis remap='B'>none</emphasis>, +<emphasis role="bold">none</emphasis>, to disable all such checks; -<emphasis remap='B'>match</emphasis>, +<emphasis role="bold">match</emphasis>, to check that files and directories on disk match SCons' expected configuration; -<emphasis remap='B'>rcs</emphasis>, +<emphasis role="bold">rcs</emphasis>, to check for the existence of an RCS source for any missing source or include files; -<emphasis remap='B'>sccs</emphasis>, +<emphasis role="bold">sccs</emphasis>, to check for the existence of an SCCS source for any missing source or include files. Multiple checks can be specified separated by commas; @@ -900,21 +900,21 @@ where the SCons configuration expects a directory).</para> </listitem> </varlistentry> <varlistentry> - <term>--duplicate=<emphasis remap='I'>ORDER</emphasis></term> + <term>--duplicate=<emphasis>ORDER</emphasis></term> <listitem> <para>There are three ways to duplicate files in a build tree: hard links, soft (symbolic) links and copies. The default behaviour of SCons is to prefer hard links to soft links to copies. You can specify different behaviours with this option. -<emphasis remap='I'>ORDER</emphasis> +<emphasis>ORDER</emphasis> must be one of -<emphasis remap='I'>hard-soft-copy</emphasis> +<emphasis>hard-soft-copy</emphasis> (the default), -<emphasis remap='I'>soft-hard-copy</emphasis>, -<emphasis remap='I'>hard-copy</emphasis>, -<emphasis remap='I'>soft-copy</emphasis> +<emphasis>soft-hard-copy</emphasis>, +<emphasis>hard-copy</emphasis>, +<emphasis>soft-copy</emphasis> or -<emphasis remap='I'>copy</emphasis>. +<emphasis>copy</emphasis>. SCons will attempt to duplicate files using the mechanisms in the specified order.</para> @@ -926,10 +926,10 @@ the mechanisms in the specified order.</para> </listitem> </varlistentry> <varlistentry> - <term>-f<emphasis remap='I'> file</emphasis>, --file=<emphasis remap='I'>file</emphasis>, --makefile=<emphasis remap='I'>file</emphasis>, --sconstruct=<emphasis remap='I'>file</emphasis></term> + <term>-f<emphasis> file</emphasis>, --file=<emphasis>file</emphasis>, --makefile=<emphasis>file</emphasis>, --sconstruct=<emphasis>file</emphasis></term> <listitem> <para>Use -<emphasis remap='I'>file</emphasis> +<emphasis>file</emphasis> as the initial SConscript file. Multiple <option>-f</option> @@ -968,10 +968,10 @@ exit.</para> </listitem> </varlistentry> <varlistentry> - <term>-I<emphasis remap='I'> directory</emphasis>, --include-dir=<emphasis remap='I'>directory</emphasis></term> + <term>-I<emphasis> directory</emphasis>, --include-dir=<emphasis>directory</emphasis></term> <listitem> <para>Specifies a -<emphasis remap='I'>directory</emphasis> +<emphasis>directory</emphasis> to search for imported Python modules. If several <option>-I</option> @@ -998,7 +998,7 @@ but with the following limitations:</para> <para><command>scons</command> will not detect changes to implicit dependency search paths (e.g. -<emphasis remap='B'>CPPPATH</emphasis>, <emphasis remap='B'>LIBPATH</emphasis>) +<emphasis role="bold">CPPPATH</emphasis>, <emphasis role="bold">LIBPATH</emphasis>) that would ordinarily cause different versions of same-named files to be used.</para> @@ -1007,10 +1007,10 @@ will miss changes in the implicit dependencies in cases where a new implicit dependency is added earlier in the implicit dependency search path (e.g. -<emphasis remap='B'>CPPPATH</emphasis>, <emphasis remap='B'>LIBPATH</emphasis>) +<emphasis role="bold">CPPPATH</emphasis>, <emphasis role="bold">LIBPATH</emphasis>) than a current implicit dependency with the same name.</para> -<variablelist remap='TP'> +<variablelist> <varlistentry> <term>--implicit-deps-changed</term> <listitem> @@ -1035,7 +1035,7 @@ This implies <listitem> <para>Starts SCons in interactive mode. The SConscript files are read once and a -<emphasis remap='B'>scons>>></emphasis> +<emphasis role="bold">scons>>></emphasis> prompt is printed. Targets may now be rebuilt by typing commands at interactive prompt without having to re-read the SConscript files @@ -1043,27 +1043,27 @@ and re-initialize the dependency graph from scratch.</para> <para>SCons interactive mode supports the following commands:</para> - <blockquote remap='RS'> - <variablelist remap='TP'> + <blockquote> + <variablelist> <varlistentry> - <term><emphasis remap='B'>build</emphasis><emphasis remap='I'>[OPTIONS] [TARGETS] ...</emphasis></term> + <term><emphasis role="bold">build</emphasis><emphasis>[OPTIONS] [TARGETS] ...</emphasis></term> <listitem> <para>Builds the specified -<emphasis remap='I'>TARGETS</emphasis> +<emphasis>TARGETS</emphasis> (and their dependencies) with the specified SCons command-line -<emphasis remap='I'>OPTIONS</emphasis>. -<emphasis remap='B'>b</emphasis> +<emphasis>OPTIONS</emphasis>. +<emphasis role="bold">b</emphasis> and <command>scons</command> are synonyms.</para> <para>The following SCons command-line options affect the -<emphasis remap='B'>build</emphasis> +<emphasis role="bold">build</emphasis> command:</para> -<literallayout remap='.nf'> +<literallayout> --cache-debug=FILE --cache-disable, --no-cache --cache-force, --cache-populate @@ -1086,20 +1086,20 @@ command:</para> <para>Any other SCons command-line options that are specified do not cause errors but have no effect on the -<emphasis remap='B'>build</emphasis> +<emphasis role="bold">build</emphasis> command (mainly because they affect how the SConscript files are read, which only happens once at the beginning of interactive mode).</para> - <variablelist remap='TP'> + <variablelist> <varlistentry> - <term><emphasis remap='B'>clean</emphasis><emphasis remap='I'>[OPTIONS] [TARGETS] ...</emphasis></term> + <term><emphasis role="bold">clean</emphasis><emphasis>[OPTIONS] [TARGETS] ...</emphasis></term> <listitem> <para>Cleans the specified -<emphasis remap='I'>TARGETS</emphasis> +<emphasis>TARGETS</emphasis> (and their dependencies) with the specified options. -<emphasis remap='B'>c</emphasis> +<emphasis role="bold">c</emphasis> is a synonym. This command is itself a synonym for <userinput>build --clean</userinput></para> @@ -1107,7 +1107,7 @@ This command is itself a synonym for </listitem> </varlistentry> <varlistentry> - <term><emphasis remap='B'>exit</emphasis></term> + <term><emphasis role="bold">exit</emphasis></term> <listitem> <para>Exits SCons interactive mode. You can also exit by terminating input @@ -1117,28 +1117,28 @@ CTRL+Z on Windows systems).</para> </listitem> </varlistentry> <varlistentry> - <term><emphasis remap='B'>help</emphasis><emphasis remap='I'>[COMMAND]</emphasis></term> + <term><emphasis role="bold">help</emphasis><emphasis>[COMMAND]</emphasis></term> <listitem> <para>Provides a help message about the commands available in SCons interactive mode. If -<emphasis remap='I'>COMMAND</emphasis> +<emphasis>COMMAND</emphasis> is specified, -<emphasis remap='B'>h</emphasis> +<emphasis role="bold">h</emphasis> and -<emphasis remap='B'>?</emphasis> +<emphasis role="bold">?</emphasis> are synonyms.</para> </listitem> </varlistentry> <varlistentry> - <term><emphasis remap='B'>shell</emphasis><emphasis remap='I'>[COMMANDLINE]</emphasis></term> + <term><emphasis role="bold">shell</emphasis><emphasis>[COMMANDLINE]</emphasis></term> <listitem> <para>Executes the specified -<emphasis remap='I'>COMMANDLINE</emphasis> +<emphasis>COMMANDLINE</emphasis> in a subshell. If no -<emphasis remap='I'>COMMANDLINE</emphasis> +<emphasis>COMMANDLINE</emphasis> is specified, executes the interactive command interpreter specified in the @@ -1146,24 +1146,24 @@ specified in the environment variable (on UNIX and Linux systems) or the -<emphasis remap='B'>COMSPEC</emphasis> +<emphasis role="bold">COMSPEC</emphasis> environment variable (on Windows systems). -<emphasis remap='B'>sh</emphasis> +<emphasis role="bold">sh</emphasis> and -<emphasis remap='B'>!</emphasis> +<emphasis role="bold">!</emphasis> are synonyms.</para> </listitem> </varlistentry> <varlistentry> - <term><emphasis remap='B'>version</emphasis></term> + <term><emphasis role="bold">version</emphasis></term> <listitem> <para>Prints SCons version information.</para> </listitem> </varlistentry> </variablelist> - </blockquote> <!-- remap='RE' --> + </blockquote> </listitem> </varlistentry> @@ -1171,10 +1171,10 @@ are synonyms.</para> <para>An empty line repeats the last typed command. Command-line editing can be used if the -<emphasis remap='B'>readline</emphasis> +<emphasis role="bold">readline</emphasis> module is available.</para> -<literallayout remap='.nf'> +<literallayout> $ scons --interactive scons: Reading SConscript files ... scons: done reading SConscript files. @@ -1182,9 +1182,9 @@ scons>>> build -n prog scons>>> exit </literallayout> <!-- .fi --> -<variablelist remap='TP'> +<variablelist> <varlistentry> - <term>-j<emphasis remap='I'> N</emphasis>, --jobs=<emphasis remap='I'>N</emphasis></term> + <term>-j<emphasis> N</emphasis>, --jobs=<emphasis>N</emphasis></term> <listitem> <para>Specifies the number of jobs (commands) to run simultaneously. If there is more than one @@ -1243,15 +1243,15 @@ targets specified on the command line will still be processed.</para> <term>-m</term> <listitem> <para>Ignored for compatibility with non-GNU versions of -<emphasis remap='B'>make</emphasis>.</para> +<emphasis role="bold">make</emphasis>.</para> </listitem> </varlistentry> <varlistentry> - <term>--max-drift=<emphasis remap='I'>SECONDS</emphasis></term> + <term>--max-drift=<emphasis>SECONDS</emphasis></term> <listitem> <para>Set the maximum expected drift in the modification time of files to -<emphasis remap='I'>SECONDS</emphasis>. +<emphasis>SECONDS</emphasis>. This value determines how long a file must be unmodified before its cached content signature will be used instead of @@ -1268,10 +1268,10 @@ no matter how old the file is.</para> </listitem> </varlistentry> <varlistentry> - <term>--md5-chunksize=<emphasis remap='I'>KILOBYTES</emphasis></term> + <term>--md5-chunksize=<emphasis>KILOBYTES</emphasis></term> <listitem> <para>Set the block size used to compute MD5 signatures to -<emphasis remap='I'>KILOBYTES</emphasis>. +<emphasis>KILOBYTES</emphasis>. This value determines the size of the chunks which are read in at once when computing MD5 signatures. Files below that size are fully stored in memory before performing the signature computation while bigger files are read in @@ -1295,13 +1295,13 @@ any out-of-date target files, but do not execute the commands.</para> <term>--no-site-dir</term> <listitem> <para>Prevents the automatic addition of the standard -<emphasis remap='I'>site_scons</emphasis> +<emphasis>site_scons</emphasis> dirs to -<emphasis remap='I'>sys.path</emphasis>. +<emphasis>sys.path</emphasis>. Also prevents loading the -<emphasis remap='I'>site_scons/site_init.py</emphasis> +<emphasis>site_scons/site_init.py</emphasis> modules if they exist, and prevents adding their -<emphasis remap='I'>site_scons/site_tools</emphasis> +<emphasis>site_scons/site_tools</emphasis> dirs to the toolpath.</para> <!-- .TP --> @@ -1337,11 +1337,11 @@ dirs to the toolpath.</para> </listitem> </varlistentry> <varlistentry> - <term>--profile=<emphasis remap='I'>file</emphasis></term> + <term>--profile=<emphasis>file</emphasis></term> <listitem> <para>Run SCons under the Python profiler and save the results in the specified -<emphasis remap='I'>file</emphasis>. +<emphasis>file</emphasis>. The results may be analyzed using the Python pstats module.</para> @@ -1395,25 +1395,25 @@ Also suppresses SCons status messages.</para> <term>-S, --no-keep-going, --stop</term> <listitem> <para>Ignored for compatibility with GNU -<emphasis remap='B'>make</emphasis>.</para> +<emphasis role="bold">make</emphasis>.</para> </listitem> </varlistentry> <varlistentry> - <term>--site-dir=<emphasis remap='I'>dir</emphasis></term> + <term>--site-dir=<emphasis>dir</emphasis></term> <listitem> <para>Uses the named dir as the site dir rather than the default -<emphasis remap='I'>site_scons</emphasis> +<emphasis>site_scons</emphasis> dirs. This dir will get prepended to -<emphasis remap='I'>sys.path</emphasis>, +<emphasis>sys.path</emphasis>, the module -<emphasis remap='I'>dir</emphasis>/site_init.py +<emphasis>dir</emphasis>/site_init.py will get loaded if it exists, and -<emphasis remap='I'>dir</emphasis>/site_tools +<emphasis>dir</emphasis>/site_tools will get added to the default toolpath.</para> <para>The default set of -<emphasis remap='I'>site_scons</emphasis> +<emphasis>site_scons</emphasis> dirs used when <option>--site-dir</option> is not specified depends on the system platform, as follows. Note @@ -1426,11 +1426,11 @@ the last dir examined comes first in the resulting path.</para> </listitem> </varlistentry> </variablelist> -<variablelist remap='IP'> +<variablelist> <varlistentry> <term>Windows:</term> <listitem> -<literallayout remap='.nf'> +<literallayout> %ALLUSERSPROFILE/Application Data/scons/site_scons %USERPROFILE%/Local Settings/Application Data/scons/site_scons %APPDATA%/scons/site_scons @@ -1442,7 +1442,7 @@ the last dir examined comes first in the resulting path.</para> <varlistentry> <term>Mac OS X:</term> <listitem> -<literallayout remap='.nf'> +<literallayout> /Library/Application Support/SCons/site_scons /opt/local/share/scons/site_scons (for MacPorts) /sw/share/scons/site_scons (for Fink) @@ -1455,7 +1455,7 @@ the last dir examined comes first in the resulting path.</para> <varlistentry> <term>Solaris:</term> <listitem> -<literallayout remap='.nf'> +<literallayout> /opt/sfw/scons/site_scons /usr/share/scons/site_scons $HOME/.scons/site_scons @@ -1466,7 +1466,7 @@ the last dir examined comes first in the resulting path.</para> <varlistentry> <term>Linux, HPUX, and other Posix-like systems:</term> <listitem> -<literallayout remap='.nf'> +<literallayout> /usr/share/scons/site_scons $HOME/.scons/site_scons ./site_scons @@ -1475,17 +1475,17 @@ the last dir examined comes first in the resulting path.</para> </listitem> </varlistentry> </variablelist> -<variablelist remap='TP'> +<variablelist> <varlistentry> - <term>--stack-size=<emphasis remap='I'>KILOBYTES</emphasis></term> + <term>--stack-size=<emphasis>KILOBYTES</emphasis></term> <listitem> <para>Set the size stack used to run threads to -<emphasis remap='I'>KILOBYTES</emphasis>. +<emphasis>KILOBYTES</emphasis>. This value determines the stack size of the threads used to run jobs. These are the threads that execute the actions of the builders for the nodes that are out-of-date. Note that this option has no effect unless the -<emphasis remap='B'>num_jobs</emphasis> +<emphasis role="bold">num_jobs</emphasis> option, which corresponds to -j and --jobs, is larger than one. Using a stack size that is too small may cause stack overflow errors. This usually shows up as segmentation faults that cause scons to abort @@ -1503,7 +1503,7 @@ unless you encounter stack overflow errors.</para> <term>-t, --touch</term> <listitem> <para>Ignored for compatibility with GNU -<emphasis remap='B'>make</emphasis>. +<emphasis role="bold">make</emphasis>. (Touching a file to make it appear up-to-date is unnecessary when using <command>scons</command>.)</para> @@ -1511,27 +1511,27 @@ appear up-to-date is unnecessary when using </listitem> </varlistentry> <varlistentry> - <term>--taskmastertrace=<emphasis remap='I'>file</emphasis></term> + <term>--taskmastertrace=<emphasis>file</emphasis></term> <listitem> <para>Prints trace information to the specified -<emphasis remap='I'>file</emphasis> +<emphasis>file</emphasis> about how the internal Taskmaster object evaluates and controls the order in which Nodes are built. A file name of -<emphasis remap='B'>-</emphasis> +<emphasis role="bold">-</emphasis> may be used to specify the standard output.</para> </listitem> </varlistentry> <varlistentry> - <term>-tree=<emphasis remap='I'>options</emphasis></term> + <term>-tree=<emphasis>options</emphasis></term> <listitem> <para>Prints a tree of the dependencies after each top-level target is built. This prints out some or all of the tree, in various formats, depending on the -<emphasis remap='I'>options</emphasis> +<emphasis>options</emphasis> specified:</para> </listitem> @@ -1568,7 +1568,7 @@ not source files.</para> for nodes that have already been displayed. Any node that has already been displayed will have its name printed in -<emphasis remap='B'>[square brackets]</emphasis>, +<emphasis role="bold">[square brackets]</emphasis>, as an indication that the dependencies for that node can be found by searching for the relevant output higher up in the tree.</para> @@ -1580,7 +1580,7 @@ for the relevant output higher up in the tree.</para> <para>Multiple options may be specified, separated by commas:</para> -<literallayout remap='.nf'> +<literallayout> # Prints only derived files, with status information: scons --tree=derived,status @@ -1589,15 +1589,15 @@ scons --tree=derived,status scons --tree=all,prune,status target </literallayout> <!-- .fi --> -<variablelist remap='TP'> +<variablelist> <varlistentry> <term>-u, --up, --search-up</term> <listitem> <para>Walks up the directory structure until an -<emphasis remap='I'>SConstruct ,</emphasis> -<emphasis remap='I'>Sconstruct</emphasis> +<emphasis>SConstruct ,</emphasis> +<emphasis>Sconstruct</emphasis> or -<emphasis remap='I'>sconstruct</emphasis> +<emphasis>sconstruct</emphasis> file is found, and uses that as the top of the directory tree. If no targets are specified on the command line, @@ -1646,10 +1646,10 @@ after other processing.</para> </listitem> </varlistentry> <varlistentry> - <term>--warn=<emphasis remap='I'>type</emphasis>, --warn=no-<emphasis remap='I'>type</emphasis></term> + <term>--warn=<emphasis>type</emphasis>, --warn=no-<emphasis>type</emphasis></term> <listitem> <para>Enable or disable warnings. -<emphasis remap='I'>type</emphasis> +<emphasis>type</emphasis> specifies the type of warnings to be enabled or disabled:</para> </listitem> @@ -1666,7 +1666,7 @@ specifies the type of warnings to be enabled or disabled:</para> <listitem> <para>Enables or disables warnings about errors trying to write a copy of a built file to a specified -<emphasis remap='B'>CacheDir</emphasis>(). +<emphasis role="bold">CacheDir</emphasis>(). These warnings are disabled by default.</para> </listitem> @@ -1706,13 +1706,13 @@ Warnings for some specific deprecated features may be enabled or disabled individually; see below.</para> - <blockquote remap='RS'> - <variablelist remap='TP'> + <blockquote> + <variablelist> <varlistentry> <term>--warn=deprecated-copy, --warn=no-deprecated-copy</term> <listitem> <para>Enables or disables warnings about use of the deprecated -<emphasis remap='B'>env.Copy()</emphasis> +<emphasis role="bold">env.Copy()</emphasis> method.</para> </listitem> @@ -1721,9 +1721,9 @@ method.</para> <term>--warn=deprecated-source-signatures, --warn=no-deprecated-source-signatures</term> <listitem> <para>Enables or disables warnings about use of the deprecated -<emphasis remap='B'>SourceSignatures()</emphasis> +<emphasis role="bold">SourceSignatures()</emphasis> function or -<emphasis remap='B'>env.SourceSignatures()</emphasis> +<emphasis role="bold">env.SourceSignatures()</emphasis> method.</para> </listitem> @@ -1732,14 +1732,14 @@ method.</para> <term>--warn=deprecated-target-signatures, --warn=no-deprecated-target-signatures</term> <listitem> <para>Enables or disables warnings about use of the deprecated -<emphasis remap='B'>TargetSignatures()</emphasis> +<emphasis role="bold">TargetSignatures()</emphasis> function or -<emphasis remap='B'>env.TargetSignatures()</emphasis> +<emphasis role="bold">env.TargetSignatures()</emphasis> method.</para> </listitem> </varlistentry> </variablelist> - </blockquote> <!-- remap='RE' --> + </blockquote> </listitem> </varlistentry> @@ -1788,16 +1788,16 @@ that may require changes to the configuration.</para> <term>--warn=misleading-keywords, --warn=no-misleading-keywords</term> <listitem> <para>Enables or disables warnings about use of the misspelled keywords -<emphasis remap='B'>targets</emphasis> +<emphasis role="bold">targets</emphasis> and -<emphasis remap='B'>sources</emphasis> +<emphasis role="bold">sources</emphasis> when calling Builders. (Note the last -<emphasis remap='B'>s</emphasis> +<emphasis role="bold">s</emphasis> characters, the correct spellings are -<emphasis remap='B'>target</emphasis> +<emphasis role="bold">target</emphasis> and -<emphasis remap='B'>source.)</emphasis> +<emphasis role="bold">source.)</emphasis> These warnings are enabled by default.</para> </listitem> @@ -1868,15 +1868,15 @@ These warnings are enabled by default.</para> <listitem> <para>Enables or disables warnings about attempts to set the reserved construction variable names -<emphasis remap='B'>CHANGED_SOURCES</emphasis>, -<emphasis remap='B'>CHANGED_TARGETS</emphasis>, -<emphasis remap='B'>TARGET</emphasis>, -<emphasis remap='B'>TARGETS</emphasis>, -<emphasis remap='B'>SOURCE</emphasis>, -<emphasis remap='B'>SOURCES</emphasis>, -<emphasis remap='B'>UNCHANGED_SOURCES</emphasis> +<emphasis role="bold">CHANGED_SOURCES</emphasis>, +<emphasis role="bold">CHANGED_TARGETS</emphasis>, +<emphasis role="bold">TARGET</emphasis>, +<emphasis role="bold">TARGETS</emphasis>, +<emphasis role="bold">SOURCE</emphasis>, +<emphasis role="bold">SOURCES</emphasis>, +<emphasis role="bold">UNCHANGED_SOURCES</emphasis> or -<emphasis remap='B'>UNCHANGED_TARGETS</emphasis>. +<emphasis role="bold">UNCHANGED_TARGETS</emphasis>. These warnings are disabled by default.</para> </listitem> @@ -1913,7 +1913,7 @@ These warnings are enabled by default.</para> </listitem> </varlistentry> <varlistentry> - <term>-Y<emphasis remap='I'> repository</emphasis>, --repository=<emphasis remap='I'>repository</emphasis>, --srcdir=<emphasis remap='I'>repository</emphasis></term> + <term>-Y<emphasis> repository</emphasis>, --repository=<emphasis>repository</emphasis>, --srcdir=<emphasis>repository</emphasis></term> <listitem> <para>Search the specified repository for any input and target files not found in the local directory hierarchy. Multiple @@ -1935,46 +1935,46 @@ repositories are searched in the order specified.</para> files communicate build information to <command>scons</command>. A new construction environment is created using the -<emphasis remap='B'>Environment</emphasis> +<emphasis role="bold">Environment</emphasis> function:</para> -<literallayout remap='.nf'> +<literallayout> env = Environment() </literallayout> <!-- .fi --> <para>Variables, called -<emphasis remap='I'>construction</emphasis> -<emphasis remap='I'>variables</emphasis>, +<emphasis>construction</emphasis> +<emphasis>variables</emphasis>, may be set in a construction environment either by specifying them as keywords when the object is created or by assigning them a value after the object is created:</para> -<literallayout remap='.nf'> +<literallayout> env = Environment(FOO = 'foo') env['BAR'] = 'bar' </literallayout> <!-- .fi --> <para>As a convenience, construction variables may also be set or modified by the -<emphasis remap='I'>parse_flags</emphasis> +<emphasis>parse_flags</emphasis> keyword argument, which applies the -<emphasis remap='B'>ParseFlags</emphasis> +<emphasis role="bold">ParseFlags</emphasis> method (described below) to the argument value after all other processing is completed. This is useful either if the exact content of the flags is unknown (for example, read from a control file) or if the flags are distributed to a number of construction variables.</para> -<literallayout remap='.nf'> +<literallayout> env = Environment(parse_flags = '-Iinclude -DEBUG -lm') </literallayout> <!-- .fi --> <para>This example adds 'include' to -<emphasis remap='B'>CPPPATH</emphasis>, +<emphasis role="bold">CPPPATH</emphasis>, 'EBUG' to -<emphasis remap='B'>CPPDEFINES</emphasis>, +<emphasis role="bold">CPPDEFINES</emphasis>, and 'm' to -<emphasis remap='B'>LIBS</emphasis>.</para> +<emphasis role="bold">LIBS</emphasis>.</para> <para>By default, a new construction environment is initialized with a set of builder methods @@ -1984,7 +1984,7 @@ An optional platform keyword argument may be used to specify that an environment should be initialized for a different platform:</para> -<literallayout remap='.nf'> +<literallayout> env = Environment(platform = 'cygwin') env = Environment(platform = 'os2') env = Environment(platform = 'posix') @@ -1997,20 +1997,20 @@ to use and generate file names with prefixes and suffixes appropriate for the platform.</para> <para>Note that the -<emphasis remap='B'>win32</emphasis> +<emphasis role="bold">win32</emphasis> platform adds the -<emphasis remap='B'>SystemDrive</emphasis> +<emphasis role="bold">SystemDrive</emphasis> and -<emphasis remap='B'>SystemRoot</emphasis> +<emphasis role="bold">SystemRoot</emphasis> variables from the user's external environment to the construction environment's -<emphasis remap='B'>ENV</emphasis> +<emphasis role="bold">ENV</emphasis> dictionary. This is so that any executed commands that use sockets to connect with other systems (such as fetching source files from external CVS repository specifications like -<emphasis remap='B'>:pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons</emphasis>) +<emphasis role="bold">:pserver:anonymous@cvs.sourceforge.net:/cvsroot/scons</emphasis>) will work on Windows systems.</para> <para>The platform argument may be function or callable object, @@ -2018,7 +2018,7 @@ in which case the Environment() method will call the specified argument to update the new construction environment:</para> -<programlisting remap='.nf'> +<programlisting> def my_platform(env): env['VAR'] = 'xyzzy' @@ -2029,13 +2029,13 @@ env = Environment(platform = my_platform) with which to initialize the environment may be specified as an optional keyword argument:</para> -<literallayout remap='.nf'> +<literallayout> env = Environment(tools = ['msvc', 'lex']) </literallayout> <!-- .fi --> <para>Non-built-in tools may be specified using the toolpath argument:</para> -<literallayout remap='.nf'> +<literallayout> env = Environment(tools = ['default', 'foo'], toolpath = ['tools']) </literallayout> <!-- .fi --> @@ -2061,12 +2061,12 @@ would override the built-in gcc tool. Also note that the toolpath is stored in the environment for use by later calls to -<emphasis remap='B'>Clone</emphasis>() +<emphasis role="bold">Clone</emphasis>() and -<emphasis remap='B'>Tool</emphasis>() +<emphasis role="bold">Tool</emphasis>() methods:</para> -<literallayout remap='.nf'> +<literallayout> base = Environment(toolpath=['custom_path']) derived = base.Clone(tools=['custom_tool']) derived.CustomBuilder() @@ -2078,7 +2078,7 @@ in which case the Environment() method will call the specified elements to update the new construction environment:</para> -<programlisting remap='.nf'> +<programlisting> def my_tool(env): env['XYZZY'] = 'xyzzy' @@ -2087,22 +2087,22 @@ env = Environment(tools = [my_tool]) <para>The individual elements of the tools list may also themselves be two-element lists of the form -(<emphasis remap='I'>toolname</emphasis>, <emphasis remap='I'>kw_dict</emphasis>). +(<emphasis>toolname</emphasis>, <emphasis>kw_dict</emphasis>). SCons searches for the -<emphasis remap='I'>toolname</emphasis> +<emphasis>toolname</emphasis> specification file as described above, and passes -<emphasis remap='I'>kw_dict</emphasis>, +<emphasis>kw_dict</emphasis>, which must be a dictionary, as keyword arguments to the tool's -<emphasis remap='B'>generate</emphasis> +<emphasis role="bold">generate</emphasis> function. The -<emphasis remap='B'>generate</emphasis> +<emphasis role="bold">generate</emphasis> function can use the arguments to modify the tool's behavior by setting up the environment in different ways or otherwise changing its initialization.</para> -<programlisting remap='.nf'> +<programlisting> # in tools/my_tool.py: def generate(env, **kw): # Sets MY_TOOL to the value of keyword argument 'arg1' or 1. @@ -2126,88 +2126,38 @@ be redetected.</para> <para>SCons supports the following tool specifications out of the box:</para> -<literallayout remap='.nf'> -386asm -aixc++ -aixcc -aixf77 -aixlink -ar -as -bcc32 -c++ -cc -cvf -dmd -dvipdf -dvips -f77 -f90 -f95 -fortran -g++ -g77 -gas -gcc -gfortran -gnulink -gs -hpc++ -hpcc -hplink -icc -icl -ifl -ifort -ilink -ilink32 -intelc -jar -javac -javah -latex -lex -link -linkloc -m4 -masm -midl -mingw -mslib -mslink -mssdk -msvc -msvs -mwcc -mwld -nasm -pdflatex -pdftex -qt -rmic -rpcgen -sgiar -sgic++ -sgicc -sgilink -sunar -sunc++ -suncc -sunf77 -sunf90 -sunf95 -sunlink -swig -tar -tex -textfile -tlib -yacc -zip -</literallayout> <!-- .fi --> +<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" --> +<!-- '\" BEGIN GENERATED TOOL DESCRIPTIONS --> + +<!-- '\" The descriptions below of the various SCons Tools are generated --> +<!-- '\" from the .xml files that live next to the various Python modules in --> +<!-- '\" the build enginer library. If you're reading this [gnt]roff file --> +<!-- '\" with an eye towards patching this man page, you can still submit --> +<!-- '\" a diff against this text, but it will have to be translated to a --> +<!-- '\" diff against the underlying .xml file before the patch is actually --> +<!-- '\" accepted. If you do that yourself, it will make it easier to --> +<!-- '\" integrate the patch. --> + +<!-- '\" BEGIN GENERATED TOOL DESCRIPTIONS --> +<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" --> +<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="../generated/tools.gen"/> +<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" --> +<!-- '\" END GENERATED TOOL DESCRIPTIONS --> + +<!-- '\" The descriptions above of the various SCons Tools are generated --> +<!-- '\" from the .xml files that live next to the various Python modules in --> +<!-- '\" the build enginer library. If you're reading this [gnt]roff file --> +<!-- '\" with an eye towards patching this man page, you can still submit --> +<!-- '\" a diff against this text, but it will have to be translated to a --> +<!-- '\" diff against the underlying .xml file before the patch is actually --> +<!-- '\" accepted. If you do that yourself, it will make it easier to --> +<!-- '\" integrate the patch. --> + +<!-- '\" END GENERATED TOOL DESCRIPTIONS --> +<!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" --> <para>Additionally, there is a "tool" named -<emphasis remap='B'>default</emphasis> +<emphasis role="bold">default</emphasis> which configures the environment with a default set of tools for the current platform.</para> @@ -2224,11 +2174,11 @@ and in OS/2 the IBM tools (e.g. icc) are preferred by SCons.</para> <para>Build rules are specified by calling a construction environment's builder methods. The arguments to the builder methods are -<emphasis remap='B'>target</emphasis> +<emphasis role="bold">target</emphasis> (a list of targets to be built, usually file names) and -<emphasis remap='B'>source</emphasis> +<emphasis role="bold">source</emphasis> (a list of sources to be built, usually file names).</para> @@ -2236,7 +2186,7 @@ usually file names).</para> can lead to a lot of quoting, <command>scons</command> supplies a -<emphasis remap='B'>Split()</emphasis> +<emphasis role="bold">Split()</emphasis> global function and a same-named environment method that split a single string @@ -2254,7 +2204,7 @@ the target is first, followed by the source. The following are equivalent examples of calling the Program builder method:</para> -<literallayout remap='.nf'> +<literallayout> env.Program('bar', ['bar.c', 'foo.c']) env.Program('bar', Split('bar.c foo.c')) env.Program('bar', env.Split('bar.c foo.c')) @@ -2267,10 +2217,10 @@ env.Program('bar', source = 'bar.c foo.c'.split()) <para>Target and source file names that are not absolute path names (that is, do not begin with -<emphasis remap='B'>/</emphasis> +<emphasis role="bold">/</emphasis> on POSIX systems or -<emphasis remap='B'>\fR +<emphasis role="bold">\fR on Windows systems, with or without an optional drive letter) @@ -2278,22 +2228,22 @@ are interpreted relative to the directory containing the SConscript</emphasis> file being read. An initial -<emphasis remap='B'>#</emphasis> +<emphasis role="bold">#</emphasis> (hash mark) on a path name means that the rest of the file name is interpreted relative to the directory containing the top-level -<emphasis remap='B'>SConstruct</emphasis> +<emphasis role="bold">SConstruct</emphasis> file, even if the -<emphasis remap='B'>#</emphasis> +<emphasis role="bold">#</emphasis> is followed by a directory separator character (slash or backslash).</para> <para>Examples:</para> -<programlisting remap='.nf'> +<programlisting> # The comments describing the targets that will be built # assume these calls are in a SConscript file in the # a subdirectory named "subdir". @@ -2326,14 +2276,14 @@ will deduce the target file name from the source file name. The following examples all build the executable program -<emphasis remap='B'>bar</emphasis> +<emphasis role="bold">bar</emphasis> (on POSIX systems) or -<emphasis remap='B'>bar.exe</emphasis> +<emphasis role="bold">bar.exe</emphasis> (on Windows systems) from the bar.c source file:</para> -<literallayout remap='.nf'> +<literallayout> env.Program(target = 'bar', source = 'bar.c') env.Program('bar', source = 'bar.c') env.Program(source = 'bar.c') @@ -2341,24 +2291,24 @@ env.Program('bar.c') </literallayout> <!-- .fi --> <para>As a convenience, a -<emphasis remap='B'>srcdir</emphasis> +<emphasis role="bold">srcdir</emphasis> keyword argument may be specified when calling a Builder. When specified, all source file strings that are not absolute paths will be interpreted relative to the specified -<emphasis remap='B'>srcdir</emphasis>. +<emphasis role="bold">srcdir</emphasis>. The following example will build the -<emphasis remap='B'>build/prog</emphasis> +<emphasis role="bold">build/prog</emphasis> (or -<emphasis remap='B'>build/prog.exe</emphasis> +<emphasis role="bold">build/prog.exe</emphasis> on Windows) program from the files -<emphasis remap='B'>src/f1.c</emphasis> +<emphasis role="bold">src/f1.c</emphasis> and -<emphasis remap='B'>src/f2.c</emphasis>:</para> +<emphasis role="bold">src/f2.c</emphasis>:</para> -<literallayout remap='.nf'> +<literallayout> env.Program('build/prog', ['f1.c', 'f2.c'], srcdir='src') </literallayout> <!-- .fi --> @@ -2369,13 +2319,13 @@ variables will only be in effect when building the target, so they will not affect other parts of the build. For example, if you want to add additional libraries for just one program:</para> -<literallayout remap='.nf'> +<literallayout> env.Program('hello', 'hello.c', LIBS=['gl', 'glut']) </literallayout> <!-- .fi --> <para>or generate a shared library with a non-standard suffix:</para> -<literallayout remap='.nf'> +<literallayout> env.SharedLibrary('word', 'word.cpp', SHLIBSUFFIX='.ocx', LIBSUFFIXES=['.ocx']) @@ -2387,19 +2337,19 @@ for dependencies on the non-standard library names; see the descriptions of these variables, below, for more information.)</para> <para>It is also possible to use the -<emphasis remap='I'>parse_flags</emphasis> +<emphasis>parse_flags</emphasis> keyword argument in an override:</para> -<literallayout remap='.nf'> +<literallayout> env = Program('hello', 'hello.c', parse_flags = '-Iinclude -DEBUG -lm') </literallayout> <!-- .fi --> <para>This example adds 'include' to -<emphasis remap='B'>CPPPATH</emphasis>, +<emphasis role="bold">CPPPATH</emphasis>, 'EBUG' to -<emphasis remap='B'>CPPDEFINES</emphasis>, +<emphasis role="bold">CPPDEFINES</emphasis>, and 'm' to -<emphasis remap='B'>LIBS</emphasis>.</para> +<emphasis role="bold">LIBS</emphasis>.</para> <para>Although the builder methods defined by <command>scons</command> @@ -2407,7 +2357,7 @@ are, in fact, methods of a construction environment object, they may also be called without an explicit environment:</para> -<literallayout remap='.nf'> +<literallayout> Program('hello', 'hello.c') SharedLibrary('word', 'word.cpp') </literallayout> <!-- .fi --> @@ -2423,7 +2373,7 @@ environment may be called from custom Python modules that you import into an SConscript file by adding the following to the Python module:</para> -<literallayout remap='.nf'> +<literallayout> from SCons.Script import * </literallayout> <!-- .fi --> @@ -2431,7 +2381,7 @@ from SCons.Script import * containing Nodes that represent the target or targets that will be built. A -<emphasis remap='I'>Node</emphasis> +<emphasis>Node</emphasis> is an internal SCons object which represents build targets or sources.</para> @@ -2445,7 +2395,7 @@ to add a specific <option>-D</option> flag when compiling one specific object file:</para> -<literallayout remap='.nf'> +<literallayout> bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR') env.Program(source = ['foo.c', bar_obj_list, 'main.c']) </literallayout> <!-- .fi --> @@ -2465,7 +2415,7 @@ If you need to manipulate a list of lists returned by Builders directly using Python, you can either build the list by hand:</para> -<literallayout remap='.nf'> +<literallayout> foo = Object('foo.c') bar = Object('bar.c') objects = ['begin.o'] + foo + ['middle.o'] + bar + ['end.o'] @@ -2474,12 +2424,12 @@ for object in objects: </literallayout> <!-- .fi --> <para>Or you can use the -<emphasis remap='B'>Flatten</emphasis>() +<emphasis role="bold">Flatten</emphasis>() function supplied by scons to create a list containing just the Nodes, which may be more convenient:</para> -<literallayout remap='.nf'> +<literallayout> foo = Object('foo.c') bar = Object('bar.c') objects = Flatten(['begin.o', foo, 'middle.o', bar, 'end.o']) @@ -2490,9 +2440,9 @@ for object in objects: <para>Note also that because Builder calls return a list-like object, not an actual Python list, you should -<emphasis remap='I'>not</emphasis> +<emphasis>not</emphasis> use the Python -<emphasis remap='B'>+=</emphasis> +<emphasis role="bold">+=</emphasis> operator to append Builder results to a Python list. Because the list and the object are different types, Python will not update the original list in place, @@ -2507,7 +2457,7 @@ Instead, use the Python method to make sure the list is updated in-place. Example:</para> -<literallayout remap='.nf'> +<literallayout> object_files = [] # Do NOT use += as follows: @@ -2526,36 +2476,36 @@ by passing the Node to the Python-builtin <function>str()</function> function:</para> -<literallayout remap='.nf'> +<literallayout> bar_obj_list = env.StaticObject('bar.c', CPPDEFINES='-DBAR') print "The path to bar_obj is:", str(bar_obj_list[0]) </literallayout> <!-- .fi --> <para>Note again that because the Builder call returns a list, we have to access the first element in the list -<emphasis remap='B'>(bar_obj_list[0])</emphasis> +<emphasis role="bold">(bar_obj_list[0])</emphasis> to get at the Node that actually represents the object file.</para> <para>Builder calls support a -<emphasis remap='B'>chdir</emphasis> +<emphasis role="bold">chdir</emphasis> keyword argument that specifies that the Builder's action(s) should be executed after changing directory. If the -<emphasis remap='B'>chdir</emphasis> +<emphasis role="bold">chdir</emphasis> argument is a string or a directory Node, scons will change to the specified directory. If the -<emphasis remap='B'>chdir</emphasis> +<emphasis role="bold">chdir</emphasis> is not a string or Node and is non-zero, then scons will change to the target file's directory.</para> -<literallayout remap='.nf'> +<literallayout> # scons will change to the "sub" subdirectory # before executing the "cp" command. env.Command('sub/dir/foo.out', 'sub/dir/foo.in', @@ -2571,13 +2521,13 @@ env.Command('sub/dir/foo.out', 'sub/dir/foo.in', </literallayout> <!-- .fi --> <para>Note that scons will -<emphasis remap='I'>not</emphasis> +<emphasis>not</emphasis> automatically modify its expansion of construction variables like -<emphasis remap='B'>$TARGET</emphasis> +<emphasis role="bold">$TARGET</emphasis> and -<emphasis remap='B'>$SOURCE</emphasis> +<emphasis role="bold">$SOURCE</emphasis> when using the chdir keyword argument--that is, the expanded file names @@ -2589,9 +2539,9 @@ If you use the chdir keyword argument, you will typically need to supply a different command line using expansions like -<emphasis remap='B'>${TARGET.file}</emphasis> +<emphasis role="bold">${TARGET.file}</emphasis> and -<emphasis remap='B'>${SOURCE.file}</emphasis> +<emphasis role="bold">${SOURCE.file}</emphasis> to use just the filename portion of the targets and source.</para> @@ -2633,7 +2583,7 @@ provides the following builder methods:</para> targets of builder methods automatically depend on their sources. An explicit dependency can be specified using the -<emphasis remap='B'>Depends</emphasis> +<emphasis role="bold">Depends</emphasis> method of a construction environment (see below).</para> <para>In addition, @@ -2665,19 +2615,19 @@ You can also write your own Scanners to add support for additional source file types. These can be added to the default Scanner object used by the -<emphasis remap='B'>Object</emphasis>(), -<emphasis remap='B'>StaticObject</emphasis>(), +<emphasis role="bold">Object</emphasis>(), +<emphasis role="bold">StaticObject</emphasis>(), and -<emphasis remap='B'>SharedObject</emphasis>() +<emphasis role="bold">SharedObject</emphasis>() Builders by adding them to the -<emphasis remap='B'>SourceFileScanner</emphasis> +<emphasis role="bold">SourceFileScanner</emphasis> object. See the section "Scanner Objects" below, for more information about defining your own Scanner objects and using the -<emphasis remap='B'>SourceFileScanner</emphasis> +<emphasis role="bold">SourceFileScanner</emphasis> object.</para> </refsect2> @@ -2697,13 +2647,13 @@ must be called with or without a construction environment. In the following list, if you call something as a global function it looks like:</para> -<literallayout remap='.nf'> -Function(<emphasis remap='I'>arguments</emphasis>) +<literallayout> +Function(<emphasis>arguments</emphasis>) </literallayout> <!-- .fi --> <para>and if you call something through a construction environment it looks like:</para> -<literallayout remap='.nf'> -env.Function(<emphasis remap='I'>arguments</emphasis>) +<literallayout> +env.Function(<emphasis>arguments</emphasis>) </literallayout> <!-- .fi --> <para>If you can call the functionality in both ways, then both forms are listed.</para> @@ -2712,7 +2662,7 @@ then both forms are listed.</para> import into an SConscript file by adding the following to the Python module:</para> -<literallayout remap='.nf'> +<literallayout> from SCons.Script import * </literallayout> <!-- .fi --> @@ -2728,7 +2678,7 @@ substitute construction variables into any supplied strings. For example:</para> -<literallayout remap='.nf'> +<literallayout> env = Environment(FOO = 'foo') Default('$FOO') env.Default('$FOO') @@ -2736,16 +2686,16 @@ env.Default('$FOO') <para>In the above example, the first call to the global -<emphasis remap='B'>Default()</emphasis> +<emphasis role="bold">Default()</emphasis> function will actually add a target named -<emphasis remap='B'>$FOO</emphasis> +<emphasis role="bold">$FOO</emphasis> to the list of default targets, while the second call to the -<emphasis remap='B'>env.Default()</emphasis> +<emphasis role="bold">env.Default()</emphasis> construction environment method will expand the value and add a target named -<emphasis remap='B'>foo</emphasis> +<emphasis role="bold">foo</emphasis> to the list of default targets. For more on construction variable expansion, see the next section on @@ -2798,37 +2748,37 @@ These variables may be accessed from custom Python modules that you import into an SConscript file by adding the following to the Python module:</para> -<literallayout remap='.nf'> +<literallayout> from SCons.Script import * </literallayout> <!-- .fi --> <!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" --> -<variablelist remap='TP'> +<variablelist> <varlistentry> <term>ARGLIST</term> <listitem> <para>A list -<emphasis remap='I'>keyword</emphasis>=<emphasis remap='I'>value</emphasis> +<emphasis>keyword</emphasis>=<emphasis>value</emphasis> arguments specified on the command line. Each element in the list is a tuple containing the -(<emphasis remap='I'>keyword</emphasis>,<emphasis remap='I'>value</emphasis>) +(<emphasis>keyword</emphasis>,<emphasis>value</emphasis>) of the argument. The separate -<emphasis remap='I'>keyword</emphasis> +<emphasis>keyword</emphasis> and -<emphasis remap='I'>value</emphasis> +<emphasis>value</emphasis> elements of the tuple can be accessed by subscripting for element -<emphasis remap='B'>[0]</emphasis> +<emphasis role="bold">[0]</emphasis> and -<emphasis remap='B'>[1]</emphasis> +<emphasis role="bold">[1]</emphasis> of the tuple, respectively.</para> <para>Example:</para> -<literallayout remap='.nf'> +<literallayout> print "first keyword, value =", ARGLIST[0][0], ARGLIST[0][1] print "second keyword, value =", ARGLIST[1][0], ARGLIST[1][1] third_tuple = ARGLIST[2] @@ -2844,7 +2794,7 @@ for key, value in ARGLIST: <term>ARGUMENTS</term> <listitem> <para>A dictionary of all the -<emphasis remap='I'>keyword</emphasis>=<emphasis remap='I'>value</emphasis> +<emphasis>keyword</emphasis>=<emphasis>value</emphasis> arguments specified on the command line. The dictionary is not in order, and if a given keyword has @@ -2852,12 +2802,12 @@ more than one value assigned to it on the command line, the last (right-most) value is the one in the -<emphasis remap='B'>ARGUMENTS</emphasis> +<emphasis role="bold">ARGUMENTS</emphasis> dictionary.</para> <para>Example:</para> -<literallayout remap='.nf'> +<literallayout> if ARGUMENTS.get('debug', 0): env = Environment(CCFLAGS = '-g') else: @@ -2875,30 +2825,30 @@ else: will actually try to build, regardless of whether they were specified on the command line or via the -<emphasis remap='B'>Default</emphasis>() +<emphasis role="bold">Default</emphasis>() function or method. The elements of this list may be strings -<emphasis remap='I'>or</emphasis> +<emphasis>or</emphasis> nodes, so you should run the list through the Python -<emphasis remap='B'>str</emphasis> +<emphasis role="bold">str</emphasis> function to make sure any Node path names are converted to strings.</para> <para>Because this list may be taken from the list of targets specified using the -<emphasis remap='B'>Default</emphasis>() +<emphasis role="bold">Default</emphasis>() function or method, the contents of the list may change on each successive call to -<emphasis remap='B'>Default</emphasis>(). +<emphasis role="bold">Default</emphasis>(). See the -<emphasis remap='B'>DEFAULT_TARGETS</emphasis> +<emphasis role="bold">DEFAULT_TARGETS</emphasis> list, below, for additional information.</para> <para>Example:</para> -<literallayout remap='.nf'> +<literallayout> if 'foo' in BUILD_TARGETS: print "Don't forget to test the `foo' program!" if 'special/program' in BUILD_TARGETS: @@ -2909,19 +2859,19 @@ if 'special/program' in BUILD_TARGETS: </variablelist> <para>Note that the -<emphasis remap='B'>BUILD_TARGETS</emphasis> +<emphasis role="bold">BUILD_TARGETS</emphasis> list only contains targets expected listed on the command line or via calls to the -<emphasis remap='B'>Default</emphasis>() +<emphasis role="bold">Default</emphasis>() function or method. It does -<emphasis remap='I'>not</emphasis> +<emphasis>not</emphasis> contain all dependent targets that will be built as a result of making the sure the explicitly-specified targets are up to date.</para> <!-- '\""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" --> -<variablelist remap='TP'> +<variablelist> <varlistentry> <term>COMMAND_LINE_TARGETS</term> <listitem> @@ -2936,7 +2886,7 @@ is explicitly being built.</para> <para>Example:</para> -<literallayout remap='.nf'> +<literallayout> if 'foo' in COMMAND_LINE_TARGETS: print "Don't forget to test the `foo' program!" if 'special/program' in COMMAND_LINE_TARGETS: @@ -2950,18 +2900,18 @@ if 'special/program' in COMMAND_LINE_TARGETS: <term>DEFAULT_TARGETS</term> <listitem> <para>A list of the target -<emphasis remap='I'>nodes</emphasis> +<emphasis>nodes</emphasis> that have been specified using the -<emphasis remap='B'>Default</emphasis>() +<emphasis role="bold">Default</emphasis>() function or method. The elements of the list are nodes, so you need to run them through the Python -<emphasis remap='B'>str</emphasis> +<emphasis role="bold">str</emphasis> function to get at the path name for each Node.</para> <para>Example:</para> -<literallayout remap='.nf'> +<literallayout> print str(DEFAULT_TARGETS[0]) if 'foo' in map(str, DEFAULT_TARGETS): print "Don't forget to test the `foo' program!" @@ -2971,12 +2921,12 @@ if 'foo' in map(str, DEFAULT_TARGETS): </variablelist> <para>The contents of the -<emphasis remap='B'>DEFAULT_TARGETS</emphasis> +<emphasis role="bold">DEFAULT_TARGETS</emphasis> list change on on each successive call to the -<emphasis remap='B'>Default</emphasis>() +<emphasis role="bold">Default</emphasis>() function:</para> -<literallayout remap='.nf'> +<literallayout> print map(str, DEFAULT_TARGETS) # originally [] Default('foo') print map(str, DEFAULT_TARGETS) # now a node ['foo'] @@ -2987,9 +2937,9 @@ print map(str, DEFAULT_TARGETS) # back to [] </literallayout> <!-- .fi --> <para>Consequently, be sure to use -<emphasis remap='B'>DEFAULT_TARGETS</emphasis> +<emphasis role="bold">DEFAULT_TARGETS</emphasis> only after you've made all of your -<emphasis remap='B'>Default</emphasis>() +<emphasis role="bold">Default</emphasis>() calls, or else simply be careful of the order of these statements in your SConscript files @@ -3016,7 +2966,7 @@ default target before it's actually been added to the list.</para> <!-- Default: --> <!-- (I dunno what this is ;\-) --> <para>A construction environment has an associated dictionary of -<emphasis remap='I'>construction variables</emphasis> +<emphasis>construction variables</emphasis> that are used by built-in or user-supplied build rules. Construction variables must follow the same rules for Python identifiers: @@ -3060,32 +3010,32 @@ defined construction variables:</para> <para>Construction variables can be retrieved and set using the -<emphasis remap='B'>Dictionary</emphasis> +<emphasis role="bold">Dictionary</emphasis> method of the construction environment:</para> -<literallayout remap='.nf'> +<literallayout> dict = env.Dictionary() dict["CC"] = "cc" </literallayout> <!-- .fi --> <para>or using the [] operator:</para> -<literallayout remap='.nf'> +<literallayout> env["CC"] = "cc" </literallayout> <!-- .fi --> <para>Construction variables can also be passed to the construction environment constructor:</para> -<literallayout remap='.nf'> +<literallayout> env = Environment(CC="cc") </literallayout> <!-- .fi --> <para>or when copying a construction environment using the -<emphasis remap='B'>Clone</emphasis> +<emphasis role="bold">Clone</emphasis> method:</para> -<literallayout remap='.nf'> +<literallayout> env2 = env.Clone(CC="cl.exe") </literallayout> <!-- .fi --> @@ -3095,7 +3045,7 @@ env2 = env.Clone(CC="cl.exe") <para><command>scons</command> supports -<emphasis remap='I'>configure contexts,</emphasis> +<emphasis>configure contexts,</emphasis> an integrated mechanism similar to the various AC_CHECK macros in GNU autoconf for testing for the existence of C header @@ -3110,41 +3060,41 @@ command line option.</para> <para>The following methods can be used to perform checks:</para> -<variablelist remap='TP'> +<variablelist> <varlistentry> - <term>Configure(<emphasis remap='I'>env</emphasis>, [<emphasis remap='I'>custom_tests</emphasis>, <emphasis remap='I'>conf_dir</emphasis>, <emphasis remap='I'>log_file</emphasis>, <emphasis remap='I'>config_h</emphasis>, <emphasis remap='I'>clean</emphasis>, <emphasis remap='I'>help])</emphasis></term> - <term>env.Configure([<emphasis remap='I'>custom_tests</emphasis>, <emphasis remap='I'>conf_dir</emphasis>, <emphasis remap='I'>log_file</emphasis>, <emphasis remap='I'>config_h</emphasis>, <emphasis remap='I'>clean</emphasis>, <emphasis remap='I'>help])</emphasis></term> + <term>Configure(<emphasis>env</emphasis>, [<emphasis>custom_tests</emphasis>, <emphasis>conf_dir</emphasis>, <emphasis>log_file</emphasis>, <emphasis>config_h</emphasis>, <emphasis>clean</emphasis>, <emphasis>help])</emphasis></term> + <term>env.Configure([<emphasis>custom_tests</emphasis>, <emphasis>conf_dir</emphasis>, <emphasis>log_file</emphasis>, <emphasis>config_h</emphasis>, <emphasis>clean</emphasis>, <emphasis>help])</emphasis></term> <listitem> <para>This creates a configure context, which can be used to perform checks. -<emphasis remap='I'>env</emphasis> +<emphasis>env</emphasis> specifies the environment for building the tests. This environment may be modified when performing checks. -<emphasis remap='I'>custom_tests</emphasis> +<emphasis>custom_tests</emphasis> is a dictionary containing custom tests. See also the section about custom tests below. By default, no custom tests are added to the configure context. -<emphasis remap='I'>conf_dir</emphasis> +<emphasis>conf_dir</emphasis> specifies a directory where the test cases are built. Note that this directory is not used for building normal targets. The default value is the directory #/.sconf_temp. -<emphasis remap='I'>log_file</emphasis> +<emphasis>log_file</emphasis> specifies a file which collects the output from commands that are executed to check for the existence of header files, libraries, etc. The default is the file #/config.log. If you are using the -<emphasis remap='B'>VariantDir</emphasis>() +<emphasis role="bold">VariantDir</emphasis>() method, you may want to specify a subdirectory under your variant directory. -<emphasis remap='I'>config_h</emphasis> +<emphasis>config_h</emphasis> specifies a C header file where the results of tests will be written, e.g. #define HAVE_STDIO_H, #define HAVE_LIBM, etc. The default is to not write a -<emphasis remap='B'>config.h</emphasis> +<emphasis role="bold">config.h</emphasis> file. You can specify the same -<emphasis remap='B'>config.h</emphasis> +<emphasis role="bold">config.h</emphasis> file in multiple calls to Configure, in which case <command>scons</command> @@ -3153,19 +3103,19 @@ Note that SCons uses its normal dependency checking to decide if it's necessary to rebuild the specified -<emphasis remap='I'>config_h</emphasis> +<emphasis>config_h</emphasis> file. This means that the file is not necessarily re-built each time scons is run, but is only rebuilt if its contents will have changed and some target that depends on the -<emphasis remap='I'>config_h</emphasis> +<emphasis>config_h</emphasis> file is being built.</para> <para>The optional -<emphasis remap='B'>clean</emphasis> +<emphasis role="bold">clean</emphasis> and -<emphasis remap='B'>help</emphasis> +<emphasis role="bold">help</emphasis> arguments can be used to suppress execution of the configuration tests when the <option>-c/--clean</option> @@ -3179,9 +3129,9 @@ affect the list of targets to be cleaned or the help text. If the configure tests do not affect these, then you may add the -<emphasis remap='B'>clean=False</emphasis> +<emphasis role="bold">clean=False</emphasis> or -<emphasis remap='B'>help=False</emphasis> +<emphasis role="bold">help=False</emphasis> arguments (or both) to avoid unnecessary test execution.</para> @@ -3190,13 +3140,13 @@ to avoid unnecessary test execution.</para> </varlistentry> </variablelist> <para>A created -<emphasis remap='B'>Configure</emphasis> +<emphasis role="bold">Configure</emphasis> instance has the following associated methods:</para> -<variablelist remap='TP'> +<variablelist> <varlistentry> - <term>SConf.Finish(<emphasis remap='I'>context</emphasis>)</term> - <term><emphasis remap='I'>sconf</emphasis>.Finish()</term> + <term>SConf.Finish(<emphasis>context</emphasis>)</term> + <term><emphasis>sconf</emphasis>.Finish()</term> <listitem> <para>This method should be called after configuration is done. It returns the environment as modified @@ -3215,58 +3165,58 @@ goes by and developers contribute new useful tests.)</para> </listitem> </varlistentry> <varlistentry> - <term>SConf.CheckHeader(<emphasis remap='I'>context</emphasis>, <emphasis remap='I'>header</emphasis>, [<emphasis remap='I'>include_quotes</emphasis>, <emphasis remap='I'>language</emphasis>])</term> - <term><emphasis remap='I'>sconf</emphasis>.CheckHeader(<emphasis remap='I'>header</emphasis>, [<emphasis remap='I'>include_quotes</emphasis>, <emphasis remap='I'>language</emphasis>])</term> + <term>SConf.CheckHeader(<emphasis>context</emphasis>, <emphasis>header</emphasis>, [<emphasis>include_quotes</emphasis>, <emphasis>language</emphasis>])</term> + <term><emphasis>sconf</emphasis>.CheckHeader(<emphasis>header</emphasis>, [<emphasis>include_quotes</emphasis>, <emphasis>language</emphasis>])</term> <listitem> <para>Checks if -<emphasis remap='I'>header</emphasis> +<emphasis>header</emphasis> is usable in the specified language. -<emphasis remap='I'>header</emphasis> +<emphasis>header</emphasis> may be a list, in which case the last item in the list is the header file to be checked, and the previous list items are header files whose -<emphasis remap='B'>#include</emphasis> +<emphasis role="bold">#include</emphasis> lines should precede the header line being checked for. The optional argument -<emphasis remap='I'>include_quotes</emphasis> +<emphasis>include_quotes</emphasis> must be a two character string, where the first character denotes the opening quote and the second character denotes the closing quote. By default, both characters are " (double quote). The optional argument -<emphasis remap='I'>language</emphasis> +<emphasis>language</emphasis> should be either -<emphasis remap='B'>C</emphasis> +<emphasis role="bold">C</emphasis> or -<emphasis remap='B'>C++</emphasis> +<emphasis role="bold">C++</emphasis> and selects the compiler to be used for the check. Returns 1 on success and 0 on failure.</para> </listitem> </varlistentry> <varlistentry> - <term>SConf.CheckCHeader(<emphasis remap='I'>context</emphasis>, <emphasis remap='I'>header</emphasis>, [<emphasis remap='I'>include_quotes</emphasis>])</term> - <term><emphasis remap='I'>sconf</emphasis>.CheckCHeader(<emphasis remap='I'>header</emphasis>, [<emphasis remap='I'>include_quotes</emphasis>])</term> + <term>SConf.CheckCHeader(<emphasis>context</emphasis>, <emphasis>header</emphasis>, [<emphasis>include_quotes</emphasis>])</term> + <term><emphasis>sconf</emphasis>.CheckCHeader(<emphasis>header</emphasis>, [<emphasis>include_quotes</emphasis>])</term> <listitem> <para>This is a wrapper around -<emphasis remap='B'>SConf.CheckHeader</emphasis> +<emphasis role="bold">SConf.CheckHeader</emphasis> which checks if -<emphasis remap='I'>header</emphasis> +<emphasis>header</emphasis> is usable in the C language. -<emphasis remap='I'>header</emphasis> +<emphasis>header</emphasis> may be a list, in which case the last item in the list is the header file to be checked, and the previous list items are header files whose -<emphasis remap='B'>#include</emphasis> +<emphasis role="bold">#include</emphasis> lines should precede the header line being checked for. The optional argument -<emphasis remap='I'>include_quotes</emphasis> +<emphasis>include_quotes</emphasis> must be a two character string, where the first character denotes the opening quote and the second character denotes the closing quote (both default @@ -3276,25 +3226,25 @@ Returns 1 on success and 0 on failure.</para> </listitem> </varlistentry> <varlistentry> - <term>SConf.CheckCXXHeader(<emphasis remap='I'>context</emphasis>, <emphasis remap='I'>header</emphasis>, [<emphasis remap='I'>include_quotes</emphasis>])</term> - <term><emphasis remap='I'>sconf</emphasis>.CheckCXXHeader(<emphasis remap='I'>header</emphasis>, [<emphasis remap='I'>include_quotes</emphasis>])</term> + <term>SConf.CheckCXXHeader(<emphasis>context</emphasis>, <emphasis>header</emphasis>, [<emphasis>include_quotes</emphasis>])</term> + <term><emphasis>sconf</emphasis>.CheckCXXHeader(<emphasis>header</emphasis>, [<emphasis>include_quotes</emphasis>])</term> <listitem> <para>This is a wrapper around -<emphasis remap='B'>SConf.CheckHeader</emphasis> +<emphasis role="bold">SConf.CheckHeader</emphasis> which checks if -<emphasis remap='I'>header</emphasis> +<emphasis>header</emphasis> is usable in the C++ language. -<emphasis remap='I'>header</emphasis> +<emphasis>header</emphasis> may be a list, in which case the last item in the list is the header file to be checked, and the previous list items are header files whose -<emphasis remap='B'>#include</emphasis> +<emphasis role="bold">#include</emphasis> lines should precede the header line being checked for. The optional argument -<emphasis remap='I'>include_quotes</emphasis> +<emphasis>include_quotes</emphasis> must be a two character string, where the first character denotes the opening quote and the second character denotes the closing quote (both default @@ -3304,15 +3254,15 @@ Returns 1 on success and 0 on failure.</para> </listitem> </varlistentry> <varlistentry> - <term>SConf.CheckFunc(<emphasis remap='I'>context,</emphasis>, <emphasis remap='I'>function_name</emphasis>, [<emphasis remap='I'>header</emphasis>, <emphasis remap='I'>language</emphasis>])</term> - <term><emphasis remap='I'>sconf</emphasis>.CheckFunc(<emphasis remap='I'>function_name</emphasis>, [<emphasis remap='I'>header</emphasis>, <emphasis remap='I'>language</emphasis>])</term> + <term>SConf.CheckFunc(<emphasis>context,</emphasis>, <emphasis>function_name</emphasis>, [<emphasis>header</emphasis>, <emphasis>language</emphasis>])</term> + <term><emphasis>sconf</emphasis>.CheckFunc(<emphasis>function_name</emphasis>, [<emphasis>header</emphasis>, <emphasis>language</emphasis>])</term> <listitem> <para>Checks if the specified C or C++ function is available. -<emphasis remap='I'>function_name</emphasis> +<emphasis>function_name</emphasis> is the name of the function to check for. The optional -<emphasis remap='I'>header</emphasis> +<emphasis>header</emphasis> argument is a string that will be placed at the top @@ -3320,137 +3270,137 @@ of the test file that will be compiled to check if the function exists; the default is:</para> -<literallayout remap='.nf'> +<literallayout> #ifdef __cplusplus extern "C" #endif char function_name(); </literallayout> <!-- .fi --> <para>The optional -<emphasis remap='I'>language</emphasis> +<emphasis>language</emphasis> argument should be -<emphasis remap='B'>C</emphasis> +<emphasis role="bold">C</emphasis> or -<emphasis remap='B'>C++</emphasis> +<emphasis role="bold">C++</emphasis> and selects the compiler to be used for the check; the default is "C".</para> </listitem> </varlistentry> <varlistentry> - <term>SConf.CheckLib(<emphasis remap='I'>context</emphasis>, [<emphasis remap='I'>library</emphasis>, <emphasis remap='I'>symbol</emphasis>, <emphasis remap='I'>header</emphasis>, <emphasis remap='I'>language</emphasis>, <emphasis remap='I'>autoadd=1</emphasis>])</term> - <term><emphasis remap='I'>sconf</emphasis>.CheckLib([<emphasis remap='I'>library</emphasis>, <emphasis remap='I'>symbol</emphasis>, <emphasis remap='I'>header</emphasis>, <emphasis remap='I'>language</emphasis>, <emphasis remap='I'>autoadd=1</emphasis>])</term> + <term>SConf.CheckLib(<emphasis>context</emphasis>, [<emphasis>library</emphasis>, <emphasis>symbol</emphasis>, <emphasis>header</emphasis>, <emphasis>language</emphasis>, <emphasis>autoadd=1</emphasis>])</term> + <term><emphasis>sconf</emphasis>.CheckLib([<emphasis>library</emphasis>, <emphasis>symbol</emphasis>, <emphasis>header</emphasis>, <emphasis>language</emphasis>, <emphasis>autoadd=1</emphasis>])</term> <listitem> <para>Checks if -<emphasis remap='I'>library</emphasis> +<emphasis>library</emphasis> provides -<emphasis remap='I'>symbol</emphasis>. +<emphasis>symbol</emphasis>. If the value of -<emphasis remap='I'>autoadd</emphasis> +<emphasis>autoadd</emphasis> is 1 and the library provides the specified -<emphasis remap='I'>symbol</emphasis>, +<emphasis>symbol</emphasis>, appends the library to the LIBS construction environment variable. -<emphasis remap='I'>library</emphasis> +<emphasis>library</emphasis> may also be None (the default), in which case -<emphasis remap='I'>symbol</emphasis> +<emphasis>symbol</emphasis> is checked with the current LIBS variable, or a list of library names, in which case each library in the list will be checked for -<emphasis remap='I'>symbol</emphasis>. +<emphasis>symbol</emphasis>. If -<emphasis remap='I'>symbol</emphasis> +<emphasis>symbol</emphasis> is not set or is -<emphasis remap='B'>None</emphasis>, +<emphasis role="bold">None</emphasis>, then -<emphasis remap='B'>SConf.CheckLib</emphasis>() +<emphasis role="bold">SConf.CheckLib</emphasis>() just checks if you can link against the specified -<emphasis remap='I'>library</emphasis>. +<emphasis>library</emphasis>. The optional -<emphasis remap='I'>language</emphasis> +<emphasis>language</emphasis> argument should be -<emphasis remap='B'>C</emphasis> +<emphasis role="bold">C</emphasis> or -<emphasis remap='B'>C++</emphasis> +<emphasis role="bold">C++</emphasis> and selects the compiler to be used for the check; the default is "C". The default value for -<emphasis remap='I'>autoadd</emphasis> +<emphasis>autoadd</emphasis> is 1. This method returns 1 on success and 0 on error.</para> </listitem> </varlistentry> <varlistentry> - <term>SConf.CheckLibWithHeader(<emphasis remap='I'>context</emphasis>, <emphasis remap='I'>library</emphasis>, <emphasis remap='I'>header</emphasis>, <emphasis remap='I'>language</emphasis>, [<emphasis remap='I'>call</emphasis>, <emphasis remap='I'>autoadd</emphasis>])</term> - <term><emphasis remap='I'>sconf</emphasis>.CheckLibWithHeader(<emphasis remap='I'>library</emphasis>, <emphasis remap='I'>header</emphasis>, <emphasis remap='I'>language</emphasis>, [<emphasis remap='I'>call</emphasis>, <emphasis remap='I'>autoadd</emphasis>])</term> + <term>SConf.CheckLibWithHeader(<emphasis>context</emphasis>, <emphasis>library</emphasis>, <emphasis>header</emphasis>, <emphasis>language</emphasis>, [<emphasis>call</emphasis>, <emphasis>autoadd</emphasis>])</term> + <term><emphasis>sconf</emphasis>.CheckLibWithHeader(<emphasis>library</emphasis>, <emphasis>header</emphasis>, <emphasis>language</emphasis>, [<emphasis>call</emphasis>, <emphasis>autoadd</emphasis>])</term> <listitem> <para>In contrast to the SConf.CheckLib call, this call provides a more sophisticated way to check against libraries. Again, -<emphasis remap='I'>library</emphasis> +<emphasis>library</emphasis> specifies the library or a list of libraries to check. -<emphasis remap='I'>header</emphasis> +<emphasis>header</emphasis> specifies a header to check for. -<emphasis remap='I'>header</emphasis> +<emphasis>header</emphasis> may be a list, in which case the last item in the list is the header file to be checked, and the previous list items are header files whose -<emphasis remap='B'>#include</emphasis> +<emphasis role="bold">#include</emphasis> lines should precede the header line being checked for. -<emphasis remap='I'>language</emphasis> +<emphasis>language</emphasis> may be one of 'C','c','CXX','cxx','C++' and 'c++'. -<emphasis remap='I'>call</emphasis> +<emphasis>call</emphasis> can be any valid expression (with a trailing ';'). If -<emphasis remap='I'>call</emphasis> +<emphasis>call</emphasis> is not set, the default simply checks that you can link against the specified -<emphasis remap='I'>library</emphasis>. -<emphasis remap='I'>autoadd</emphasis> +<emphasis>library</emphasis>. +<emphasis>autoadd</emphasis> specifies whether to add the library to the environment (only if the check succeeds). This method returns 1 on success and 0 on error.</para> </listitem> </varlistentry> <varlistentry> - <term>SConf.CheckType(<emphasis remap='I'>context</emphasis>, <emphasis remap='I'>type_name</emphasis>, [<emphasis remap='I'>includes</emphasis>, <emphasis remap='I'>language</emphasis>])</term> - <term><emphasis remap='I'>sconf</emphasis>.CheckType(<emphasis remap='I'>type_name</emphasis>, [<emphasis remap='I'>includes</emphasis>, <emphasis remap='I'>language</emphasis>])</term> + <term>SConf.CheckType(<emphasis>context</emphasis>, <emphasis>type_name</emphasis>, [<emphasis>includes</emphasis>, <emphasis>language</emphasis>])</term> + <term><emphasis>sconf</emphasis>.CheckType(<emphasis>type_name</emphasis>, [<emphasis>includes</emphasis>, <emphasis>language</emphasis>])</term> <listitem> <para>Checks for the existence of a type defined by -<emphasis remap='B'>typedef</emphasis>. -<emphasis remap='I'>type_name</emphasis> +<emphasis role="bold">typedef</emphasis>. +<emphasis>type_name</emphasis> specifies the typedef name to check for. -<emphasis remap='I'>includes</emphasis> +<emphasis>includes</emphasis> is a string containing one or more -<emphasis remap='B'>#include</emphasis> +<emphasis role="bold">#include</emphasis> lines that will be inserted into the program that will be run to test for the existence of the type. The optional -<emphasis remap='I'>language</emphasis> +<emphasis>language</emphasis> argument should be -<emphasis remap='B'>C</emphasis> +<emphasis role="bold">C</emphasis> or -<emphasis remap='B'>C++</emphasis> +<emphasis role="bold">C++</emphasis> and selects the compiler to be used for the check; the default is "C". Example:</para> -<literallayout remap='.nf'> +<literallayout> sconf.CheckType('foo_type', '#include "my_types.h"', 'C++') </literallayout> <!-- .fi --> </listitem> </varlistentry> <varlistentry> - <term>Configure.CheckCC(<emphasis remap='I'>self</emphasis>)</term> + <term>Configure.CheckCC(<emphasis>self</emphasis>)</term> <listitem> <para>Checks whether the C compiler (as defined by the CC construction variable) works by trying to compile a small source file.</para> @@ -3465,7 +3415,7 @@ not.</para> </listitem> </varlistentry> <varlistentry> - <term>Configure.CheckCXX(<emphasis remap='I'>self</emphasis>)</term> + <term>Configure.CheckCXX(<emphasis>self</emphasis>)</term> <listitem> <para>Checks whether the C++ compiler (as defined by the CXX construction variable) works by trying to compile a small source file. By default, SCons only detects @@ -3478,7 +3428,7 @@ works or not.</para> </listitem> </varlistentry> <varlistentry> - <term>Configure.CheckSHCC(<emphasis remap='I'>self</emphasis>)</term> + <term>Configure.CheckSHCC(<emphasis>self</emphasis>)</term> <listitem> <para>Checks whether the C compiler (as defined by the SHCC construction variable) works by trying to compile a small source file. By default, SCons only detects if @@ -3492,7 +3442,7 @@ library, only that the compilation (not link) succeeds.</para> </listitem> </varlistentry> <varlistentry> - <term>Configure.CheckSHCXX(<emphasis remap='I'>self</emphasis>)</term> + <term>Configure.CheckSHCXX(<emphasis>self</emphasis>)</term> <listitem> <para>Checks whether the C++ compiler (as defined by the SHCXX construction variable) works by trying to compile a small source file. By default, SCons only detects @@ -3508,7 +3458,7 @@ a shared library, only that the compilation (not link) succeeds.</para> </variablelist> <para>Example of a typical Configure usage:</para> -<literallayout remap='.nf'> +<literallayout> env = Environment() conf = Configure( env ) if not conf.CheckCHeader( 'math.h' ): @@ -3521,17 +3471,17 @@ if conf.CheckLibWithHeader( 'qt', 'qapp.h', 'c++', env = conf.Finish() </literallayout> <!-- .fi --> -<variablelist remap='TP'> +<variablelist> <varlistentry> - <term>SConf.CheckTypeSize(<emphasis remap='I'>context</emphasis>, <emphasis remap='I'>type_name</emphasis>, [<emphasis remap='I'>header</emphasis>, <emphasis remap='I'>language</emphasis>, <emphasis remap='I'>expect</emphasis>])</term> - <term><emphasis remap='I'>sconf</emphasis>.CheckTypeSize(<emphasis remap='I'>type_name</emphasis>, [<emphasis remap='I'>header</emphasis>, <emphasis remap='I'>language</emphasis>, <emphasis remap='I'>expect</emphasis>])</term> + <term>SConf.CheckTypeSize(<emphasis>context</emphasis>, <emphasis>type_name</emphasis>, [<emphasis>header</emphasis>, <emphasis>language</emphasis>, <emphasis>expect</emphasis>])</term> + <term><emphasis>sconf</emphasis>.CheckTypeSize(<emphasis>type_name</emphasis>, [<emphasis>header</emphasis>, <emphasis>language</emphasis>, <emphasis>expect</emphasis>])</term> <listitem> <para>Checks for the size of a type defined by -<emphasis remap='B'>typedef</emphasis>. -<emphasis remap='I'>type_name</emphasis> +<emphasis role="bold">typedef</emphasis>. +<emphasis>type_name</emphasis> specifies the typedef name to check for. The optional -<emphasis remap='I'>header</emphasis> +<emphasis>header</emphasis> argument is a string that will be placed at the top @@ -3540,64 +3490,64 @@ that will be compiled to check if the function exists; the default is empty. The optional -<emphasis remap='I'>language</emphasis> +<emphasis>language</emphasis> argument should be -<emphasis remap='B'>C</emphasis> +<emphasis role="bold">C</emphasis> or -<emphasis remap='B'>C++</emphasis> +<emphasis role="bold">C++</emphasis> and selects the compiler to be used for the check; the default is "C". The optional -<emphasis remap='I'>expect</emphasis> +<emphasis>expect</emphasis> argument should be an integer. If this argument is used, the function will only check whether the type given in type_name has the expected size (in bytes). For example, -<emphasis remap='B'>CheckTypeSize('short', expect = 2)</emphasis> +<emphasis role="bold">CheckTypeSize('short', expect = 2)</emphasis> will return success only if short is two bytes.</para> -<literallayout remap='.nf'> +<literallayout> </literallayout> <!-- .fi --> </listitem> </varlistentry> <varlistentry> - <term>SConf.CheckDeclaration(<emphasis remap='I'>context</emphasis>, <emphasis remap='I'>symbol</emphasis>, [<emphasis remap='I'>includes</emphasis>, <emphasis remap='I'>language</emphasis>])</term> - <term><emphasis remap='I'>sconf</emphasis>.CheckDeclaration(<emphasis remap='I'>symbol</emphasis>, [<emphasis remap='I'>includes</emphasis>, <emphasis remap='I'>language</emphasis>])</term> + <term>SConf.CheckDeclaration(<emphasis>context</emphasis>, <emphasis>symbol</emphasis>, [<emphasis>includes</emphasis>, <emphasis>language</emphasis>])</term> + <term><emphasis>sconf</emphasis>.CheckDeclaration(<emphasis>symbol</emphasis>, [<emphasis>includes</emphasis>, <emphasis>language</emphasis>])</term> <listitem> <para>Checks if the specified -<emphasis remap='I'>symbol</emphasis> +<emphasis>symbol</emphasis> is declared. -<emphasis remap='I'>includes</emphasis> +<emphasis>includes</emphasis> is a string containing one or more -<emphasis remap='B'>#include</emphasis> +<emphasis role="bold">#include</emphasis> lines that will be inserted into the program that will be run to test for the existence of the type. The optional -<emphasis remap='I'>language</emphasis> +<emphasis>language</emphasis> argument should be -<emphasis remap='B'>C</emphasis> +<emphasis role="bold">C</emphasis> or -<emphasis remap='B'>C++</emphasis> +<emphasis role="bold">C++</emphasis> and selects the compiler to be used for the check; the default is "C".</para> </listitem> </varlistentry> <varlistentry> - <term>SConf.Define(<emphasis remap='I'>context</emphasis>, <emphasis remap='I'>symbol</emphasis>, [<emphasis remap='I'>value</emphasis>, <emphasis remap='I'>comment</emphasis>])</term> - <term><emphasis remap='I'>sconf</emphasis>.Define(<emphasis remap='I'>symbol</emphasis>, [<emphasis remap='I'>value</emphasis>, <emphasis remap='I'>comment</emphasis>])</term> + <term>SConf.Define(<emphasis>context</emphasis>, <emphasis>symbol</emphasis>, [<emphasis>value</emphasis>, <emphasis>comment</emphasis>])</term> + <term><emphasis>sconf</emphasis>.Define(<emphasis>symbol</emphasis>, [<emphasis>value</emphasis>, <emphasis>comment</emphasis>])</term> <listitem> <para>This function does not check for anything, but defines a preprocessor symbol that will be added to the configuration header file. It is the equivalent of AC_DEFINE, and defines the symbol -<emphasis remap='I'>name</emphasis> +<emphasis>name</emphasis> with the optional -<emphasis remap='B'>value</emphasis> +<emphasis role="bold">value</emphasis> and the optional comment -<emphasis remap='B'>comment</emphasis>.</para> +<emphasis role="bold">comment</emphasis>.</para> </listitem> </varlistentry> @@ -3605,7 +3555,7 @@ and the optional comment <para>Examples:</para> -<programlisting remap='.nf'> +<programlisting> env = Environment() conf = Configure( env ) @@ -3621,7 +3571,7 @@ conf.Define('A_SYMBOL', 1) <para>Be careful about quoting string values, though:</para> -<programlisting remap='.nf'> +<programlisting> env = Environment() conf = Configure( env ) @@ -3637,7 +3587,7 @@ conf.Define('A_SYMBOL', '"YA"') <para>For comment:</para> -<programlisting remap='.nf'> +<programlisting> env = Environment() conf = Configure( env ) @@ -3653,31 +3603,31 @@ These are passed in a dictionary to the Configure function. This dictionary maps the names of the checks to user defined Python callables (either Python functions or class instances implementing the -<emphasis remap='I'>__call__</emphasis> +<emphasis>__call__</emphasis> method). The first argument of the call is always a -<emphasis remap='I'>CheckContext</emphasis> +<emphasis>CheckContext</emphasis> instance followed by the arguments, which must be supplied by the user of the check. These CheckContext instances define the following methods:</para> -<variablelist remap='TP'> +<variablelist> <varlistentry> - <term>CheckContext.Message(<emphasis remap='I'>self</emphasis>, <emphasis remap='I'>text</emphasis>)</term> + <term>CheckContext.Message(<emphasis>self</emphasis>, <emphasis>text</emphasis>)</term> <listitem> <para>Usually called before the check is started. -<emphasis remap='I'>text</emphasis> +<emphasis>text</emphasis> will be displayed to the user, e.g. 'Checking for library X...'</para> </listitem> </varlistentry> <varlistentry> - <term>CheckContext.Result(<emphasis remap='I'>self,</emphasis>, <emphasis remap='I'>res</emphasis>)</term> + <term>CheckContext.Result(<emphasis>self,</emphasis>, <emphasis>res</emphasis>)</term> <listitem> <para>Usually called after the check is done. -<emphasis remap='I'>res</emphasis> +<emphasis>res</emphasis> can be either an integer or a string. In the former case, 'yes' (res != 0) or 'no' (res == 0) is displayed to the user, in the latter case the given string is displayed.</para> @@ -3685,47 +3635,47 @@ given string is displayed.</para> </listitem> </varlistentry> <varlistentry> - <term>CheckContext.TryCompile(<emphasis remap='I'>self</emphasis>, <emphasis remap='I'>text</emphasis>, <emphasis remap='I'>extension</emphasis>)</term> + <term>CheckContext.TryCompile(<emphasis>self</emphasis>, <emphasis>text</emphasis>, <emphasis>extension</emphasis>)</term> <listitem> <para>Checks if a file with the specified -<emphasis remap='I'>extension</emphasis> +<emphasis>extension</emphasis> (e.g. '.c') containing -<emphasis remap='I'>text</emphasis> +<emphasis>text</emphasis> can be compiled using the environment's -<emphasis remap='B'>Object</emphasis> +<emphasis role="bold">Object</emphasis> builder. Returns 1 on success and 0 on failure.</para> </listitem> </varlistentry> <varlistentry> - <term>CheckContext.TryLink(<emphasis remap='I'>self</emphasis>, <emphasis remap='I'>text</emphasis>, <emphasis remap='I'>extension</emphasis>)</term> + <term>CheckContext.TryLink(<emphasis>self</emphasis>, <emphasis>text</emphasis>, <emphasis>extension</emphasis>)</term> <listitem> <para>Checks, if a file with the specified -<emphasis remap='I'>extension</emphasis> +<emphasis>extension</emphasis> (e.g. '.c') containing -<emphasis remap='I'>text</emphasis> +<emphasis>text</emphasis> can be compiled using the environment's -<emphasis remap='B'>Program</emphasis> +<emphasis role="bold">Program</emphasis> builder. Returns 1 on success and 0 on failure.</para> </listitem> </varlistentry> <varlistentry> - <term>CheckContext.TryRun(<emphasis remap='I'>self</emphasis>, <emphasis remap='I'>text</emphasis>, <emphasis remap='I'>extension</emphasis>)</term> + <term>CheckContext.TryRun(<emphasis>self</emphasis>, <emphasis>text</emphasis>, <emphasis>extension</emphasis>)</term> <listitem> <para>Checks, if a file with the specified -<emphasis remap='I'>extension</emphasis> +<emphasis>extension</emphasis> (e.g. '.c') containing -<emphasis remap='I'>text</emphasis> +<emphasis>text</emphasis> can be compiled using the environment's -<emphasis remap='B'>Program</emphasis> +<emphasis role="bold">Program</emphasis> builder. On success, the program is run. If the program executes successfully (that is, its return status is 0), a tuple -<emphasis remap='I'>(1, outputStr)</emphasis> +<emphasis>(1, outputStr)</emphasis> is returned, where -<emphasis remap='I'>outputStr</emphasis> +<emphasis>outputStr</emphasis> is the standard output of the program. If the program fails execution @@ -3735,44 +3685,44 @@ then (0, '') is returned.</para> </listitem> </varlistentry> <varlistentry> - <term>CheckContext.TryAction(<emphasis remap='I'>self</emphasis>, <emphasis remap='I'>action</emphasis>, [<emphasis remap='I'>text</emphasis>, <emphasis remap='I'>extension</emphasis>])</term> + <term>CheckContext.TryAction(<emphasis>self</emphasis>, <emphasis>action</emphasis>, [<emphasis>text</emphasis>, <emphasis>extension</emphasis>])</term> <listitem> <para>Checks if the specified -<emphasis remap='I'>action</emphasis> +<emphasis>action</emphasis> with an optional source file (contents -<emphasis remap='I'>text</emphasis> +<emphasis>text</emphasis> , extension -<emphasis remap='I'>extension</emphasis> +<emphasis>extension</emphasis> = '' ) can be executed. -<emphasis remap='I'>action</emphasis> +<emphasis>action</emphasis> may be anything which can be converted to a <command>scons</command> Action. On success, -<emphasis remap='I'>(1, outputStr)</emphasis> +<emphasis>(1, outputStr)</emphasis> is returned, where -<emphasis remap='I'>outputStr</emphasis> +<emphasis>outputStr</emphasis> is the content of the target file. On failure -<emphasis remap='I'>(0, '')</emphasis> +<emphasis>(0, '')</emphasis> is returned.</para> </listitem> </varlistentry> <varlistentry> - <term>CheckContext.TryBuild(<emphasis remap='I'>self</emphasis>, <emphasis remap='I'>builder</emphasis>, [<emphasis remap='I'>text</emphasis>, <emphasis remap='I'>extension</emphasis>])</term> + <term>CheckContext.TryBuild(<emphasis>self</emphasis>, <emphasis>builder</emphasis>, [<emphasis>text</emphasis>, <emphasis>extension</emphasis>])</term> <listitem> <para>Low level implementation for testing specific builds; the methods above are based on this method. Given the Builder instance -<emphasis remap='I'>builder</emphasis> +<emphasis>builder</emphasis> and the optional -<emphasis remap='I'>text</emphasis> +<emphasis>text</emphasis> of a source file with optional -<emphasis remap='I'>extension</emphasis>, +<emphasis>extension</emphasis>, this method returns 1 on success and 0 on failure. In addition, -<emphasis remap='I'>self.lastTarget</emphasis> +<emphasis>self.lastTarget</emphasis> is set to the build target node, if the build was successful.</para> </listitem> @@ -3780,7 +3730,7 @@ is set to the build target node, if the build was successful.</para> </variablelist> <para>Example for implementing and using custom tests:</para> -<programlisting remap='.nf'> +<programlisting> def CheckQt(context, qtdir): context.Message( 'Checking for qt ...' ) lastLIBS = context.env['LIBS'] @@ -3818,39 +3768,39 @@ locations, or site-specific compiler options may need to be passed to the compiler. <command>scons</command> provides a -<emphasis remap='B'>Variables</emphasis> +<emphasis role="bold">Variables</emphasis> object to support overriding construction variables on the command line:</para> -<literallayout remap='.nf'> +<literallayout> $ scons VARIABLE=foo </literallayout> <!-- .fi --> <para>The variable values can also be specified in a text-based SConscript file. To create a Variables object, call the Variables() function:</para> -<variablelist remap='TP'> +<variablelist> <varlistentry> - <term>Variables([<emphasis remap='I'>files</emphasis>], [<emphasis remap='I'>args</emphasis>])</term> + <term>Variables([<emphasis>files</emphasis>], [<emphasis>args</emphasis>])</term> <listitem> <para>This creates a Variables object that will read construction variables from the file or list of filenames specified in -<emphasis remap='I'>files</emphasis>. +<emphasis>files</emphasis>. If no files are specified, or the -<emphasis remap='I'>files</emphasis> +<emphasis>files</emphasis> argument is -<emphasis remap='B'>None</emphasis>, +<emphasis role="bold">None</emphasis>, then no files will be read. The optional argument -<emphasis remap='I'>args</emphasis> +<emphasis>args</emphasis> is a dictionary of values that will override anything read from the specified files; it is primarily intended to be passed the -<emphasis remap='B'>ARGUMENTS</emphasis> +<emphasis role="bold">ARGUMENTS</emphasis> dictionary that holds variables specified on the command line. Example:</para> -<literallayout remap='.nf'> +<literallayout> vars = Variables('custom.py') vars = Variables('overrides.py', ARGUMENTS) vars = Variables(None, {FOO:'expansion', BAR:7}) @@ -3861,41 +3811,41 @@ vars = Variables(None, {FOO:'expansion', BAR:7}) </listitem> </varlistentry> <varlistentry> - <term>Add(<emphasis remap='I'>key</emphasis>, [<emphasis remap='I'>help</emphasis>, <emphasis remap='I'>default</emphasis>, <emphasis remap='I'>validator</emphasis>, <emphasis remap='I'>converter</emphasis>])</term> + <term>Add(<emphasis>key</emphasis>, [<emphasis>help</emphasis>, <emphasis>default</emphasis>, <emphasis>validator</emphasis>, <emphasis>converter</emphasis>])</term> <listitem> <para>This adds a customizable construction variable to the Variables object. -<emphasis remap='I'>key</emphasis> +<emphasis>key</emphasis> is the name of the variable. -<emphasis remap='I'>help</emphasis> +<emphasis>help</emphasis> is the help text for the variable. -<emphasis remap='I'>default</emphasis> +<emphasis>default</emphasis> is the default value of the variable; if the default value is -<emphasis remap='B'>None</emphasis> +<emphasis role="bold">None</emphasis> and there is no explicit value specified, the construction variable will -<emphasis remap='I'>not</emphasis> +<emphasis>not</emphasis> be added to the construction environment. -<emphasis remap='I'>validator</emphasis> +<emphasis>validator</emphasis> is called to validate the value of the variable, and should take three arguments: key, value, and environment. The recommended way to handle an invalid value is to raise an exception (see example below). -<emphasis remap='I'>converter</emphasis> +<emphasis>converter</emphasis> is called to convert the value before putting it in the environment, and should take either a value, or the value and environment, as parameters. The -<emphasis remap='I'>converter</emphasis> +<emphasis>converter</emphasis> must return a value, which will be converted into a string before being validated by the -<emphasis remap='I'>validator</emphasis> +<emphasis>validator</emphasis> (if any) and then added to the environment.</para> <para>Examples:</para> -<programlisting remap='.nf'> +<programlisting> vars.Add('CC', 'The C compiler') def validate_color(key, val, env): @@ -3907,19 +3857,19 @@ vars.Add('COLOR', validator=valid_color) </listitem> </varlistentry> <varlistentry> - <term>AddVariables(<emphasis remap='I'>list</emphasis>)</term> + <term>AddVariables(<emphasis>list</emphasis>)</term> <listitem> <para>A wrapper script that adds multiple customizable construction variables to a Variables object. -<emphasis remap='I'>list</emphasis> +<emphasis>list</emphasis> is a list of tuple or list objects that contain the arguments for an individual call to the -<emphasis remap='B'>Add</emphasis> +<emphasis role="bold">Add</emphasis> method.</para> -<literallayout remap='.nf'> +<literallayout> opt.AddVariables( ('debug', '', 0), ('CC', 'The C compiler'), @@ -3931,24 +3881,24 @@ opt.AddVariables( </listitem> </varlistentry> <varlistentry> - <term>Update(<emphasis remap='I'>env</emphasis>, [<emphasis remap='I'>args</emphasis>])</term> + <term>Update(<emphasis>env</emphasis>, [<emphasis>args</emphasis>])</term> <listitem> <para>This updates a construction environment -<emphasis remap='I'>env</emphasis> +<emphasis>env</emphasis> with the customized construction variables. Any specified variables that are -<emphasis remap='I'>not</emphasis> +<emphasis>not</emphasis> configured for the Variables object will be saved and may be retrieved with the -<emphasis remap='B'>UnknownVariables</emphasis>() +<emphasis role="bold">UnknownVariables</emphasis>() method, below.</para> <para>Normally this method is not called directly, but is called indirectly by passing the Variables object to the Environment() function:</para> -<literallayout remap='.nf'> +<literallayout> env = Environment(variables=vars) </literallayout> <!-- .fi --> @@ -3964,13 +3914,13 @@ are added to the construction environment.</para> <para>Example:</para> -<literallayout remap='.nf'> +<literallayout> CC = 'my_cc' </literallayout> <!-- .fi --> -<variablelist remap='TP'> +<variablelist> <varlistentry> - <term>UnknownVariables(<emphasis remap='I'>)</emphasis></term> + <term>UnknownVariables(<emphasis>)</emphasis></term> <listitem> <para>Returns a dictionary containing any variables that were specified @@ -3979,7 +3929,7 @@ with which the Variables object was initialized, but for which the Variables object was not configured.</para> -<literallayout remap='.nf'> +<literallayout> env = Environment(variables=vars) for key, value in vars.UnknownVariables(): print "unknown variable: %s=%s" % (key, value) @@ -3988,15 +3938,15 @@ for key, value in vars.UnknownVariables(): </listitem> </varlistentry> <varlistentry> - <term>Save(<emphasis remap='I'>filename</emphasis>, <emphasis remap='I'>env</emphasis>)</term> + <term>Save(<emphasis>filename</emphasis>, <emphasis>env</emphasis>)</term> <listitem> <para>This saves the currently set variables into a script file named -<emphasis remap='I'>filename</emphasis> +<emphasis>filename</emphasis> that can be used on the next invocation to automatically load the current settings. This method combined with the Variables method can be used to support caching of variables between runs.</para> -<literallayout remap='.nf'> +<literallayout> env = Environment() vars = Variables(['variables.cache', 'custom.py']) vars.Add(...) @@ -4007,29 +3957,29 @@ vars.Save('variables.cache', env) </listitem> </varlistentry> <varlistentry> - <term>GenerateHelpText(<emphasis remap='I'>env</emphasis>, [<emphasis remap='I'>sort</emphasis>])</term> + <term>GenerateHelpText(<emphasis>env</emphasis>, [<emphasis>sort</emphasis>])</term> <listitem> <para>This generates help text documenting the customizable construction variables suitable to passing in to the Help() function. -<emphasis remap='I'>env</emphasis> +<emphasis>env</emphasis> is the construction environment that will be used to get the actual values of customizable variables. Calling with an optional -<emphasis remap='I'>sort</emphasis> +<emphasis>sort</emphasis> function will cause the output to be sorted by the specified argument. The specific -<emphasis remap='I'>sort</emphasis> +<emphasis>sort</emphasis> function should take two arguments and return -1, 0 or 1 (like the standard Python -<emphasis remap='I'>cmp</emphasis> +<emphasis>cmp</emphasis> function).</para> -<literallayout remap='.nf'> +<literallayout> Help(vars.GenerateHelpText(env)) Help(vars.GenerateHelpText(env, sort=cmp)) </literallayout> <!-- .fi --> @@ -4037,26 +3987,26 @@ Help(vars.GenerateHelpText(env, sort=cmp)) </listitem> </varlistentry> <varlistentry> - <term>FormatVariableHelpText(<emphasis remap='I'>env</emphasis>, <emphasis remap='I'>opt</emphasis>, <emphasis remap='I'>help</emphasis>, <emphasis remap='I'>default</emphasis>, <emphasis remap='I'>actual</emphasis>)</term> + <term>FormatVariableHelpText(<emphasis>env</emphasis>, <emphasis>opt</emphasis>, <emphasis>help</emphasis>, <emphasis>default</emphasis>, <emphasis>actual</emphasis>)</term> <listitem> <para>This method returns a formatted string containing the printable help text for one option. It is normally not called directly, but is called by the -<emphasis remap='I'>GenerateHelpText</emphasis>() +<emphasis>GenerateHelpText</emphasis>() method to create the returned help text. It may be overridden with your own function that takes the arguments specified above and returns a string of help text formatted to your liking. Note that the -<emphasis remap='I'>GenerateHelpText</emphasis>() +<emphasis>GenerateHelpText</emphasis>() will not put any blank lines or extra characters in between the entries, so you must add those characters to the returned string if you want the entries separated.</para> -<programlisting remap='.nf'> +<programlisting> def my_format(env, opt, help, default, actual): fmt = "\n%s: default=%s actual=%s (%s)\n" return fmt % (opt, default. actual, help) @@ -4072,43 +4022,43 @@ various types of Variables:</para> </listitem> </varlistentry> <varlistentry> - <term>BoolVariable(<emphasis remap='I'>key</emphasis>, <emphasis remap='I'>help</emphasis>, <emphasis remap='I'>default</emphasis>)</term> + <term>BoolVariable(<emphasis>key</emphasis>, <emphasis>help</emphasis>, <emphasis>default</emphasis>)</term> <listitem> <para>Return a tuple of arguments to set up a Boolean option. The option will use the specified name -<emphasis remap='I'>key</emphasis>, +<emphasis>key</emphasis>, have a default value of -<emphasis remap='I'>default</emphasis>, +<emphasis>default</emphasis>, and display the specified -<emphasis remap='I'>help</emphasis> +<emphasis>help</emphasis> text. The option will interpret the values -<emphasis remap='B'>y</emphasis>, -<emphasis remap='B'>yes</emphasis>, -<emphasis remap='B'>t</emphasis>, -<emphasis remap='B'>true</emphasis>, +<emphasis role="bold">y</emphasis>, +<emphasis role="bold">yes</emphasis>, +<emphasis role="bold">t</emphasis>, +<emphasis role="bold">true</emphasis>, <literal>1</literal>, -<emphasis remap='B'>on</emphasis> +<emphasis role="bold">on</emphasis> and -<emphasis remap='B'>all</emphasis> +<emphasis role="bold">all</emphasis> as true, and the values -<emphasis remap='B'>n</emphasis>, -<emphasis remap='B'>no</emphasis>, -<emphasis remap='B'>f</emphasis>, -<emphasis remap='B'>false</emphasis>, +<emphasis role="bold">n</emphasis>, +<emphasis role="bold">no</emphasis>, +<emphasis role="bold">f</emphasis>, +<emphasis role="bold">false</emphasis>, <literal>0</literal>, -<emphasis remap='B'>off</emphasis> +<emphasis role="bold">off</emphasis> and -<emphasis remap='B'>none</emphasis> +<emphasis role="bold">none</emphasis> as false.</para> </listitem> </varlistentry> <varlistentry> - <term>EnumVariable(<emphasis remap='I'>key</emphasis>, <emphasis remap='I'>help</emphasis>, <emphasis remap='I'>default</emphasis>, <emphasis remap='I'>allowed_values</emphasis>, [<emphasis remap='I'>map</emphasis>, <emphasis remap='I'>ignorecase</emphasis>])</term> + <term>EnumVariable(<emphasis>key</emphasis>, <emphasis>help</emphasis>, <emphasis>default</emphasis>, <emphasis>allowed_values</emphasis>, [<emphasis>map</emphasis>, <emphasis>ignorecase</emphasis>])</term> <listitem> <para>Return a tuple of arguments to set up an option @@ -4116,38 +4066,38 @@ whose value may be one of a specified list of legal enumerated values. The option will use the specified name -<emphasis remap='I'>key</emphasis>, +<emphasis>key</emphasis>, have a default value of -<emphasis remap='I'>default</emphasis>, +<emphasis>default</emphasis>, and display the specified -<emphasis remap='I'>help</emphasis> +<emphasis>help</emphasis> text. The option will only support those values in the -<emphasis remap='I'>allowed_values</emphasis> +<emphasis>allowed_values</emphasis> list. The optional -<emphasis remap='I'>map</emphasis> +<emphasis>map</emphasis> argument is a dictionary that can be used to convert input values into specific legal values in the -<emphasis remap='I'>allowed_values</emphasis> +<emphasis>allowed_values</emphasis> list. If the value of -<emphasis remap='I'>ignore_case</emphasis> +<emphasis>ignore_case</emphasis> is <literal>0</literal> (the default), then the values are case-sensitive. If the value of -<emphasis remap='I'>ignore_case</emphasis> +<emphasis>ignore_case</emphasis> is <literal>1</literal>, then values will be matched case-insensitive. If the value of -<emphasis remap='I'>ignore_case</emphasis> +<emphasis>ignore_case</emphasis> is <literal>1</literal>, then values will be matched @@ -4158,7 +4108,7 @@ converted to lower case.</para> </listitem> </varlistentry> <varlistentry> - <term>ListVariable(<emphasis remap='I'>key</emphasis>, <emphasis remap='I'>help</emphasis>, <emphasis remap='I'>default</emphasis>, <emphasis remap='I'>names</emphasis>, [<emphasis remap='I'>,</emphasis>map<emphasis remap='I'>])</emphasis></term> + <term>ListVariable(<emphasis>key</emphasis>, <emphasis>help</emphasis>, <emphasis>default</emphasis>, <emphasis>names</emphasis>, [<emphasis>,</emphasis>map<emphasis>])</emphasis></term> <listitem> <para>Return a tuple of arguments to set up an option @@ -4166,17 +4116,17 @@ whose value may be one or more of a specified list of legal enumerated values. The option will use the specified name -<emphasis remap='I'>key</emphasis>, +<emphasis>key</emphasis>, have a default value of -<emphasis remap='I'>default</emphasis>, +<emphasis>default</emphasis>, and display the specified -<emphasis remap='I'>help</emphasis> +<emphasis>help</emphasis> text. The option will only support the values -<emphasis remap='B'>all</emphasis>, -<emphasis remap='B'>none</emphasis>, +<emphasis role="bold">all</emphasis>, +<emphasis role="bold">none</emphasis>, or the values in the -<emphasis remap='I'>names</emphasis> +<emphasis>names</emphasis> list. More than one value may be specified, with all values separated by commas. @@ -4184,18 +4134,18 @@ The default may be a string of comma-separated default values, or a list of the default values. The optional -<emphasis remap='I'>map</emphasis> +<emphasis>map</emphasis> argument is a dictionary that can be used to convert input values into specific legal values in the -<emphasis remap='I'>names</emphasis> +<emphasis>names</emphasis> list.</para> </listitem> </varlistentry> <varlistentry> - <term>PackageVariable(<emphasis remap='I'>key</emphasis>, <emphasis remap='I'>help</emphasis>, <emphasis remap='I'>default</emphasis>)</term> + <term>PackageVariable(<emphasis>key</emphasis>, <emphasis>help</emphasis>, <emphasis>default</emphasis>)</term> <listitem> <para>Return a tuple of arguments to set up an option @@ -4205,84 +4155,84 @@ enabled, disabled or given an explicit path name. The option will use the specified name -<emphasis remap='I'>key</emphasis>, +<emphasis>key</emphasis>, have a default value of -<emphasis remap='I'>default</emphasis>, +<emphasis>default</emphasis>, and display the specified -<emphasis remap='I'>help</emphasis> +<emphasis>help</emphasis> text. The option will support the values -<emphasis remap='B'>yes</emphasis>, -<emphasis remap='B'>true</emphasis>, -<emphasis remap='B'>on</emphasis>, -<emphasis remap='B'>enable</emphasis> +<emphasis role="bold">yes</emphasis>, +<emphasis role="bold">true</emphasis>, +<emphasis role="bold">on</emphasis>, +<emphasis role="bold">enable</emphasis> or -<emphasis remap='B'>search</emphasis>, +<emphasis role="bold">search</emphasis>, in which case the specified -<emphasis remap='I'>default</emphasis> +<emphasis>default</emphasis> will be used, or the option may be set to an arbitrary string (typically the path name to a package that is being enabled). The option will also support the values -<emphasis remap='B'>no</emphasis>, -<emphasis remap='B'>false</emphasis>, -<emphasis remap='B'>off</emphasis> +<emphasis role="bold">no</emphasis>, +<emphasis role="bold">false</emphasis>, +<emphasis role="bold">off</emphasis> or -<emphasis remap='B'>disable</emphasis> +<emphasis role="bold">disable</emphasis> to disable use of the specified option.</para> </listitem> </varlistentry> <varlistentry> - <term>PathVariable(<emphasis remap='I'>key</emphasis>, <emphasis remap='I'>help</emphasis>, <emphasis remap='I'>default</emphasis>, [<emphasis remap='I'>validator</emphasis>])</term> + <term>PathVariable(<emphasis>key</emphasis>, <emphasis>help</emphasis>, <emphasis>default</emphasis>, [<emphasis>validator</emphasis>])</term> <listitem> <para>Return a tuple of arguments to set up an option whose value is expected to be a path name. The option will use the specified name -<emphasis remap='I'>key</emphasis>, +<emphasis>key</emphasis>, have a default value of -<emphasis remap='I'>default</emphasis>, +<emphasis>default</emphasis>, and display the specified -<emphasis remap='I'>help</emphasis> +<emphasis>help</emphasis> text. An additional -<emphasis remap='I'>validator</emphasis> +<emphasis>validator</emphasis> may be specified that will be called to verify that the specified path is acceptable. SCons supplies the following ready-made validators: -<emphasis remap='B'>PathVariable.PathExists</emphasis> +<emphasis role="bold">PathVariable.PathExists</emphasis> (the default), which verifies that the specified path exists; -<emphasis remap='B'>PathVariable.PathIsFile</emphasis>, +<emphasis role="bold">PathVariable.PathIsFile</emphasis>, which verifies that the specified path is an existing file; -<emphasis remap='B'>PathVariable.PathIsDir</emphasis>, +<emphasis role="bold">PathVariable.PathIsDir</emphasis>, which verifies that the specified path is an existing directory; -<emphasis remap='B'>PathVariable.PathIsDirCreate</emphasis>, +<emphasis role="bold">PathVariable.PathIsDirCreate</emphasis>, which verifies that the specified path is a directory and will create the specified directory if the path does not exist; and -<emphasis remap='B'>PathVariable.PathAccept</emphasis>, +<emphasis role="bold">PathVariable.PathAccept</emphasis>, which simply accepts the specific path name argument without validation, and which is suitable if you want your users to be able to specify a directory path that will be created as part of the build process, for example. You may supply your own -<emphasis remap='I'>validator</emphasis> +<emphasis>validator</emphasis> function, which must take three arguments -(<emphasis remap='I'>key</emphasis>, +(<emphasis>key</emphasis>, the name of the variable to be set; -<emphasis remap='I'>val</emphasis>, +<emphasis>val</emphasis>, the specified value being checked; and -<emphasis remap='I'>env</emphasis>, +<emphasis>env</emphasis>, the construction environment) and should raise an exception if the specified value is not acceptable.</para> @@ -4294,10 +4244,10 @@ if the specified value is not acceptable.</para> convenient to create a number of variables with consistent behavior in a single call to the -<emphasis remap='B'>AddVariables</emphasis> +<emphasis role="bold">AddVariables</emphasis> method:</para> -<literallayout remap='.nf'> +<literallayout> vars.AddVariables( BoolVariable('warnings', 'compilation with -Wall and similiar', 1), EnumVariable('debug', 'debug output and symbols', 'no' @@ -4322,19 +4272,19 @@ vars.AddVariables( <refsect2 id='file_and_directory_nodes'><title>File and Directory Nodes</title> <para>The -<emphasis remap='I'>File</emphasis>() +<emphasis>File</emphasis>() and -<emphasis remap='I'>Dir</emphasis>() +<emphasis>Dir</emphasis>() functions return -<emphasis remap='I'>File</emphasis> +<emphasis>File</emphasis> and -<emphasis remap='I'>Dir</emphasis> +<emphasis>Dir</emphasis> Nodes, respectively. python objects, respectively. Those objects have several user-visible attributes and methods that are often useful:</para> -<variablelist remap='IP'> +<variablelist> <varlistentry> <term>path</term> <listitem> @@ -4343,10 +4293,10 @@ of the given file or directory. This path is relative to the top-level directory (where the -<emphasis remap='B'>SConstruct</emphasis> +<emphasis role="bold">SConstruct</emphasis> file is found). The build path is the same as the source path if -<emphasis remap='I'>variant_dir</emphasis> +<emphasis>variant_dir</emphasis> is not being used.</para> </listitem> @@ -4362,21 +4312,21 @@ is not being used.</para> <term>srcnode()</term> <listitem> <para>The -<emphasis remap='I'>srcnode</emphasis>() +<emphasis>srcnode</emphasis>() method returns another -<emphasis remap='I'>File</emphasis> +<emphasis>File</emphasis> or -<emphasis remap='I'>Dir</emphasis> +<emphasis>Dir</emphasis> object representing the -<emphasis remap='I'>source</emphasis> +<emphasis>source</emphasis> path of the given -<emphasis remap='I'>File</emphasis> +<emphasis>File</emphasis> or -<emphasis remap='I'>Dir</emphasis>. +<emphasis>Dir</emphasis>. The</para> -<literallayout remap='.nf'> +<literallayout> # Get the current build dir's path, relative to top. Dir('.').path # Current dir's absolute path @@ -4391,97 +4341,97 @@ print "foo will be built in %s"%foo.path </literallayout> <!-- .fi --> <para>A -<emphasis remap='I'>Dir</emphasis> +<emphasis>Dir</emphasis> Node or -<emphasis remap='I'>File</emphasis> +<emphasis>File</emphasis> Node can also be used to create file and subdirectory Nodes relative to the generating Node. A -<emphasis remap='I'>Dir</emphasis> +<emphasis>Dir</emphasis> Node will place the new Nodes within the directory it represents. A -<emphasis remap='I'>File</emphasis> +<emphasis>File</emphasis> node will place the new Nodes within its parent directory (that is, "beside" the file in question). If -<emphasis remap='I'>d</emphasis> +<emphasis>d</emphasis> is a -<emphasis remap='I'>Dir</emphasis> +<emphasis>Dir</emphasis> (directory) Node and -<emphasis remap='I'>f</emphasis> +<emphasis>f</emphasis> is a -<emphasis remap='I'>File</emphasis> +<emphasis>File</emphasis> (file) Node, then these methods are available:</para> </listitem> </varlistentry> </variablelist> -<variablelist remap='TP'> +<variablelist> <varlistentry> - <term><emphasis remap='I'>d</emphasis>.Dir(<emphasis remap='I'>name</emphasis>)</term> + <term><emphasis>d</emphasis>.Dir(<emphasis>name</emphasis>)</term> <listitem> <para>Returns a directory Node for a subdirectory of -<emphasis remap='I'>d</emphasis> +<emphasis>d</emphasis> named -<emphasis remap='I'>name</emphasis>.</para> +<emphasis>name</emphasis>.</para> </listitem> </varlistentry> <varlistentry> - <term><emphasis remap='I'>d</emphasis>.File(<emphasis remap='I'>name</emphasis>)</term> + <term><emphasis>d</emphasis>.File(<emphasis>name</emphasis>)</term> <listitem> <para>Returns a file Node for a file within -<emphasis remap='I'>d</emphasis> +<emphasis>d</emphasis> named -<emphasis remap='I'>name</emphasis>.</para> +<emphasis>name</emphasis>.</para> </listitem> </varlistentry> <varlistentry> - <term><emphasis remap='I'>d</emphasis>.Entry(<emphasis remap='I'>name</emphasis>)</term> + <term><emphasis>d</emphasis>.Entry(<emphasis>name</emphasis>)</term> <listitem> <para>Returns an unresolved Node within -<emphasis remap='I'>d</emphasis> +<emphasis>d</emphasis> named -<emphasis remap='I'>name</emphasis>.</para> +<emphasis>name</emphasis>.</para> </listitem> </varlistentry> <varlistentry> - <term><emphasis remap='I'>f</emphasis>.Dir(<emphasis remap='I'>name</emphasis>)</term> + <term><emphasis>f</emphasis>.Dir(<emphasis>name</emphasis>)</term> <listitem> <para>Returns a directory named -<emphasis remap='I'>name</emphasis> +<emphasis>name</emphasis> within the parent directory of -<emphasis remap='I'>f</emphasis>.</para> +<emphasis>f</emphasis>.</para> </listitem> </varlistentry> <varlistentry> - <term><emphasis remap='I'>f</emphasis>.File(<emphasis remap='I'>name</emphasis>)</term> + <term><emphasis>f</emphasis>.File(<emphasis>name</emphasis>)</term> <listitem> <para>Returns a file named -<emphasis remap='I'>name</emphasis> +<emphasis>name</emphasis> within the parent directory of -<emphasis remap='I'>f</emphasis>.</para> +<emphasis>f</emphasis>.</para> </listitem> </varlistentry> <varlistentry> - <term><emphasis remap='I'>f</emphasis>.Entry(<emphasis remap='I'>name</emphasis>)</term> + <term><emphasis>f</emphasis>.Entry(<emphasis>name</emphasis>)</term> <listitem> <para>Returns an unresolved Node named -<emphasis remap='I'>name</emphasis> +<emphasis>name</emphasis> within the parent directory of -<emphasis remap='I'>f</emphasis>.</para> +<emphasis>f</emphasis>.</para> </listitem> </varlistentry> </variablelist> <para>For example:</para> -<literallayout remap='.nf'> +<literallayout> # Get a Node for a file within a directory incl = Dir('include') f = incl.File('header.h') @@ -4511,7 +4461,7 @@ css = index.File('app.css') can be extended to build different types of targets by adding new Builder objects to a construction environment. -<emphasis remap='I'>In general</emphasis>, +<emphasis>In general</emphasis>, you should only need to add a new Builder object when you want to build a new type of file or other external target. If you just want to invoke a different compiler or other tool @@ -4527,18 +4477,18 @@ that sets the appropriate construction variables <para>Builder objects are created using the -<emphasis remap='B'>Builder</emphasis> +<emphasis role="bold">Builder</emphasis> function. The -<emphasis remap='B'>Builder</emphasis> +<emphasis role="bold">Builder</emphasis> function accepts the following arguments:</para> -<variablelist remap='IP'> +<variablelist> <varlistentry> <term>action</term> <listitem> <para>The command line string used to build the target from the source. -<emphasis remap='B'>action</emphasis> +<emphasis role="bold">action</emphasis> can also be: a list of strings representing the command to be executed and its arguments @@ -4554,11 +4504,11 @@ or a list of any of the above.</para> <para>An action function takes three arguments: -<emphasis remap='I'>source</emphasis> +<emphasis>source</emphasis> - a list of source nodes, -<emphasis remap='I'>target</emphasis> +<emphasis>target</emphasis> - a list of target nodes, -<emphasis remap='I'>env</emphasis> +<emphasis>env</emphasis> - the construction environment.</para> </listitem> @@ -4569,34 +4519,34 @@ takes three arguments: <para>The prefix that will be prepended to the target file name. This may be specified as a:</para> - <blockquote remap='RS'> + <blockquote> <para>* -<emphasis remap='I'>string</emphasis>,</para> +<emphasis>string</emphasis>,</para> <para>* -<emphasis remap='I'>callable object</emphasis> +<emphasis>callable object</emphasis> - a function or other callable that takes two arguments (a construction environment and a list of sources) and returns a prefix,</para> <para>* -<emphasis remap='I'>dictionary</emphasis> +<emphasis>dictionary</emphasis> - specifies a mapping from a specific source suffix (of the first source specified) to a corresponding target prefix. Both the source suffix and target prefix specifications may use environment variable substitution, and the target prefix (the 'value' entries in the dictionary) may also be a callable object. The default target prefix may be indicated by a dictionary entry with a key value of None. - </para></blockquote> <!-- remap='RE' --> + </para></blockquote> </listitem> </varlistentry> </variablelist> -<programlisting remap='.nf'> +<programlisting> b = Builder("build_it < $SOURCE > $TARGET", prefix = "file-") @@ -4610,7 +4560,7 @@ b = Builder("build_it < $SOURCE > $TARGET", "$SRC_SFX_A": gen_prefix }) </programlisting> <!-- .fi --> -<variablelist remap='IP'> +<variablelist> <varlistentry> <term>suffix</term> <listitem> @@ -4623,7 +4573,7 @@ there. The string returned by callable object (or obtained from the dictionary) is untouched and must append its own '.' to the beginning if one is desired.</para> -<programlisting remap='.nf'> +<programlisting> b = Builder("build_it < $SOURCE > $TARGET" suffix = "-file") @@ -4645,13 +4595,13 @@ b = Builder("build_it < $SOURCE > $TARGET", <para>When set to any true value, causes <command>scons</command> to add the target suffix specified by the -<emphasis remap='I'>suffix</emphasis> +<emphasis>suffix</emphasis> keyword to any target strings that have a different suffix. (The default behavior is to leave untouched any target file name that looks like it already has any suffix.)</para> -<literallayout remap='.nf'> +<literallayout> b1 = Builder("build_it < $SOURCE > $TARGET" suffix = ".out") b2 = Builder("build_it < $SOURCE > $TARGET" @@ -4689,7 +4639,7 @@ for Scanner objects that find implicit dependencies based only on the target file and the construction environment, -<emphasis remap='I'>not</emphasis> +<emphasis>not</emphasis> for implicit dependencies based on source files. (See the section "Scanner Objects" below, for information about creating Scanner objects.)</para> @@ -4707,10 +4657,10 @@ used to build this target file. This is where you would specify a scanner to find things like -<emphasis remap='B'>#include</emphasis> +<emphasis role="bold">#include</emphasis> lines in source files. The pre-built -<emphasis remap='B'>DirScanner</emphasis> +<emphasis role="bold">DirScanner</emphasis> Scanner object may be used to indicate that this Builder should scan directory trees @@ -4732,16 +4682,16 @@ By default, SCons assumes that all targets are files. Other useful target_factory values include -<emphasis remap='B'>Dir</emphasis>, +<emphasis role="bold">Dir</emphasis>, for when a Builder creates a directory target, and -<emphasis remap='B'>Entry</emphasis>, +<emphasis role="bold">Entry</emphasis>, for when a Builder can create either a file or directory target.</para> <para>Example:</para> -<literallayout remap='.nf'> +<literallayout> MakeDirectoryBuilder = Builder(action=my_mkdir, target_factory=Dir) env = Environment() env.Append(BUILDERS = {'MakeDirectory':MakeDirectoryBuilder}) @@ -4769,16 +4719,16 @@ By default, SCons assumes that all source are files. Other useful source_factory values include -<emphasis remap='B'>Dir</emphasis>, +<emphasis role="bold">Dir</emphasis>, for when a Builder uses a directory as a source, and -<emphasis remap='B'>Entry</emphasis>, +<emphasis role="bold">Entry</emphasis>, for when a Builder can use files or directories (or both) as sources.</para> <para>Example:</para> -<programlisting remap='.nf'> +<programlisting> CollectBuilder = Builder(action=my_mkdir, source_factory=Entry) env = Environment() env.Append(BUILDERS = {'Collect':CollectBuilder}) @@ -4793,7 +4743,7 @@ env.Collect('archive', ['directory_name', 'file_name']) <para>A function or list of functions to manipulate the target and source lists before dependencies are established and the target(s) are actually built. -<emphasis remap='B'>emitter</emphasis> +<emphasis role="bold">emitter</emphasis> can also be a string containing a construction variable to expand to an emitter function or list of functions, or a dictionary mapping source file suffixes @@ -4804,11 +4754,11 @@ from an emitter dictionary.)</para> <para>An emitter function takes three arguments: -<emphasis remap='I'>source</emphasis> +<emphasis>source</emphasis> - a list of source nodes, -<emphasis remap='I'>target</emphasis> +<emphasis>target</emphasis> - a list of target nodes, -<emphasis remap='I'>env</emphasis> +<emphasis>env</emphasis> - the construction environment. An emitter must return a tuple containing two lists, the list of targets to be built by this builder, @@ -4816,7 +4766,7 @@ and the list of sources for this builder.</para> <para>Example:</para> -<programlisting remap='.nf'> +<programlisting> def e(target, source, env): return (target + ['foo.foo'], source + ['foo.src']) @@ -4873,7 +4823,7 @@ builder with the target.</para> <para>A construction environment that can be used to fetch source code using this Builder. (Note that this environment is -<emphasis remap='I'>not</emphasis> +<emphasis>not</emphasis> used for normal builds of normal target files, which use the environment that was used to call the Builder for the target file.)</para> @@ -4892,20 +4842,20 @@ can be converted into an Action object <para>The generator function takes four arguments: -<emphasis remap='I'>source</emphasis> +<emphasis>source</emphasis> - a list of source nodes, -<emphasis remap='I'>target</emphasis> +<emphasis>target</emphasis> - a list of target nodes, -<emphasis remap='I'>env</emphasis> +<emphasis>env</emphasis> - the construction environment, -<emphasis remap='I'>for_signature</emphasis> +<emphasis>for_signature</emphasis> - a Boolean value that specifies whether the generator is being called for generating a build signature (as opposed to actually executing the command). Example:</para> -<programlisting remap='.nf'> +<programlisting> def g(source, target, env, for_signature): return [["gcc", "-c", "-o"] + target + source] @@ -4914,9 +4864,9 @@ b = Builder(generator=g) <para>The -<emphasis remap='I'>generator</emphasis> +<emphasis>generator</emphasis> and -<emphasis remap='I'>action</emphasis> +<emphasis>action</emphasis> arguments must not both be used for the same Builder.</para> </listitem> @@ -4943,17 +4893,17 @@ source files together with target files results in a UserError exception.</para> </variablelist> <para>The -<emphasis remap='I'>generator</emphasis> +<emphasis>generator</emphasis> and -<emphasis remap='I'>action</emphasis> +<emphasis>action</emphasis> arguments must not both be used for the same Builder.</para> -<variablelist remap='IP'> +<variablelist> <varlistentry> <term>source_ext_match</term> <listitem> <para>When the specified -<emphasis remap='I'>action</emphasis> +<emphasis>action</emphasis> argument is a dictionary, the default behavior when a builder is passed multiple source files is to make sure that the @@ -4961,31 +4911,31 @@ extensions of all the source files match. If it is legal for this builder to be called with a list of source files with different extensions, this check can be suppressed by setting -<emphasis remap='B'>source_ext_match</emphasis> +<emphasis role="bold">source_ext_match</emphasis> to -<emphasis remap='B'>None</emphasis> +<emphasis role="bold">None</emphasis> or some other non-true value. When -<emphasis remap='B'>source_ext_match</emphasis> +<emphasis role="bold">source_ext_match</emphasis> is disable, <command>scons</command> will use the suffix of the first specified source file to select the appropriate action from the -<emphasis remap='I'>action</emphasis> +<emphasis>action</emphasis> dictionary.</para> <para>In the following example, the setting of -<emphasis remap='B'>source_ext_match</emphasis> +<emphasis role="bold">source_ext_match</emphasis> prevents <command>scons</command> from exiting with an error due to the mismatched suffixes of -<emphasis remap='B'>foo.in</emphasis> +<emphasis role="bold">foo.in</emphasis> and -<emphasis remap='B'>foo.extra</emphasis>.</para> +<emphasis role="bold">foo.extra</emphasis>.</para> -<literallayout remap='.nf'> +<literallayout> b = Builder(action={'.in' : 'build $SOURCES > $TARGET'}, source_ext_match = None) @@ -5001,12 +4951,12 @@ env.MyBuild('foo.out', ['foo.in', 'foo.extra']) <para>A construction environment that can be used to fetch source code using this Builder. (Note that this environment is -<emphasis remap='I'>not</emphasis> +<emphasis>not</emphasis> used for normal builds of normal target files, which use the environment that was used to call the Builder for the target file.)</para> -<literallayout remap='.nf'> +<literallayout> b = Builder(action="build < $SOURCE > $TARGET") env = Environment(BUILDERS = {'MyBuild' : b}) env.MyBuild('foo.out', 'foo.in', my_arg = 'xyzzy') @@ -5022,25 +4972,25 @@ will execute the action(s) specified for this Builder. If the -<emphasis remap='B'>chdir</emphasis> +<emphasis role="bold">chdir</emphasis> argument is a string or a directory Node, scons will change to the specified directory. If the -<emphasis remap='B'>chdir</emphasis> +<emphasis role="bold">chdir</emphasis> is not a string or Node and is non-zero, then scons will change to the target file's directory.</para> <para>Note that scons will -<emphasis remap='I'>not</emphasis> +<emphasis>not</emphasis> automatically modify its expansion of construction variables like -<emphasis remap='B'>$TARGET</emphasis> +<emphasis role="bold">$TARGET</emphasis> and -<emphasis remap='B'>$SOURCE</emphasis> +<emphasis role="bold">$SOURCE</emphasis> when using the chdir keyword argument--that is, the expanded file names @@ -5051,27 +5001,27 @@ relative to the chdir directory. Builders created using chdir keyword argument, will need to use construction variable expansions like -<emphasis remap='B'>${TARGET.file}</emphasis> +<emphasis role="bold">${TARGET.file}</emphasis> and -<emphasis remap='B'>${SOURCE.file}</emphasis> +<emphasis role="bold">${SOURCE.file}</emphasis> to use just the filename portion of the targets and source.</para> -<literallayout remap='.nf'> +<literallayout> b = Builder(action="build < ${SOURCE.file} > ${TARGET.file}", chdir=1) env = Environment(BUILDERS = {'MyBuild' : b}) env.MyBuild('sub/dir/foo.out', 'sub/dir/foo.in') </literallayout> <!-- .fi --> -<para><emphasis remap='B'>WARNING:</emphasis> +<para><emphasis role="bold">WARNING:</emphasis> Python only keeps one current directory location for all of the threads. This means that use of the -<emphasis remap='B'>chdir</emphasis> +<emphasis role="bold">chdir</emphasis> argument will -<emphasis remap='I'>not</emphasis> +<emphasis>not</emphasis> work with the SCons <option>-j</option> option, @@ -5093,7 +5043,7 @@ the repository of a source code system.</para> <para>Any additional keyword arguments supplied when a Builder -<emphasis remap='I'>object</emphasis> +<emphasis>object</emphasis> is called will only be associated with the target created by that particular Builder call @@ -5111,17 +5061,17 @@ and emitter functions.</para> <refsect2 id='action_objects'><title>Action Objects</title> <para>The -<emphasis remap='B'>Builder</emphasis>() +<emphasis role="bold">Builder</emphasis>() function will turn its -<emphasis remap='B'>action</emphasis> +<emphasis role="bold">action</emphasis> keyword argument into an appropriate internal Action object. You can also explicity create Action objects using the -<emphasis remap='B'>Action</emphasis>() +<emphasis role="bold">Action</emphasis>() global function, which can then be passed to the -<emphasis remap='B'>Builder</emphasis>() +<emphasis role="bold">Builder</emphasis>() function. This can be used to configure an Action object more flexibly, @@ -5132,12 +5082,12 @@ when multiple Builder objects need to do the same thing.</para> <para>The -<emphasis remap='B'>Action</emphasis>() +<emphasis role="bold">Action</emphasis>() global function returns an appropriate object for the action represented by the type of the first argument:</para> -<variablelist remap='IP'> +<variablelist> <varlistentry> <term>Action</term> <listitem> @@ -5153,15 +5103,15 @@ the object is simply returned.</para> a command-line Action is returned. Note that the command-line string may be preceded by an -<emphasis remap='B'>@</emphasis> +<emphasis role="bold">@</emphasis> (at-sign) to suppress printing of the specified command line, or by a -<emphasis remap='B'>-</emphasis> +<emphasis role="bold">-</emphasis> (hyphen) to ignore the exit status from the specified command:</para> -<literallayout remap='.nf'> +<literallayout> Action('$CC -c -o $TARGET $SOURCES') # Doesn't print the line being executed. @@ -5189,7 +5139,7 @@ then a list of Action objects is returned. An Action object is created as necessary for each element in the list. If an element -<emphasis remap='I'>within</emphasis> +<emphasis>within</emphasis> the list is itself a list, the internal list is the command and arguments to be executed via @@ -5198,7 +5148,7 @@ This allows white space to be enclosed in an argument by defining a command in a list within a list:</para> -<literallayout remap='.nf'> +<literallayout> Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']]) </literallayout> <!-- .fi --> @@ -5210,25 +5160,25 @@ Action([['cc', '-c', '-DWHITE SPACE', '-o', '$TARGET', '$SOURCES']]) <para>If the first argument is a Python function, a function Action is returned. The Python function must take three keyword arguments, -<emphasis remap='B'>target</emphasis> +<emphasis role="bold">target</emphasis> (a Node object representing the target file), -<emphasis remap='B'>source</emphasis> +<emphasis role="bold">source</emphasis> (a Node object representing the source file) and -<emphasis remap='B'>env</emphasis> +<emphasis role="bold">env</emphasis> (the construction environment used for building the target file). The -<emphasis remap='B'>target</emphasis> +<emphasis role="bold">target</emphasis> and -<emphasis remap='B'>source</emphasis> +<emphasis role="bold">source</emphasis> arguments may be lists of Node objects if there is more than one target file or source file. The actual target and source file name(s) may be retrieved from their Node objects via the built-in Python str() function:</para> -<literallayout remap='.nf'> +<literallayout> target_file_name = str(target) source_file_names = map(lambda x: str(x), source) </literallayout> <!-- .fi --> @@ -5236,13 +5186,13 @@ source_file_names = map(lambda x: str(x), source) <para>The function should return <literal>0</literal> or -<emphasis remap='B'>None</emphasis> +<emphasis role="bold">None</emphasis> to indicate a successful build of the target file(s). The function may raise an exception or return a non-zero exit status to indicate an unsuccessful build.</para> -<programlisting remap='.nf'> +<programlisting> def build_it(target = None, source = None, env = None): # build the target from the source return 0 @@ -5269,27 +5219,27 @@ The argument must be either a Python function or a string.</para> it's a function that returns a string to be printed to describe the action being executed. The function may also be specified by the -<emphasis remap='I'>strfunction</emphasis>= +<emphasis>strfunction</emphasis>= keyword argument. Like a function to build a file, this function must take three keyword arguments: -<emphasis remap='B'>target</emphasis> +<emphasis role="bold">target</emphasis> (a Node object representing the target file), -<emphasis remap='B'>source</emphasis> +<emphasis role="bold">source</emphasis> (a Node object representing the source file) and -<emphasis remap='B'>env</emphasis> +<emphasis role="bold">env</emphasis> (a construction environment). The -<emphasis remap='B'>target</emphasis> +<emphasis role="bold">target</emphasis> and -<emphasis remap='B'>source</emphasis> +<emphasis role="bold">source</emphasis> arguments may be lists of Node objects if there is more than one target file or source file.</para> <para>In the second case, you provide the string itself. The string may also be specified by the -<emphasis remap='I'>cmdstr</emphasis>= +<emphasis>cmdstr</emphasis>= keyword argument. The string typically contains variables, notably $TARGET(S) and $SOURCE(S), or consists of just a single @@ -5298,7 +5248,7 @@ SCons itself heavily uses the latter variant.</para> <para>Examples:</para> -<programlisting remap='.nf'> +<programlisting> def build_it(target, source, env): # build the target from the source return 0 @@ -5323,7 +5273,7 @@ may either be a construction variable or a list of construction variables whose values will be included in the signature of the Action when deciding whether a target should be rebuilt because the action changed. The variables may also be specified by a -<emphasis remap='I'>varlist</emphasis>= +<emphasis>varlist</emphasis>= keyword parameter; if both are present, they are combined. This is necessary whenever you want a target to be rebuilt @@ -5333,7 +5283,7 @@ as the expanded variables will normally be part of the command line, but may be needed if a Python function action uses the value of a construction variable when generating the command line.</para> -<programlisting remap='.nf'> +<programlisting> def build_it(target, source, env): # build the target from the 'XXX' construction variable open(target[0], 'w').write(env['XXX']) @@ -5347,26 +5297,26 @@ a = Action(build_it, varlist=['XXX']) </programlisting> <!-- .fi --> <para>The -<emphasis remap='B'>Action</emphasis>() +<emphasis role="bold">Action</emphasis>() global function can be passed the following optional keyword arguments to modify the Action object's behavior:</para> -<para><emphasis remap='B'>chdir</emphasis> +<para><emphasis role="bold">chdir</emphasis> The -<emphasis remap='B'>chdir</emphasis> +<emphasis role="bold">chdir</emphasis> keyword argument specifies that scons will execute the action after changing to the specified directory. If the -<emphasis remap='B'>chdir</emphasis> +<emphasis role="bold">chdir</emphasis> argument is a string or a directory Node, scons will change to the specified directory. If the -<emphasis remap='B'>chdir</emphasis> +<emphasis role="bold">chdir</emphasis> argument is not a string or Node and is non-zero, @@ -5374,13 +5324,13 @@ then scons will change to the target file's directory.</para> <para>Note that scons will -<emphasis remap='I'>not</emphasis> +<emphasis>not</emphasis> automatically modify its expansion of construction variables like -<emphasis remap='B'>$TARGET</emphasis> +<emphasis role="bold">$TARGET</emphasis> and -<emphasis remap='B'>$SOURCE</emphasis> +<emphasis role="bold">$SOURCE</emphasis> when using the chdir keyword argument--that is, the expanded file names @@ -5391,24 +5341,24 @@ relative to the chdir directory. Builders created using chdir keyword argument, will need to use construction variable expansions like -<emphasis remap='B'>${TARGET.file}</emphasis> +<emphasis role="bold">${TARGET.file}</emphasis> and -<emphasis remap='B'>${SOURCE.file}</emphasis> +<emphasis role="bold">${SOURCE.file}</emphasis> to use just the filename portion of the targets and source.</para> -<literallayout remap='.nf'> +<literallayout> a = Action("build < ${SOURCE.file} > ${TARGET.file}", chdir=1) </literallayout> <!-- .fi --> -<para><emphasis remap='B'>exitstatfunc</emphasis> +<para><emphasis role="bold">exitstatfunc</emphasis> The -<emphasis remap='B'>Action</emphasis>() +<emphasis role="bold">Action</emphasis>() global function also takes an -<emphasis remap='B'>exitstatfunc</emphasis> +<emphasis role="bold">exitstatfunc</emphasis> keyword argument which specifies a function that is passed the exit status @@ -5423,7 +5373,7 @@ under special conditions and SCons should, therefore, consider that the action always suceeds:</para> -<programlisting remap='.nf'> +<programlisting> def always_succeed(s): # Always return 0, which indicates success. return 0 @@ -5432,9 +5382,9 @@ a = Action("build < ${SOURCE.file} > ${TARGET.file}", </programlisting> <!-- .fi --> -<para><emphasis remap='B'>batch_key</emphasis> +<para><emphasis role="bold">batch_key</emphasis> The -<emphasis remap='B'>batch_key</emphasis> +<emphasis role="bold">batch_key</emphasis> keyword argument can be used to specify that the Action can create multiple target files by processing multiple independent source files simultaneously. @@ -5444,7 +5394,7 @@ by passing multiple source files to a single invocation of a compiler such as Microsoft's Visual C / C++ compiler.) If the -<emphasis remap='B'>batch_key</emphasis> +<emphasis role="bold">batch_key</emphasis> argument is any non-False, non-callable Python value, the configured Action object will cause <command>scons</command> @@ -5453,22 +5403,22 @@ and configured with the same construction environment into single invocations of the Action object's command line or function. Command lines will typically want to use the -<emphasis remap='B'>CHANGED_SOURCES</emphasis> +<emphasis role="bold">CHANGED_SOURCES</emphasis> construction variable (and possibly -<emphasis remap='B'>CHANGED_TARGETS</emphasis> +<emphasis role="bold">CHANGED_TARGETS</emphasis> as well) to only pass to the command line those sources that have actually changed since their targets were built.</para> <para>Example:</para> -<literallayout remap='.nf'> +<literallayout> a = Action('build $CHANGED_SOURCES', batch_key=True) </literallayout> <!-- .fi --> <para>The -<emphasis remap='B'>batch_key</emphasis> +<emphasis role="bold">batch_key</emphasis> argument may also be a callable function that returns a key that @@ -5476,10 +5426,10 @@ will be used to identify different "batches" of target files to be collected for batch building. A -<emphasis remap='B'>batch_key</emphasis> +<emphasis role="bold">batch_key</emphasis> function must take the following arguments:</para> -<variablelist remap='IP'> +<variablelist> <varlistentry> <term>action</term> <listitem> @@ -5512,35 +5462,35 @@ be a tuple of values derived from the arguments, using any appropriate logic to decide how multiple invocations should be batched. For example, a -<emphasis remap='B'>batch_key</emphasis> +<emphasis role="bold">batch_key</emphasis> function may decide to return the value of a specific construction variable from the -<emphasis remap='B'>env</emphasis> +<emphasis role="bold">env</emphasis> argument which will cause <command>scons</command> to batch-build targets with matching values of that variable, or perhaps return the -<emphasis remap='B'>id</emphasis>() +<emphasis role="bold">id</emphasis>() of the entire construction environment, in which case <command>scons</command> will batch-build all targets configured with the same construction environment. Returning -<emphasis remap='B'>None</emphasis> +<emphasis role="bold">None</emphasis> indicates that the particular target should -<emphasis remap='I'>not</emphasis> +<emphasis>not</emphasis> be part of any batched build, but instead will be built by a separate invocation of action's command or function. Example:</para> -<programlisting remap='.nf'> +<programlisting> def batch_key(action, env, target, source): tdir = target[0].dir if tdir.name == 'special': @@ -5575,7 +5525,7 @@ appropriate time. (In Object-Oriented terminology, these are actually Action -<emphasis remap='I'>Factory</emphasis> +<emphasis>Factory</emphasis> functions that return Action objects.)</para> @@ -5591,9 +5541,9 @@ to perform the action at the time the SConscript file is being read, you can use the -<emphasis remap='B'>Execute</emphasis> +<emphasis role="bold">Execute</emphasis> global function to do so:</para> -<literallayout remap='.nf'> +<literallayout> Execute(Touch('file')) </literallayout> <!-- .fi --> @@ -5601,7 +5551,7 @@ Execute(Touch('file')) you can use these functions to supply Actions in a list for use by the -<emphasis remap='B'>Command</emphasis> +<emphasis role="bold">Command</emphasis> method. This can allow you to perform more complicated @@ -5610,7 +5560,7 @@ without relying on platform-specific external commands: that</para> -<literallayout remap='.nf'> +<literallayout> env = Environment(TMPBUILD = '/tmp/builddir') env.Command('foo.out', 'foo.in', [Mkdir('$TMPBUILD'), @@ -5619,18 +5569,18 @@ env.Command('foo.out', 'foo.in', Delete('$TMPBUILD')]) </literallayout> <!-- .fi --> -<variablelist remap='TP'> +<variablelist> <varlistentry> - <term>Chmod(<emphasis remap='I'>dest</emphasis>, <emphasis remap='I'>mode</emphasis>)</term> + <term>Chmod(<emphasis>dest</emphasis>, <emphasis>mode</emphasis>)</term> <listitem> <para>Returns an Action object that changes the permissions on the specified -<emphasis remap='I'>dest</emphasis> +<emphasis>dest</emphasis> file or directory to the specified -<emphasis remap='I'>mode</emphasis>. +<emphasis>mode</emphasis>. Examples:</para> -<literallayout remap='.nf'> +<literallayout> Execute(Chmod('file', 0755)) env.Command('foo.out', 'foo.in', @@ -5641,17 +5591,17 @@ env.Command('foo.out', 'foo.in', </listitem> </varlistentry> <varlistentry> - <term>Copy(<emphasis remap='I'>dest</emphasis>, <emphasis remap='I'>src</emphasis>)</term> + <term>Copy(<emphasis>dest</emphasis>, <emphasis>src</emphasis>)</term> <listitem> <para>Returns an Action object that will copy the -<emphasis remap='I'>src</emphasis> +<emphasis>src</emphasis> source file or directory to the -<emphasis remap='I'>dest</emphasis> +<emphasis>dest</emphasis> destination file or directory. Examples:</para> -<literallayout remap='.nf'> +<literallayout> Execute(Copy('foo.output', 'foo.input')) env.Command('bar.out', 'bar.in', @@ -5661,27 +5611,27 @@ env.Command('bar.out', 'bar.in', </listitem> </varlistentry> <varlistentry> - <term>Delete(<emphasis remap='I'>entry</emphasis>, [<emphasis remap='I'>must_exist</emphasis>])</term> + <term>Delete(<emphasis>entry</emphasis>, [<emphasis>must_exist</emphasis>])</term> <listitem> <para>Returns an Action that deletes the specified -<emphasis remap='I'>entry</emphasis>, +<emphasis>entry</emphasis>, which may be a file or a directory tree. If a directory is specified, the entire directory tree will be removed. If the -<emphasis remap='I'>must_exist</emphasis> +<emphasis>must_exist</emphasis> flag is set, then a Python error will be thrown if the specified entry does not exist; the default is -<emphasis remap='B'>must_exist=0</emphasis>, +<emphasis role="bold">must_exist=0</emphasis>, that is, the Action will silently do nothing if the entry does not exist. Examples:</para> -<literallayout remap='.nf'> +<literallayout> Execute(Delete('/tmp/buildroot')) env.Command('foo.out', 'foo.in', @@ -5694,15 +5644,15 @@ Execute(Delete('file_that_must_exist', must_exist=1)) </listitem> </varlistentry> <varlistentry> - <term>Mkdir(<emphasis remap='I'>dir</emphasis>)</term> + <term>Mkdir(<emphasis>dir</emphasis>)</term> <listitem> <para>Returns an Action that creates the specified directory -<emphasis remap='I'>dir .</emphasis> +<emphasis>dir .</emphasis> Examples:</para> -<literallayout remap='.nf'> +<literallayout> Execute(Mkdir('/tmp/outputdir')) env.Command('foo.out', 'foo.in', @@ -5715,18 +5665,18 @@ env.Command('foo.out', 'foo.in', </listitem> </varlistentry> <varlistentry> - <term>Move(<emphasis remap='I'>dest</emphasis>, <emphasis remap='I'>src</emphasis>)</term> + <term>Move(<emphasis>dest</emphasis>, <emphasis>src</emphasis>)</term> <listitem> <para>Returns an Action that moves the specified -<emphasis remap='I'>src</emphasis> +<emphasis>src</emphasis> file or directory to the specified -<emphasis remap='I'>dest</emphasis> +<emphasis>dest</emphasis> file or directory. Examples:</para> -<literallayout remap='.nf'> +<literallayout> Execute(Move('file.destination', 'file.source')) env.Command('output_file', 'input_file', @@ -5737,15 +5687,15 @@ env.Command('output_file', 'input_file', </listitem> </varlistentry> <varlistentry> - <term>Touch(<emphasis remap='I'>file</emphasis>)</term> + <term>Touch(<emphasis>file</emphasis>)</term> <listitem> <para>Returns an Action that updates the modification time on the specified -<emphasis remap='I'>file</emphasis>. +<emphasis>file</emphasis>. Examples:</para> -<literallayout remap='.nf'> +<literallayout> Execute(Touch('file_to_be_touched')) env.Command('marker', 'input_file', @@ -5765,12 +5715,12 @@ env.Command('marker', 'input_file', performs construction variable interpolation on the strings that make up the command line of builders. Variables are introduced by a -<emphasis remap='B'>$</emphasis> +<emphasis role="bold">$</emphasis> prefix. Besides construction variables, scons provides the following variables for each command execution:</para> -<variablelist remap='IP'> +<variablelist> <varlistentry> <term>CHANGED_SOURCES</term> <listitem> @@ -5824,7 +5774,7 @@ if multiple targets are being built.</para> <listitem> <para>The file names of all sources of the build command that have -<emphasis remap='I'>not</emphasis> +<emphasis>not</emphasis> changed since the target was last built.</para> </listitem> @@ -5834,7 +5784,7 @@ changed since the target was last built.</para> <listitem> <para>The file names of all targets that would be built from sources that have -<emphasis remap='I'>not</emphasis> +<emphasis>not</emphasis> changed since the target was last built.</para> <para>(Note that the above variables are reserved @@ -5847,13 +5797,13 @@ and may not be set in a construction environment.)</para> <para>For example, given the construction variable CC='cc', targets=['foo'], and sources=['foo.c', 'bar.c']:</para> -<literallayout remap='.nf'> +<literallayout> action='$CC -c -o $TARGET $SOURCES' </literallayout> <!-- .fi --> <para>would produce the command line:</para> -<literallayout remap='.nf'> +<literallayout> cc -c -o foo foo.c bar.c </literallayout> <!-- .fi --> @@ -5864,13 +5814,13 @@ a Python slice subscript appended to select one or more items from a list. In the previous example, the string:</para> -<literallayout remap='.nf'> +<literallayout> ${SOURCES[1]} </literallayout> <!-- .fi --> <para>would produce:</para> -<literallayout remap='.nf'> +<literallayout> bar.c </literallayout> <!-- .fi --> @@ -5879,7 +5829,7 @@ have the following special modifiers appended within the enclosing curly braces to modify the interpolated string:</para> -<variablelist remap='IP'> +<variablelist> <varlistentry> <term>base</term> <listitem> @@ -5932,7 +5882,7 @@ and minus the directory.</para> <listitem> <para>The POSIX form of the path, with directories separated by -<emphasis remap='B'>/</emphasis> +<emphasis role="bold">/</emphasis> (forward slashes) not backslashes. This is sometimes necessary on Windows systems @@ -5944,7 +5894,7 @@ when a path references a file on other (POSIX) systems.</para> <term>srcpath</term> <listitem> <para>The directory and file name to the source file linked to this file through -<emphasis remap='B'>VariantDir</emphasis>(). +<emphasis role="bold">VariantDir</emphasis>(). If this file isn't linked, it just returns the directory and filename unchanged.</para> @@ -5954,7 +5904,7 @@ it just returns the directory and filename unchanged.</para> <term>srcdir</term> <listitem> <para>The directory containing the source file linked to this file through -<emphasis remap='B'>VariantDir</emphasis>(). +<emphasis role="bold">VariantDir</emphasis>(). If this file isn't linked, it just returns the directory part of the filename.</para> @@ -5964,7 +5914,7 @@ it just returns the directory part of the filename.</para> <term>rsrcpath</term> <listitem> <para>The directory and file name to the source file linked to this file through -<emphasis remap='B'>VariantDir</emphasis>(). +<emphasis role="bold">VariantDir</emphasis>(). If the file does not exist locally but exists in a Repository, the path in the Repository is returned. If this file isn't linked, it just returns the @@ -5976,7 +5926,7 @@ directory and filename unchanged.</para> <term>rsrcdir</term> <listitem> <para>The Repository directory containing the source file linked to this file through -<emphasis remap='B'>VariantDir</emphasis>(). +<emphasis role="bold">VariantDir</emphasis>(). If this file isn't linked, it just returns the directory part of the filename.</para> @@ -5987,7 +5937,7 @@ it just returns the directory part of the filename.</para> <para>For example, the specified target will expand as follows for the corresponding modifiers:</para> -<literallayout remap='.nf'> +<literallayout> $TARGET => sub/dir/file.x ${TARGET.base} => sub/dir/file ${TARGET.dir} => sub/dir @@ -6022,13 +5972,13 @@ associated with a construction variable in the environment. The function should take four arguments: -<emphasis remap='I'>target</emphasis> +<emphasis>target</emphasis> - a list of target nodes, -<emphasis remap='I'>source</emphasis> +<emphasis>source</emphasis> - a list of source nodes, -<emphasis remap='I'>env</emphasis> +<emphasis>env</emphasis> - the construction environment, -<emphasis remap='I'>for_signature</emphasis> +<emphasis>for_signature</emphasis> - a Boolean value that specifies whether the function is being called for generating a build signature. @@ -6036,7 +5986,7 @@ SCons will insert whatever the called function returns into the expanded string:</para> -<programlisting remap='.nf'> +<programlisting> def foo(target, source, env, for_signature): return "bar" @@ -6057,7 +6007,7 @@ so that the arguments will be associated with the instantiation of the class:</para> -<literallayout remap='.nf'> +<literallayout> class foo(object): def __init__(self, arg): self.arg = arg @@ -6071,43 +6021,43 @@ env=Environment(FOO=foo, BAR="${FOO('my argument')} baz") <para>The special pseudo-variables -<emphasis remap='B'>$(</emphasis> +<emphasis role="bold">$(</emphasis> and -<emphasis remap='B'>$)</emphasis> +<emphasis role="bold">$)</emphasis> may be used to surround parts of a command line that may change -<emphasis remap='I'>without</emphasis> +<emphasis>without</emphasis> causing a rebuild--that is, which are not included in the signature of target files built with this command. All text between -<emphasis remap='B'>$(</emphasis> +<emphasis role="bold">$(</emphasis> and -<emphasis remap='B'>$)</emphasis> +<emphasis role="bold">$)</emphasis> will be removed from the command line before it is added to file signatures, and the -<emphasis remap='B'>$(</emphasis> +<emphasis role="bold">$(</emphasis> and -<emphasis remap='B'>$)</emphasis> +<emphasis role="bold">$)</emphasis> will be removed before the command is executed. For example, the command line:</para> -<literallayout remap='.nf'> +<literallayout> echo Last build occurred $( $TODAY $). > $TARGET </literallayout> <!-- .fi --> <para>would execute the command:</para> -<literallayout remap='.nf'> +<literallayout> echo Last build occurred $TODAY. > $TARGET </literallayout> <!-- .fi --> <para>but the command signature added to any target files would be:</para> -<literallayout remap='.nf'> +<literallayout> echo Last build occurred . > $TARGET </literallayout> <!-- .fi --> @@ -6116,21 +6066,21 @@ echo Last build occurred . > $TARGET <refsect2 id='python_code_substitution'><title>Python Code Substitution</title> <para>Any python code within -<emphasis remap='B'>${</emphasis>-<emphasis remap='B'>}</emphasis> +<emphasis role="bold">${</emphasis>-<emphasis role="bold">}</emphasis> pairs gets evaluated by python 'eval', with the python globals set to the current environment's set of construction variables. So in the following case:</para> -<literallayout remap='.nf'> +<literallayout> env['COND'] = 0 env.Command('foo.out', 'foo.in', <!-- '''echo ${COND==1 and 'FOO' or 'BAR'} > $TARGET''') --> </literallayout> <!-- .fi --> <para>the command executed will be either</para> -<literallayout remap='.nf'> +<literallayout> echo FOO > foo.out </literallayout> <!-- .fi --> <para>or</para> -<literallayout remap='.nf'> +<literallayout> echo BAR > foo.out </literallayout> <!-- .fi --> <para>according to the current value of env['COND'] when the command is @@ -6143,7 +6093,7 @@ BAR are environment variables, and their values are substituted into the final command. FOO is a list, so its elements are interpolated separated by spaces.</para> -<literallayout remap='.nf'> +<literallayout> env=Environment() env['COND'] = 0 env['FOO'] = ['foo1', 'foo2'] @@ -6158,7 +6108,7 @@ env.Command('foo.out', 'foo.in', <para>SCons uses the following rules when converting construction variables into command lines:</para> -<variablelist remap='IP'> +<variablelist> <varlistentry> <term>String</term> <listitem> @@ -6199,15 +6149,15 @@ a future version of SCons.</para> <refsect2 id='scanner_objects'><title>Scanner Objects</title> <para>You can use the -<emphasis remap='B'>Scanner</emphasis> +<emphasis role="bold">Scanner</emphasis> function to define objects to scan new file types for implicit dependencies. The -<emphasis remap='B'>Scanner</emphasis> +<emphasis role="bold">Scanner</emphasis> function accepts the following arguments:</para> -<variablelist remap='IP'> +<variablelist> <varlistentry> <term>function</term> <listitem> @@ -6230,16 +6180,16 @@ the function must take three or four arguments:</para> <para> def scanner_function(node, env, path, arg=None):</para> <para>The -<emphasis remap='B'>node</emphasis> +<emphasis role="bold">node</emphasis> argument is the internal SCons node representing the file. Use -<emphasis remap='B'>str(node)</emphasis> +<emphasis role="bold">str(node)</emphasis> to fetch the name of the file, and -<emphasis remap='B'>node.get_contents()</emphasis> +<emphasis role="bold">node.get_contents()</emphasis> to fetch contents of the file. Note that the file is -<emphasis remap='I'>not</emphasis> +<emphasis>not</emphasis> guaranteed to exist before the scanner is called, so the scanner function should check that if there's any chance that the scanned file @@ -6247,23 +6197,23 @@ might not exist (for example, if it's built from other files).</para> <para>The -<emphasis remap='B'>env</emphasis> +<emphasis role="bold">env</emphasis> argument is the construction environment for the scan. Fetch values from it using the -<emphasis remap='B'>env.Dictionary()</emphasis> +<emphasis role="bold">env.Dictionary()</emphasis> method.</para> <para>The -<emphasis remap='B'>path</emphasis> +<emphasis role="bold">path</emphasis> argument is a tuple (or list) of directories that can be searched for files. This will usually be the tuple returned by the -<emphasis remap='B'>path_function</emphasis> +<emphasis role="bold">path_function</emphasis> argument (see below).</para> <para>The -<emphasis remap='B'>arg</emphasis> +<emphasis role="bold">arg</emphasis> argument is the argument supplied when the scanner was created, if any.</para> @@ -6318,14 +6268,14 @@ a list of source nodes, and an optional argument supplied when the scanner was created. The -<emphasis remap='B'>path_function</emphasis> +<emphasis role="bold">path_function</emphasis> returns a tuple of directories that can be searched for files to be returned by this Scanner object. (Note that the -<emphasis remap='B'>FindPathDirs</emphasis>() +<emphasis role="bold">FindPathDirs</emphasis>() function can be used to return a ready-made -<emphasis remap='B'>path_function</emphasis> +<emphasis role="bold">path_function</emphasis> for a given construction variable name, instead of having to write your own function from scratch.)</para> @@ -6340,7 +6290,7 @@ Any strings or other objects returned by the scanner function that are not of this class will be run through the -<emphasis remap='B'>node_factory</emphasis> +<emphasis role="bold">node_factory</emphasis> function.</para> </listitem> @@ -6382,7 +6332,7 @@ only invoke the scanner on the file being scanned, and not (for example) also on the files specified by the #include lines in the file being scanned. -<emphasis remap='I'>recursive</emphasis> +<emphasis>recursive</emphasis> may be a callable function, in which case it will be called with a list of Nodes found and @@ -6397,18 +6347,18 @@ Nodes for additional scanning.</para> <para>Note that <command>scons</command> has a global -<emphasis remap='B'>SourceFileScanner</emphasis> +<emphasis role="bold">SourceFileScanner</emphasis> object that is used by the -<emphasis remap='B'>Object</emphasis>(), -<emphasis remap='B'>SharedObject</emphasis>(), +<emphasis role="bold">Object</emphasis>(), +<emphasis role="bold">SharedObject</emphasis>(), and -<emphasis remap='B'>StaticObject</emphasis>() +<emphasis role="bold">StaticObject</emphasis>() builders to decide which scanner should be used for different file extensions. You can using the -<emphasis remap='B'>SourceFileScanner.add_scanner</emphasis>() +<emphasis role="bold">SourceFileScanner.add_scanner</emphasis>() method to add your own Scanner object to the <command>scons</command> @@ -6417,7 +6367,7 @@ that builds target programs or libraries from a list of source files of different types:</para> -<programlisting remap='.nf'> +<programlisting> def xyz_scan(node, env, path): contents = node.get_text_contents() # Scan the contents and return the included files. @@ -6474,7 +6424,7 @@ such as Windows, SCons treats a file with a <markup>.F</markup> suffix as a Fortran source file that should -<emphasis remap='I'>not</emphasis> +<emphasis>not</emphasis> be run through the C preprocessor.</para> </refsect2> @@ -6518,7 +6468,7 @@ to run SCons.</para> <refsect2 id='windows_sconsbat_file'><title>Windows: scons.bat file</title> <para>On Windows systems, SCons is executed via a wrapper -<emphasis remap='B'>scons.bat</emphasis> +<emphasis role="bold">scons.bat</emphasis> file. This has (at least) two ramifications:</para> @@ -6528,7 +6478,7 @@ on the command line may have to put double quotes around the assignments:</para> -<literallayout remap='.nf'> +<literallayout> scons "FOO=BAR" "BAZ=BLEH" </literallayout> <!-- .fi --> @@ -6539,11 +6489,11 @@ as an command issued at the command-line prompt. You can work around this either by executing -<emphasis remap='B'>scons.bat</emphasis> +<emphasis role="bold">scons.bat</emphasis> from the Cygwin command line, or by creating a wrapper shell script named -<emphasis remap='B'>scons .</emphasis></para> +<emphasis role="bold">scons .</emphasis></para> </refsect2> @@ -6558,7 +6508,7 @@ directories in the PATH variable. If you have both MSVC and MinGW installed and you want to use MinGW instead of MSVC, then you must explictly tell SCons to use MinGW by passing</para> -<literallayout remap='.nf'> +<literallayout> tools=['mingw'] </literallayout> <!-- .fi --> @@ -6575,7 +6525,7 @@ this section contains a brief overview of some common tasks.</para> <refsect2 id='basic_compilation_from_a_single_source_f'><title>Basic Compilation From a Single Source File</title> -<literallayout remap='.nf'> +<literallayout> env = Environment() env.Program(target = 'foo', source = 'foo.c') </literallayout> <!-- .fi --> @@ -6589,7 +6539,7 @@ or by specifying a dot ("scons .").</para> <refsect2 id='basic_compilation_from_multiple_source_f'><title>Basic Compilation From Multiple Source Files</title> -<literallayout remap='.nf'> +<literallayout> env = Environment() env.Program(target = 'foo', source = Split('f1.c f2.c f3.c')) </literallayout> <!-- .fi --> @@ -6598,7 +6548,7 @@ env.Program(target = 'foo', source = Split('f1.c f2.c f3.c')) <refsect2 id='setting_a_compilation_flag'><title>Setting a Compilation Flag</title> -<literallayout remap='.nf'> +<literallayout> env = Environment(CCFLAGS = '-g') env.Program(target = 'foo', source = 'foo.c') </literallayout> <!-- .fi --> @@ -6608,11 +6558,11 @@ env.Program(target = 'foo', source = 'foo.c') <refsect2 id='search_the_local_directory_for_h_files'><title>Search The Local Directory For .h Files</title> <para>Note: You do -<emphasis remap='I'>not</emphasis> +<emphasis>not</emphasis> need to set CCFLAGS to specify -I options by hand. SCons will construct the right -I options from CPPPATH.</para> -<literallayout remap='.nf'> +<literallayout> env = Environment(CPPPATH = ['.']) env.Program(target = 'foo', source = 'foo.c') </literallayout> <!-- .fi --> @@ -6621,7 +6571,7 @@ env.Program(target = 'foo', source = 'foo.c') <refsect2 id='search_multiple_directories_for_h_files'><title>Search Multiple Directories For .h Files</title> -<literallayout remap='.nf'> +<literallayout> env = Environment(CPPPATH = ['include1', 'include2']) env.Program(target = 'foo', source = 'foo.c') </literallayout> <!-- .fi --> @@ -6630,7 +6580,7 @@ env.Program(target = 'foo', source = 'foo.c') <refsect2 id='building_a_static_library'><title>Building a Static Library</title> -<literallayout remap='.nf'> +<literallayout> env = Environment() env.StaticLibrary(target = 'foo', source = Split('l1.c l2.c')) env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c']) @@ -6640,7 +6590,7 @@ env.StaticLibrary(target = 'bar', source = ['l3.c', 'l4.c']) <refsect2 id='building_a_shared_library'><title>Building a Shared Library</title> -<literallayout remap='.nf'> +<literallayout> env = Environment() env.SharedLibrary(target = 'foo', source = ['l5.c', 'l6.c']) env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c')) @@ -6650,7 +6600,7 @@ env.SharedLibrary(target = 'bar', source = Split('l7.c l8.c')) <refsect2 id='linking_a_local_library_into_a_program'><title>Linking a Local Library Into a Program</title> -<literallayout remap='.nf'> +<literallayout> env = Environment(LIBS = 'mylib', LIBPATH = ['.']) env.Library(target = 'mylib', source = Split('l1.c l2.c')) env.Program(target = 'prog', source = ['p1.c', 'p2.c']) @@ -6664,7 +6614,7 @@ env.Program(target = 'prog', source = ['p1.c', 'p2.c']) you can leave off the target file suffix, and SCons will add it automatically.</para> -<literallayout remap='.nf'> +<literallayout> bld = Builder(action = 'pdftex < $SOURCES > $TARGET' suffix = '.pdf', src_suffix = '.tex') @@ -6685,7 +6635,7 @@ env.Object(), env.StaticLibrary(), etc.</para> <refsect2 id='adding_your_own_builder_object_to_an_env'><title>Adding Your Own Builder Object to an Environment</title> -<literallayout remap='.nf'> +<literallayout> bld = Builder(action = 'pdftex < $SOURCES > $TARGET' suffix = '.pdf', src_suffix = '.tex') @@ -6698,7 +6648,7 @@ env.Program(target = 'bar', source = 'bar.c') <para>You also can use other Pythonic techniques to add to the BUILDERS construction variable, such as:</para> -<literallayout remap='.nf'> +<literallayout> env = Environment() env['BUILDERS]['PDFBuilder'] = bld </literallayout> <!-- .fi --> @@ -6708,17 +6658,17 @@ env['BUILDERS]['PDFBuilder'] = bld <refsect2 id='defining_your_own_scanner_object'><title>Defining Your Own Scanner Object</title> <para>The following example shows an extremely simple scanner (the -<emphasis remap='B'>kfile_scan</emphasis>() +<emphasis role="bold">kfile_scan</emphasis>() function) that doesn't use a search path at all and simply returns the file names present on any -<emphasis remap='B'>include</emphasis> +<emphasis role="bold">include</emphasis> lines in the scanned file. This would implicitly assume that all included files live in the top-level directory:</para> -<literallayout remap='.nf'> +<literallayout> import re include_re = re.compile(r'^include\s+(\S+)$', re.M) @@ -6746,18 +6696,18 @@ bar_in.target_scanner = kscan have to return a list of File nodes from the scan function, simple strings for the file names won't do. As in the examples we are showing here, you can use the -<emphasis remap='B'>File()</emphasis> +<emphasis role="bold">File()</emphasis> function of your current Environment in order to create nodes on the fly from a sequence of file names with relative paths.</para> <para>Here is a similar but more complete example that searches a path of directories (specified as the -<emphasis remap='B'>MYPATH</emphasis> +<emphasis role="bold">MYPATH</emphasis> construction variable) for files that actually exist:</para> -<programlisting remap='.nf'> +<programlisting> import re import os include_re = re.compile(r'^include\s+(\S+)$', re.M) @@ -6790,26 +6740,26 @@ env.Command('foo', 'foo.x', 'xprocess < $SOURCES > $TARGET') </programlisting> <!-- .fi --> <para>The -<emphasis remap='B'>FindPathDirs</emphasis>() +<emphasis role="bold">FindPathDirs</emphasis>() function used in the previous example returns a function (actually a callable Python object) that will return a list of directories specified in the -<emphasis remap='B'>$MYPATH</emphasis> +<emphasis role="bold">$MYPATH</emphasis> construction variable. It lets SCons detect the file -<emphasis remap='B'>incs/foo.inc</emphasis> +<emphasis role="bold">incs/foo.inc</emphasis> , even if -<emphasis remap='B'>foo.x</emphasis> +<emphasis role="bold">foo.x</emphasis> contains the line -<emphasis remap='B'>include foo.inc</emphasis> +<emphasis role="bold">include foo.inc</emphasis> only. If you need to customize how the search path is derived, you would provide your own -<emphasis remap='B'>path_function</emphasis> +<emphasis role="bold">path_function</emphasis> argument when creating the Scanner object, as follows:</para> -<programlisting remap='.nf'> +<programlisting> # MYPATH is a list of directories to search for files in def pf(env, dir, target, source, arg): top_dir = Dir('#').abspath @@ -6835,7 +6785,7 @@ scanner = Scanner(name = 'myscanner', SConscript file are relative to that subdirectory.</para> -<programlisting remap='.nf'> +<programlisting> SConstruct: env = Environment() @@ -6865,7 +6815,7 @@ sub/dir/SConscript: <para>You must explicitly Export() and Import() variables that you want to share between SConscript files.</para> -<programlisting remap='.nf'> +<programlisting> SConstruct: env = Environment() @@ -6889,7 +6839,7 @@ the SConscript function to establish one or more separate variant build directory trees for a given source directory:</para> -<programlisting remap='.nf'> +<programlisting> SConstruct: cppdefines = ['FOO'] @@ -6915,7 +6865,7 @@ value each time we call the SConscript function.</para> <refsect2 id='hierarchical_build_of_two_libraries_link'><title>Hierarchical Build of Two Libraries Linked With a Program</title> -<programlisting remap='.nf'> +<programlisting> SConstruct: env = Environment(LIBPATH = ['#libA', '#libB']) @@ -6958,7 +6908,7 @@ prefix and suffix for the current platform <para>The following would allow the C compiler to be specified on the command line or in the file custom.py.</para> -<literallayout remap='.nf'> +<literallayout> vars = Variables('custom.py') vars.Add('CC', 'The C compiler.') env = Environment(variables=vars) @@ -6967,19 +6917,19 @@ Help(vars.GenerateHelpText(env)) <para>The user could specify the C compiler on the command line:</para> -<literallayout remap='.nf'> +<literallayout> scons "CC=my_cc" </literallayout> <!-- .fi --> <para>or in the custom.py file:</para> -<literallayout remap='.nf'> +<literallayout> CC = 'my_cc' </literallayout> <!-- .fi --> <para>or get documentation on the options:</para> -<literallayout remap='.nf'> +<literallayout> $ scons -h CC: The C compiler. @@ -7003,32 +6953,32 @@ include "StdAfx.h" as the first header in all the source files you are compiling to object files. For example:</para> <para>StdAfx.h:</para> -<literallayout remap='.nf'> +<literallayout> #include <windows.h> #include <my_big_header.h> </literallayout> <!-- .fi --> <para>StdAfx.cpp:</para> -<literallayout remap='.nf'> +<literallayout> #include <StdAfx.h> </literallayout> <!-- .fi --> <para>Foo.cpp:</para> -<literallayout remap='.nf'> +<literallayout> #include <StdAfx.h> /* do some stuff */ </literallayout> <!-- .fi --> <para>Bar.cpp:</para> -<literallayout remap='.nf'> +<literallayout> #include <StdAfx.h> /* do some other stuff */ </literallayout> <!-- .fi --> <para>SConstruct:</para> -<literallayout remap='.nf'> +<literallayout> env=Environment() env['PCHSTOP'] = 'StdAfx.h' env['PCH'] = env.PCH('StdAfx.cpp')[0] @@ -7050,7 +7000,7 @@ file. SCons supports PDB files through the PDB construction variable.</para> <para>SConstruct:</para> -<literallayout remap='.nf'> +<literallayout> env=Environment() env['PDB'] = 'MyApp.pdb' env.Program('MyApp', ['Foo.cpp', 'Bar.cpp']) @@ -7062,7 +7012,7 @@ env.Program('MyApp', ['Foo.cpp', 'Bar.cpp']) </refsect1> <refsect1 id='environment'><title>ENVIRONMENT</title> -<variablelist remap='IP'> +<variablelist> <varlistentry> <term>SCONS_LIB_DIR</term> <listitem> diff --git a/doc/man/sconsign.xml b/doc/man/sconsign.xml index 99bfd11..8f4a854 100644 --- a/doc/man/sconsign.xml +++ b/doc/man/sconsign.xml @@ -69,7 +69,7 @@ Each entry is printed in the following format:</para> implicit_dependency_2: signature timestamp length action_signature [action string]</para> -<para><emphasis remap='B'>None</emphasis> +<para><emphasis role="bold">None</emphasis> is printed in place of any missing timestamp, bsig, or csig values for @@ -82,7 +82,7 @@ the lines are simply omitted.</para> <para>By default, <command>sconsign</command> assumes that any -<emphasis remap='I'>file</emphasis> +<emphasis>file</emphasis> arguments that end with a <markup>.dbm</markup> suffix contains @@ -90,10 +90,10 @@ signature entries for more than one directory (that is, was specified by the -<emphasis remap='B'>SConsignFile ()</emphasis> +<emphasis role="bold">SConsignFile ()</emphasis> function). Any -<emphasis remap='I'>file</emphasis> +<emphasis>file</emphasis> argument that does not end in <markup>.dbm</markup> is assumed to be a traditional @@ -113,7 +113,7 @@ options.</para> <para>Various options control what information is printed and the format:</para> -<variablelist remap='TP'> +<variablelist> <varlistentry> <term>-a, --act, --action</term> <listitem> @@ -144,7 +144,7 @@ options are used, prints information about only the signatures for entries in the specified -<emphasis remap='I'>DIRECTORY</emphasis>.</para> +<emphasis>DIRECTORY</emphasis>.</para> </listitem> </varlistentry> @@ -152,10 +152,10 @@ for entries in the specified <term>-e ENTRY, --entry=ENTRY</term> <listitem> <para>Prints information about only the specified -<emphasis remap='I'>ENTRY</emphasis>. +<emphasis>ENTRY</emphasis>. Multiple -e options may be used, in which case information about each -<emphasis remap='I'>ENTRY</emphasis> +<emphasis>ENTRY</emphasis> is printed in the order in which the options are specified on the command line.</para> @@ -166,12 +166,12 @@ options are specified on the command line.</para> <listitem> <para>The file(s) to be printed are in the specified -<emphasis remap='I'>FORMAT</emphasis>. +<emphasis>FORMAT</emphasis>. Legal values are -<emphasis remap='B'>dbm</emphasis> +<emphasis role="bold">dbm</emphasis> (the DBM format used when the -<emphasis remap='B'>SConsignFile</emphasis>() +<emphasis role="bold">SConsignFile</emphasis>() function is used) or <command>sconsign</command> @@ -235,7 +235,7 @@ for all entries or the specified entries.</para> </refsect1> <refsect1 id='environment'><title>ENVIRONMENT</title> -<variablelist remap='IP'> +<variablelist> <varlistentry> <term>SCONS_LIB_DIR</term> <listitem> @@ -249,12 +249,12 @@ on the command line.</para> </refsect1> <refsect1 id='see_also'><title>SEE ALSO</title> -<para><emphasis remap='B'>scons</emphasis>, -<emphasis remap='B'>scons</emphasis> +<para><emphasis role="bold">scons</emphasis>, +<emphasis role="bold">scons</emphasis> User Manual, -<emphasis remap='B'>scons</emphasis> +<emphasis role="bold">scons</emphasis> Design Document, -<emphasis remap='B'>scons</emphasis> +<emphasis role="bold">scons</emphasis> source code.</para> </refsect1> |