Intergrate Kess' configure docs in the docs tree and,

in particular, integrate them into install.xml by removing
large chunks of that document and making it a summary
with pointers into configure.xml.

(I also snuck in the odd fix to both install.xml and
configure.xml.  Sorry for the mix.)


git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@103154 13f79535-47bb-0310-9956-ffa450edef68

1 files changed, 65 insertions, 343 deletions

diff --git a/docs/manual/install.xml b/docs/manual/install.xml
index 664df12ae0..bb84a123cc 100644
--- a/docs/manual/install.xml
+++ b/docs/manual/install.xml
@@ -44,6 +44,7 @@
 
 </summary>
 
+<seealso><a href="programs/configure.html">Configure the source tree</a></seealso>
 <seealso><a href="invoking.html">Starting Apache</a></seealso>
 <seealso><a href="stopping.html">Stopping and Restarting</a></seealso>
 
@@ -165,55 +166,22 @@
 
     <p>Apache can be downloaded from the <a
     href="http://httpd.apache.org/download.cgi">Apache HTTP Server
-    download site</a> which lists several mirrors. You'll find here
-    the latest stable release.</p>
-
-    <p>After downloading, especially if a mirror site is used, it
-    is important to verify that you have a complete and unmodified
-    version of the Apache HTTP Server. This can be accomplished by
-    testing the downloaded tarball against the PGP signature. This,
-    in turn, is a two step procedure. First, you must obtain the
-    <a href="http://www.apache.org/dist/httpd/KEYS"><code>KEYS</code></a>
-    file from the Apache distribution site, too. (To assure that the
-    <code>KEYS</code> file itself has not been modified, it may be a good
-    idea to use a file from a previous distribution of Apache or import
-    the keys from a public key server.) The keys are imported into
-    your personal key ring using one of the following commands (depending
-    on your pgp version):</p>
-
-<example>$ pgp &lt; KEYS</example>
-
-    <p>or </p>
-
-<example>$ gpg --import KEYS</example>
-
-    <p>The next step is to test the tarball against the PGP
-    signature, which should always be obtained from the <a
-    href="http://httpd.apache.org/download.cgi">main Apache
-    website</a>. A link to the signature file is placed behind the
-    corresponding download link or may be found in the particular
-    directory at the <a href="http://www.apache.org/dist/httpd/">Apache
-    distribution site</a>. Its filename is identical to the source
-    tarball with the addition of <code>.asc</code>. Then you can check
-    the distribution with one of the following commands (again,
-    depending on your pgp version):</p>
-
-<example>$ pgp httpd-2_1_<em>NN</em>.tar.gz.asc</example>
-
-    <p>or</p>
-
-<example>$ gpg --verify httpd-2_1_<em>NN</em>.tar.gz.asc</example>
-
-    <p>You should receive a message like</p>
-
-<example>Good signature from user "Martin Kraemer
-      &lt;martin@apache.org&gt;".</example>
-
-    <p>Depending on the trust relationships contained in your key
-    ring, you may also receive a message saying that the
-    relationship between the key and the signer of the key cannot
-    be verified. This is not a problem if you trust the
-    authenticity of the <code>KEYS</code> file.</p>
+    download site</a> which lists several mirrors.  Most users of
+    Apache on unix-like systems will be better off downloading and
+    compiling a source version.  The build process (described below) is
+    easy, and it allows you to customize your server to suit your needs.
+    In addition, binary releases are often not up to date with the latest
+    source releases.  If you do download a binary, follow the instructions
+    in the <code>INSTALL.bindist</code> file inside the distribution.</p>
+
+    <p>After downloading, it is important to verify that you ahve a
+    complete and unmodified version of the Apache HTTP Server. This
+    can be accomplished by testing the downloaded tarball against the
+    PGP signature.  Details on how to do this are available on the <a
+    href="http://httpd.apache.org/download.cgi#verify">download
+    page</a> and an extended example is available describing the <a
+    href="http://httpd.apache.org/dev/verification.html">use of
+    PGP</a>.</p>
 
 </section>
 
@@ -223,8 +191,8 @@
     simple matter of uncompressing, and then untarring:</p>
 
 <example>
-      $ gzip -d httpd-2_1_<em>NN</em>.tar.gz<br />
-       $ tar xvf httpd-2_1_<em>NN</em>.tar
+$ gzip -d httpd-2_1_<em>NN</em>.tar.gz<br />
+$ tar xvf httpd-2_1_<em>NN</em>.tar
 </example>
 
     <p>This will create a new directory under the current directory
@@ -235,26 +203,53 @@
 
 <section id="configure"><title>Configuring the source tree</title>
 
