Add a man page.

1 files changed, 194 insertions, 0 deletions

diff --git a/doc/man/desc.sgml b/doc/man/desc.sgml
new file mode 100644
index 0000000..da2961e
--- /dev/null
+++ b/doc/man/desc.sgml
@@ -0,0 +1,194 @@
+<!--
+
+  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>