#
$doc_tar_gz = "#build/dist/scons-doc-$version.tar.gz";
+#
+# We'll only try to build text files (for some documents)
+# if lynx is available to do the dump.
+#
+$lynx = cons::whereis('lynx');
+
#
# Always create a version.sgml file containing the version information
# for this run. Ignore it for dependency purposes so we don't
Ignore("version.sgml");
#
-# Each document will live in its own subdirectory. List them here.
+# Each document will live in its own subdirectory. List them here
+# as hash keys, with a hash of the info to control its build.
#
-@doc_dirs = qw(
- design
+%doc_dirs = (
+ 'design' => {
+ 'html' => 'book1.html',
+ },
+ 'man' => {
+ 'html' => 'scons.html',
+ 'text' => 1,
+ },
);
# Find internal dependencies in .sgml files:
# For each document, build the document itself in HTML, Postscript,
# and PDF formats.
#
-foreach $doc (@doc_dirs) {
+foreach $doc (keys %doc_dirs) {
my $main = "$doc/main.sgml";
my $out = "main.out";
my $htmldir = "HTML/scons-$doc";
+ my $html = "$htmldir/" . $doc_dirs{$doc}->{'html'};
my $ps = "PS/scons-$doc.ps";
my $pdf = "PDF/scons-$doc.pdf";
+ my $text = "TEXT/scons-$doc.txt";
$env->QuickScan(\&scansgml, $main);
- $env->Command("$htmldir/book1.html", $main,
- qq(jw -b html -o %>:d %<));
+ $env->Command($html, $main,
+ [qq(rm -f %>:d/*.html),
+ qq(jw -b html -o %>:d %<),
+ ]);
$env->Command($ps, $main,
[qq(rm -f %>:d/$out),
qq(rm -f %>:d/$out),
]);
- push(@tar_deps, "$htmldir/book1.html", $ps, $pdf);
+ if ($doc_dirs{$doc}->{'text'} && $lynx) {
+ $env->Command($text, $html, qq(lynx -dump %<:a > %>));
+ }
+
+ push(@tar_deps, $html, $ps, $pdf);
push(@tar_list, "$htmldir/[A-Za-z]*", $ps, $pdf);
}
--- /dev/null
+<!--
+
+ Copyright 2001 Steven Knight
+
+-- >
+
+ <para>
+
+ The &scons; utility builds software (or other files)
+ by determining which component pieces must be rebuilt
+ and executing the necessary commands to rebuild them.
+
+ </para>
+
+ <para>
+
+ By default, &scons; reads configuration information from the
+ file named <filename>SConstruct</filename> in the current
+ directory. An alternate file name may be specified via the
+ <option>-f</option> option. If the alternate file is not in
+ the local directory, &scons; will internally change its working
+ directory (chdir) to the directory containing the file.
+
+ </para>
+
+ <para>
+
+ The configuration file specifies the files to be built, and
+ (optionally) the rules to build those files. Reasonable default
+ rules exist for building common software components (executable
+ programs, object files, libraries), so that for simple software
+ projects, only the target and input files need be specified.
+
+ <!--
+ See
+ .IR scconsfile (5)
+ for information about the contents of
+ &scons;
+ configuration files.
+ -- >
+
+ </para>
+
+ <para>
+
+ &scons; can scan known input files automatically for dependency
+ information (for example, <literal>#include</literal> statements
+ in C or C++ files) and will rebuild dependent files appropriately
+ whenever any "included" input file changes. &scons; supports the
+ ability to define new scanners for unknown input file types.
+
+ </para>
+
+ <para>
+
+ &scons; is normally executed in a top-level directory containing a
+ &SConstruct; file, specifying the target or targets to be built as
+ command-line arguments. The command
+
+ </para>
+
+ <screen>
+ scons .
+ </screen>
+
+ <para>
+
+ will build all target files in or below the current directory
+ ( <filename>.</filename>).
+
+ </para>
+
+ <screen>
+ scons /
+ </screen>
+
+ <para>
+
+ will build all target files in or below the root directory (i.e.,
+ all files). Specific targets may be supplied:
+
+ </para>
+
+ <screen>
+ scons foo bar
+ </screen>
+
+ <para>
+
+ Targets may be omitted from the command line,
+ in which case the targets specified
+ in the configuration file(s) as
+ <function>Default</function>
+ targets will be built:
+
+ </para>
+
+ <screen>
+ scons
+ </screen>
+
+ <para>
+
+ Specifying "cleanup" targets in configuration files is not
+ necessary. The <option>-c</option> flag removes all files
+ necessary to build the specified target:
+
+ </para>
+
+ <screen>
+ # removes all target files
+ scons -c .
+
+ # removes all target files under the specified subdirectories
+ scons -c build export
+ </screen>
+
+ <para>
+
+ A subset of a hierarchical tree may be built by:
+
+ </para>
+
+ <orderedlist>
+ <listitem>
+ <para>
+ remaining at the top-level directory (where the &SConstruct;
+ file lives) and specifying the subdirectory as the target to be
+ built:
+ </para>
+ <screen>
+ scons src/subdir
+ </screen>
+ </listitem>
+ <listitem>
+ <para>
+ changing directory and invoking sccons with the
+ <option>-u</option> option, which traverses up the directory
+ hierarchy until it finds the &SConstruct; file, and then builds
+ targets relatively to the current subdirectory:
+ </para>
+ <screen>
+ cd src/subdir
+ scons -u .
+ </screen>
+ </listitem>
+ </orderedlist>
+
+ <para>
+
+ &scons; supports building multiple targets in parallel via a
+ <option>-j</option> option that takes, as its argument, the number
+ of simultaneous tasks that may be spawned:
+
+ </para>
+
+ <screen>
+ # build four targets in parallel
+ &scons; -j 4
+ </screen>
+
+
+ <para>
+
+ Values of variables to be passed to the configuration file(s)
+ may be specified on the command line:
+
+ </para>
+
+ <screen>
+ &scons; debug=1 .
+ </screen>
+
+ <para>
+
+ These variables can be used in the configuration file(s) to modify
+ the build in any way.
+
+ </para>
+
+ <para>
+
+ &scons; can maintain a cache of target (derived) files that can
+ be shared between multiple builds. When caching is enabled in a
+ configuration file, any target files built by &scons; will be copied
+ to the cache. If an up-to-date target file is found in the cache, it
+ will be retrieved from the cache instead of being rebuilt locally.
+ Caching behavior may be disabled and controlled in other ways by the
+ <option>--cache-force</option>, <option>--cache-disable</option>,
+ and <option>--cache-show</option> command-line options. The
+ <option>--random</option> is useful whenever multiple builds may be
+ trying to update the cache simultaneously.
+
+ </para>
--- /dev/null
+<!--
+
+ Copyright 2001 Steven Knight
+
+-- >
+
+<para>
+
+ In general, &scons; supports the same command-line options as GNU
+ &Make;, and many of those supported by &Cons;.
+
+</para>
+
+<variablelist>
+
+ <varlistentry>
+ <term>
+ <option>-b</option>
+ </term>
+ <listitem>
+ <para>
+
+ Ignored for compatibility with non-GNU versions of
+ <application>make</application>.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-c</option>,
+ <option>--clean</option>,
+ <option>--remove</option>
+ </term>
+ <listitem>
+ <para>
+
+ Clean up by removing all target files for which a construction
+ command is specified.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <!--
+
+ <varlistentry>
+ <term>
+ <option>- -cache-disable</option>,
+ <option>- -no-cache</option>
+ </term>
+ <listitem>
+ <para>
+
+ Disable caching. Will neither retrieve files from cache nor flush
+ files to cache. Has no effect if use of caching is not specified
+ in a configuration file.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>- -cache-force</option>,
+ <option>- -cache-populate</option>
+ </term>
+ <listitem>
+ <para>
+
+ Populate a cache by forcing any already-existing up-to-date
+ target files to the cache, in addition to files built by this
+ invocation. This is useful to populate a new cache with
+ appropriate target files, or to make available in the cache
+ any target files recently built with caching disabled via the
+ <option>- -cache-disable</option> option.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>- -cache-show</option>
+ </term>
+ <listitem>
+ <para>
+
+ When retrieving a target file from a cache, show the command
+ that would have been executed to build the file. This produces
+ consistent output for build logs, regardless of whether a target
+ file was rebuilt or retrieved from cache.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ -->
+
+ <varlistentry>
+ <term>
+ <option>-C</option> <replaceable>directory</replaceable>,
+ <option>--directory=</option><replaceable>directory</replaceable>
+ </term>
+ <listitem>
+ <para>
+
+ Change to the specified <replaceable>directory</replaceable>
+ before reading <filename>SConstruct</filename> or doing
+ anything else. Multiple <option>-C</option> options are
+ interpreted relative to the previous one. (This is nearly
+ equivalent to <literal>-f directory/SConstruct</literal>,
+ except that it will search for <filename>SConstruct</filename>,
+ <filename>Sconstruct</filename>, or
+ <filename>sconstruct</filename> in the directory.)
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-d</option>
+ </term>
+ <listitem>
+ <para>
+
+ Display dependencies while building target files. Useful for
+ figuring out why a specific file is being rebuilt, as well as
+ general debugging of the build process.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>--debug</option>=<replaceable>flags</replaceable>
+ </term>
+ <listitem>
+ <para>
+
+ Print debugging information. ???
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term> <option>-e</option>,
+ <option>--environment-overrides</option>
+ </term>
+ <listitem>
+ <para>
+
+ Variables from the execution environment override construction
+ variables from the configuration files.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-f</option> <replaceable>file</replaceable>,
+ <option>--file</option>=<replaceable>file</replaceable>,
+ <option>--makefile</option>=<replaceable>file</replaceable>,
+ <option>--sconstruct</option>=<replaceable>file</replaceable>
+ </term>
+ <listitem>
+ <para>
+
+ Use <replaceable>file</replaceable> as the initial configuration
+ file. If <replaceable>file</replaceable> is in another directory,
+ &scons; will change to that directory before building targets.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-h</option>,
+ <option>--help</option>
+ </term>
+ <listitem>
+ <para>
+
+ Print command-line help message and exit.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-H</option>,
+ <option>--help-local</option>,
+ <option>--local-help</option>
+ </term>
+ <listitem>
+ <para>
+
+ Display a local help message for this build, if one is defined in
+ the configuration file(s).
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-i</option>,
+ <option>--ignore-errors</option>,
+ </term>
+ <listitem>
+ <para>
+
+ Ignore all errors from commands executed to rebuild files.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-I</option> <replaceable>directory</replaceable>,
+ <option>--include-dir</option>=<replaceable>directory</replaceable>
+ </term>
+ <listitem>
+ <para>
+
+ Specifies a <replaceable>directory</replaceable> to search for
+ imported Python modules. If several <option>-I</option> options
+ are used, the directories are searched in the order specified.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-j</option> <replaceable>N</replaceable>,
+ <option>--jobs</option>=<replaceable>N</replaceable>
+ </term>
+ <listitem>
+ <para>
+
+ Specifies the number of jobs (commands) to run simultaneously.
+ If there is more than one <option>-j</option> option,
+ the last one is effective.
+ <!--
+ ??? If the <option>-j</option> option
+ is specified without an argument,
+ &scons; will not limit the number of
+ simultaneous jobs.
+ -->
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-k</option>,
+ <option>--keep-going</option>,
+ </term>
+ <listitem>
+ <para>
+
+ Continue as much as possible after an error. The target that
+ failed and those that depend on it will not be remade, but other
+ targets specified on the command line will still be processed.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-l</option>,
+ <option>--load-average</option>=<replaceable>N</replaceable>,
+ <option>--max-load</option>=<replaceable>N</replaceable>
+ </term>
+ <listitem>
+ <para>
+
+ No new jobs (commands) will be started if
+ there are other jobs running and the system load
+ average is at least <replaceable>N</replaceable>
+ (a floating-point number).
+
+ <!--
+ ???
+ With no argument, removes a previous load limit.
+ -->
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>--list-derived</option>
+ </term>
+ <listitem>
+ <para>
+
+ List derived files (targets, dependencies) that would be built,
+ but do not build them.
+ [XXX This can probably go away with the right
+ combination of other options. Revisit this issue.]
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>--list-actions</option>
+ </term>
+ <listitem>
+ <para>
+
+ List derived files that would be built, with the actions
+ (commands) that build them. Does not build the files.
+ [XXX This can probably go away with the right
+ combination of other options. Revisit this issue.]
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>--list-where</option>
+ </term>
+ <listitem>
+ <para>
+
+ List derived files that would be built, plus where the file is
+ defined (file name and line number). Does not build the files.
+ [XXX This can probably go away with the right
+ combination of other options. Revisit this issue.]
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-m</option>
+ </term>
+ <listitem>
+ <para>
+
+ Ignored for compatibility with non-GNU versions of
+ <application>make</application>.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-n</option>,
+ <option>--just-print</option>,
+ <option>--dry-run</option>,
+ <option>--recon</option>
+ </term>
+ <listitem>
+ <para>
+
+ No execute. Print the commands that would be executed to build
+ any out-of-date target files, but do not execute the commands.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-o</option> <replaceable>file</replaceable>,
+ <option>--old-file</option>=<replaceable>file</replaceable>,
+ <option>--assume-old</option>=<replaceable>file</replaceable>
+ </term>
+ <listitem>
+ <para>
+
+ Do not rebuild <replaceable>file</replaceable>, and do
+ not rebuild anything due to changes in the contents of
+ <replaceable>file</replaceable>.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <!--
+
+ <varlistentry>
+ <term>
+ <option>- -override</option> <replaceable>file</replaceable>
+ </term>
+ <listitem>
+ <para>
+
+ Read values to override specific build environment variables
+ from the specified <replaceable>file</replaceable>.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ -->
+
+ <!--
+
+ <varlistentry>
+ <term>
+ <option>-p</option>
+ </term>
+ <listitem>
+ <para>
+
+ Print the data base (construction environments,
+ Builder and Scanner objects) that are defined
+ after reading the configuration files.
+ After printing, a normal build is performed
+ as usual, as specified by other command-line options.
+ This also prints version information
+ printed by the <option>-v</option> option.
+
+ <!- -
+ ???
+ To print the data base without trying
+ to rebuild any files,
+ use <literal>scons -p -f /dev/null</literal>.
+ - ->
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ -->
+
+ <varlistentry>
+ <term>
+ <option>-q</option>,
+ <option>--question</option>
+ </term>
+ <listitem>
+ <para>
+
+ Do not run any commands, or print anything. Just return an exit
+ status that is zero if the specified targets are already up to
+ date, nonzero otherwise.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <!--
+
+ <varlistentry>
+ <term>
+ <option>-r</option>,
+ <option>- -no-builtin-rules</option>,
+ <option>-R</option>,
+ <option>- -no-builtin-variables</option>
+ </term>
+ <listitem>
+ <para>
+
+ Clear the default construction variables. Construction
+ environments that are created will be completely empty.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ -->
+
+ <varlistentry>
+ <term>
+ <option>--random</option>
+ </term>
+ <listitem>
+ <para>
+
+ Build dependencies in a random order. This is useful when
+ building multiple trees simultaneously with caching enabled as a
+ way to prevent multiple builds from simultaneously trying to build
+ or retrieve the same target files.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-s</option>,
+ <option>--silent</option>,
+ <option>--quiet</option>
+ </term>
+ <listitem>
+ <para>
+
+ Silent. Do not print commands that are executed to rebuild
+ target files.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-S</option>,
+ <option>--no-keep-going</option>,
+ <option>--stop</option>
+ </term>
+ <listitem>
+ <para>
+
+ Ignored for compatibility with GNU <application>make</application>.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-t</option>
+ </term>
+ <listitem>
+ <para>
+
+ Ignored for compatibility with GNU
+ <application>make</application>. (Touching a file to make it
+ appear up-to-date is unnecessary when using &scons;.)
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <!--
+
+ <varlistentry>
+ <term>
+ <option>-u</option>
+ </term>
+ <listitem>
+ <para>
+
+ Traverse up directories until an <filename>SConstruct</filename>
+ or <filename>sconstruct</filename> file is found, and use that
+ as the top of the directory tree. Only targets at or below the
+ current directory will be built.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ -->
+
+ <varlistentry>
+ <term>
+ <option>-v</option>
+ </term>
+ <listitem>
+ <para>
+
+ Print the &scons; version, copyright information,
+ list of authors, and any other relevant information.
+ Then exit.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>-w</option>,
+ <option>--print-directory</option>,
+ </term>
+ <listitem>
+ <para>
+
+ Print a message containing the working directory before and
+ after other processing.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>
+ <option>--no-print-directory</option>
+ </term>
+ <listitem>
+ <para>
+
+ Turn off -w, even if it was turned on implicitly.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <!--
+
+ <varlistentry>
+ <term>
+ <option>- -write-filenames</option> <replaceable>file</replaceable>
+ </term>
+ <listitem>
+ <para>
+
+ Write all filenames considered into
+ <replaceable>file</replaceable>.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ -->
+
+ <!--
+
+ <varlistentry>
+ <term>
+ <option>-W</option> <replaceable>file</replaceable>,
+ <option>- -what-if</option>=<replaceable>file</replaceable>,
+ <option>- -new-file</option>=<replaceable>file</replaceable>,
+ <option>- -assume-new</option>=<replaceable>file</replaceable>
+ </term>
+ <listitem>
+ <para>
+
+ Pretend that the target <replaceable>file</replaceable> has been
+ modified. When used with the <option>-n</option> option, this
+ show you what would be rebuilt if you were to modify that file.
+ Without <option>-n</option>... what? XXX
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ -->
+
+ <varlistentry>
+ <term>
+ <option>--warn-undefined-variables</option>
+ </term>
+ <listitem>
+ <para>
+
+ Warn when an undefined variable is referenced.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ <!--
+
+ <varlistentry>
+ <term>
+ <option>-Y</option> <replaceable>repository</replaceable>,
+ <option>- -repository</option> <replaceable>repository</replaceable>
+ </term>
+ <listitem>
+ <para>
+
+ Search the specified repository for any input and target
+ files not found in the local directory hierarchy. Multiple
+ <option>-Y</option> options may specified, in which case the
+ repositories are searched in the order specified.
+
+ </para>
+ </listitem>
+ </varlistentry>
+
+ -->
+
+</variablelist>
projects / scons.git / commitdiff