-    <p>The next step is to configure the Apache source tree for
-    your particular platform and personal requirements. This is
-    done using the script <code>configure</code> included in the
-    root directory of the distribution. (Developers downloading the
-    CVS version of the Apache source tree will need to have
-    <code>autoconf</code> and <code>libtool</code> installed and
-    will need to run <code>buildconf</code> before proceeding with
-    the next steps. This is not necessary for official
-    releases.)</p>
+    <p>The next step is to configure the Apache source tree for your
+    particular platform and personal requirements. This is done using
+    the script <code><a
+    href="programs/configure.html">configure</a></code> included in
+    the root directory of the distribution. (Developers downloading
+    the CVS version of the Apache source tree will need to have
+    <code>autoconf</code> and <code>libtool</code> installed and will
+    need to run <code>buildconf</code> before proceeding with the next
+    steps. This is not necessary for official releases.)</p>
 
     <p>To configure the source tree using all the default options,
     simply type <code>./configure</code>. To change the default
     options, <code>configure</code> accepts a variety of variables
-    and command line options. Environment variables are generally
-    placed before the <code>./configure</code> command, while other
-    options are placed after. The most important option here is the
-    location prefix where Apache is to be installed later, because
-    Apache has to be configured for this location to work
-    correctly. But there are a lot of other options available for
-    your pleasure.</p>
+    and command line options.</p>
+
+    <p>The most important option is the location prefix where Apache
+    is to be installed later, because Apache has to be configured for
+    this location to work correctly.  More fine-tuned control of the
+    location of files is possible with additional <a
+    href="programs/configure.html#installationdirectories">configure
+    options</a>.</p>
+
+    <p>Also at this point, you can specify which <a
+    href="programs/configure.html#optionalfeatures">features</a> you
+    want included in Apache by enabling and disabling <a
+    href="mod/">modules</a>.  Apache comes with a <a
+    href="module-dict.html#Status">Base</a> set of modules included by
+    default.  Other modules are enabled using the
+    <code>enable-<var>module</var></code> option, where
+    <var>module</var> is the name of the module with the
+    <code>mod_</code> string removed and with any underscore converted
+    to a dash.  You can also choose to compile modules as <a
+    href="dso.html">shared objects (DSOs)</a> -- which can be loaded
+    or unloaded at runtime -- by using the option
+    <code>enable-<var>module</var>=shared</code>.  Similarly, you can
+    disable Base modules with the
+    <code>--disable-<var>module</var></code> option.  Be careful when
+    using these options, since <code>configure</code> cannot warn you
+    if the module you specify does not exit; it will simply ignore the
+    option.</p>
+
+    <p>In addition, it is sometimes necessary to provide the
+    <code>configure</code> script with extra information about the
+    location of your compiler, libraries, or header files.  This is
+    done by passing either environment variables or command line
+    options to <code>configure</code>.  For more information, see the
+    <a href="programs/configure.html">configure manual page</a>.</p>
 
     <p>For a short impression of what possibilities you have, here
     is a typical example which compiles Apache for the installation
@@ -274,282 +269,9 @@
     test for the availability of features on your system and build
     Makefiles which will later be used to compile the server.</p>
 
-    <p>The easiest way to find all of the configuration flags for
-    Apache is to run <code>./configure --help</code>. What follows is a
-    brief description of most of the arguments and environment
-    variables.</p>
-
-<section id="environment"><title>Environment Variables</title>
-
-    <p>The <code>autoconf</code> build process uses several environment
-    variables to configure the build environment. In general, these
-    variables change the method used to build Apache, but not the
-    eventual features of the server. These variables can be placed
-    in the environment before invoking <code>configure</code>, but
-    it is usually easier to specify them on the
-    <code>configure</code> command line as demonstrated in the
-    example above.</p>
-
-    <dl>
-      <dt><code>CC=...</code></dt>
-
-      <dd>The name of the C compiler command.</dd>
-
-      <dt><code>CPPFLAGS=...</code></dt>
-
-      <dd>Miscellaneous C preprocessor and compiler options.</dd>
-
-      <dt><code>CFLAGS=...</code></dt>
-
-      <dd>Debugging and optimization options for the C
-      compiler.</dd>
-
-      <dt><code>LDFLAGS=...</code></dt>
-
-      <dd>Miscellaneous options to be passed to the linker.</dd>
-
-      <dt><code>LIBS=...</code></dt>
-
-      <dd>Library location information ("<code>-L</code>" and
-      "<code>-l</code>" options) to pass to the linker.</dd>
-
-      <dt><code>INCLUDES=...</code></dt>
-
-      <dd>Header file search directories ("<code>-I<em>dir</em></code>").</dd>
-
-      <dt><code>TARGET=...</code> [Default: <code>httpd</code>]</dt>
-
-      <dd>Name of the executable which will be built.</dd>
-
-      <dt><code>NOTEST_CPPFLAGS=...</code></dt>
-
-      <dt><code>NOTEST_CFLAGS=...</code></dt>
-
-      <dt><code>NOTEST_LDFLAGS=...</code></dt>
-
-      <dt><code>NOTEST_LIBS=...</code></dt>
-
-      <dd>These variables share the same function as their
-      non-<code>NOTEST</code> namesakes. However, the variables are
-      applied to the build process only after autoconf has performed its
-      feature testing. This allows the inclusion of flags which
-      will cause problems during feature testing, but must be used
-      for the final compilation.</dd>
-
-      <dt><code>SHLIB_PATH=...</code></dt>
-
-      <dd>Options which specify shared library paths for the
-      compiler and linker.</dd>
-    </dl>
-</section>
-
-<section id="output"><title>autoconf Output Options</title>
-
-    <dl>
-      <dt><code>--help</code></dt>
-
-      <dd>Prints the usage message including all available options,
-      but does not actually configure anything.</dd>
-
-      <dt><code>--quiet</code></dt>
-
-      <dd>Prevents the printing of the usual "<code>checking...</code>"
-      messages.</dd>
-
-      <dt><code>--verbose</code></dt>
-
-      <dd>Prints much more information during the configuration
-      process, including the names of all the files examined.</dd>
-    </dl>
-</section>
-
-<section id="pathnames"><title>Pathnames</title>
-
-    <p>There are currently two ways to configure the pathnames
-    under which Apache will install its files. First, you can
-    specify a directory and have Apache install itself under that
-    directory in its default locations.</p>
-
-    <dl>
-      <dt><code>--prefix=<em>PREFIX</em></code> [Default:
-      <code>/usr/local/apache2</code>]</dt>
-
-      <dd>Specifies the directory under which the Apache files will
-      be installed.</dd>
-    </dl>
-
-    <p>It is possible to specify that architecture-dependent files
-    should be placed under a different directory.</p>
-
-    <dl>
-      <dt><code>--exec-prefix=<em>EPREFIX</em></code> [Default:
-      <code><em>PREFIX</em></code>]</dt>
-
-      <dd>Specifies the directory under which
-      architecture-dependent files will be placed.</dd>
-    </dl>
-
-    <p>The second, and more flexible way to configure the install
-    path locations for Apache is using the
-    <code>config.layout</code> file. Using this method, it is
-    possible to separately specify the location for each type of
-    file within the Apache installation. The
-    <code>config.layout</code> file contains several example
-    configurations, and you can also create your own custom
-    configuration following the examples. The different layouts in
-    this file are grouped into <code>&lt;Layout
-    FOO&gt;...&lt;/Layout&gt;</code> sections and referred to by
-    name as in <code>FOO</code>.</p>
-
-    <dl>
-      <dt><code>--enable-layout=<em>LAYOUT</em></code></dt>
-
-      <dd>Use the named layout in the <code>config.layout</code>
-      file to specify the installation paths.</dd>
-    </dl>
-
-</section>
-
-<section id="modules"><title>Modules</title>
-
-    <p>Apache is a modular server. Only the most basic
-    functionality is included in the core server. Extended features
-    are available in various modules. During the configuration
-    process, you must select which modules to compile for use with
-    your server. You can view a <a
-    href="mod/">list of modules</a> included in
-    the documentation. Those modules with a <a
-    href="mod/module-dict.html#Status">status</a> of "Base" are
-    included by default and must be specifically disabled if you do
-    not want them (e.g. <module>mod_userdir</module>). Modules with any
-    other status must be specifically enabled if you wish to use them
-    (e.g. <module>mod_expires</module>).</p>
-
-    <p>There are two ways for a module to be compiled and used with
-    Apache. Modules may be <em>statically compiled</em>, which
-    means that they are permanently included in the Apache binary.
-    Alternatively, if your operating system supports Dynamic Shared
-    Objects (DSOs) and <code>autoconf</code> can detect that support, then
-    modules may be <em>dynamically compiled</em>. DSO modules are
-    stored separately from the Apache binary, and may be included
-    or excluded from the server using the run-time configuration
-    directives provided by <module>mod_so</module>.
-    The mod_so is automatically included in the server if any
-    dynamic modules are included in the compilation. If you would
-    like to make your server capable of loading DSOs without
-    actually compiling any dynamic modules, you can explicitly
-    <code>--enable-so</code>.</p>
-
-    <dl>
-      <dt><code>--enable-<em>MODULE</em>[=shared]</code></dt>
-
-      <dd>Compile and include the module <em>MODULE</em>. The
-      identifier <em>MODULE</em> is the <a
-      href="mod/module-dict.html#ModuleIdentifier">Module
-      Identifier</a> from the module documentation without the
-      "_module" string. To compile the module as a DSO, add the
-      option <code>=shared</code>.</dd>
-
-      <dt><code>--disable-<em>MODULE</em></code></dt>
-
-      <dd>Remove the module <em>MODULE</em> which would otherwise
-      be compiled and included.</dd>
-
-      <dt><code>--enable-modules=<em>MODULE-LIST</em></code></dt>
-
-      <dd>Compile and include the modules listed in the
-      space-separated <em>MODULE-LIST</em>.</dd>
-
-      <dt>
-      <code>--enable-mods-shared=<em>MODULE-LIST</em></code></dt>
-
-      <dd>Compile and include the modules in the space-separated
-      <em>MODULE-LIST</em> as dynamically loadable (DSO)
-      modules.</dd>
-    </dl>
-
-    <p>The <em>MODULE-LIST</em> in the
-    <code>--enable-modules</code> and
-    <code>--enable-mods-shared</code> options is usually a
-    space-separated list of module identifiers. For example, to
-    enable <module>mod_dav</module> and <module>mod_info</module>,
-    you can either use</p>
-
-<example>./configure --enable-dav --enable-info</example>
-
-    <p>or, equivalently,</p>
-
-<example>./configure --enable-modules="dav info"</example>
-
-    <p>In addition, the special keywords <code>all</code> or
-    <code>most</code> can be used to add all or most of the modules
-    in one step. You can then remove any modules that you do not
-    want with the <code>--disable-<em>MODULE</em></code> option.
-    For example, to include all modules as DSOs with the exception
-    of <module>mod_info</module>, you can use</p>
-
-<example>
-      ./configure --enable-mods-shared=all
-      --disable-info
-</example>
-
-    <p>In addition to the standard set of modules, Apache 2.0 also
-    includes a choice of <a href="mpm.html">Multi-Processing
-    Modules</a> (MPMs). One, and only one MPM must be included in
-    the compilation process. The default MPMs for each platform are
-    listed on the <a href="mpm.html">MPM documentation page</a>,
-    but can be overridden on the <code>configure</code> command
-    line.</p>
-
-    <dl>
-      <dt><code>--with-mpm=<em>NAME</em></code></dt>
-
-      <dd>Choose the mpm <em>NAME</em>.</dd>
-    </dl>
-
-    <p>To activate an MPM called <var>mpm_name</var>, you can use</p>
-
-<example>
-     ./configure --with-mpm=<var>mpm_name</var>
-</example>
-
-</section>
-
-<section id="dbm"><title>DBM</title>
-
-    <p>Several Apache features, including
-    <module>mod_authn_dbm</module> and <module>mod_rewrite</module>'s
-    DBM <directive module="mod_rewrite">RewriteMap</directive> use
-    simple key/value databases for quick lookups of information.  Apache
-    includes SDBM with its source-code, so this database is always
-    available.  If you would like to use other database types, the
-    following <code>configure</code> options are available:</p>
-
-<dl>
-<dt><code>--with-gdbm[=<em>path</em>]</code></dt>
-<dt><code>--with-ndbm[=<em>path</em>]</code></dt>
-<dt><code>--with-berkeley-db[=<em>path</em>]</code></dt>
-
-<dd>If no <em>path</em> is specified, Apache will search for the
-include files and libraries in the usual search paths.  An explicit
-<em>path</em> will cause Apache to look in
-<em>path</em><code>/lib</code> and
-<em>path</em><code>/include</code> for the relevant files.  Finally,
-the <em>path</em> may specify specific include and library paths
-separated by a colon.</dd>
-</dl>
-</section>
-
-
-<section id="suexec"><title>Suexec</title>
-
-    <p>Apache includes a support program called <a
-    href="suexec.html">suexec</a> which can be used to isolate user
-    CGI programs. However, if suexec is improperly configured, it
-    can cause serious security problems. Therefore, you should
-    carefully read and consider the <a href="suexec.html">suexec
-    documentation</a> before implementing this feature.</p>
-</section>
+    <p>Details on all the different <code>configure</code> options are
+    available on the <a href="programs/configure.html">configure
+    manual page</a>.</p>
 </section>
 
 <section id="compile"><title>Build</title>