Make INSTALL just be a terse quick-start guide. The full installation

documentation is now in install.html.

Submitted by:	Joshua Slive
Reviewed by:	Cliff Woolley


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

1 files changed, 29 insertions, 448 deletions

diff --git a/INSTALL b/INSTALL
index ced2c73298..14ff4970e4 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,466 +1,47 @@
 
-  APACHE INSTALLATION
+  APACHE INSTALLATION OVERVIEW
 
-  Introduction
-  ============
+  For complete installation documentation, see docs/manual/install.html or
+  http://httpd.apache.org/docs-2.0/install.html
 
-  Apache 2.0's configuration and installation environment has changed
-  completely from Apache 1.3.  Apache 1.3 used a custom set of scripts
-  to achieve easy installation.  Apache 2.0 now uses libtool and
-  autoconf to create an environment that looks like many other Open
-  Source projects.
-
-
-  Installing the Apache 2.0 HTTP server
-  =====================================
-
-  1. Overview for the impatient
-     --------------------------
+  Quick Start
+  -----------
 
      $ ./configure --prefix=PREFIX
      $ make
      $ make install
      $ PREFIX/bin/apachectl start
 
-     NOTE: PREFIX is not the string "PREFIX". Instead use the Unix
-           filesystem path under which Apache should be installed. For
-           instance use "/usr/local/apache" for PREFIX above.
-
-     NOTE: if you are building from a copy of the Apache CVS
-           repository, rather than a release distribution, then you
-	   must use the "buildconf" script before running configure.
-
-     NOTE: If you are building on FreeBSD, you should add the argument
-           --with-mpm=prefork to the configure line.  The Apache Group
-           has discovered that threads do not work well with Apache
-           on FreeBSD.  For that reason, we disable threads by default
-           on FreeBSD, and you need to build the prefork MPM.  If you wish
-           to try to make threads work on FreeBSD, they can be re-enabled
-           by using --enable-threads
-
-  2. Requirements
-     ------------
-
-     The following requirements exist for building Apache:
-
-     o  Disk Space: 
-
-        Make sure you have approximately 12 MB of temporary free disk
-        space available.  After installation Apache occupies
-        approximately 5 MB of disk space (the actual required disk
-        space depends on the amount of compiled in third party
-        modules, etc).
-
-     o  ANSI-C Compiler: 
-
-        Make sure you have an ANSI-C compiler installed. The GNU C
-        compiler (GCC) from the Free Software Foundation (FSF) is
-        recommended (version 2.7.2 is fine). If you don't have GCC
-        then at least make sure your vendors compiler is ANSI
-        compliant. You can find the homepage of GNU at
-        http://www.gnu.org/ and the GCC distribution under
-        http://www.gnu.org/order/ftp.html .
-
-     o  Perl 5 Interpreter [OPTIONAL]:
-
-        For some of the support scripts like `apxs' or `dbmmanage'
-        (which are written in Perl) the Perl 5 interpreter is required
-        (versions 5.003 and 5.004 are fine). If no such interpreter is
-        found by the `configure' script this is no harm.  Of
-        course, you still can build and install Apache 2.0. Only those
-        support scripts cannot be used. If you have multiple Perl
-        interpreters installed (perhaps a Perl 4 from the vendor and a
-        Perl 5 from your own), then it is recommended to use the
-        --with-perl option (see below) to make sure the correct one is
-        selected by ./configure.
-
-     o  Dynamic Shared Object (DSO) support [OPTIONAL]:
-
-        To provide maximum flexibility Apache now is able to load
-        modules under runtime via the DSO mechanism by using the
-        pragmatic apr_dso_open()/apr_dso_sym() calls. These calls
-        are not available under all operating systems therefore you
-        cannot use the DSO mechanism on all platforms. Apache relies
-        on autoconf to detect the ability to use DSOs, and libtool to
-        determine how to build DSOs. If your platform is supported by
-        libtool, and we can find DSO system calls, then DSOs should
-        work out-of-the-box. 
-
-        If your system is not on these lists but has the dlopen-style
-        interface, you either have to provide the appropriate compiler
-        and linker flags manually or at least make sure a Perl 5
-        interpreter is installed from which Apache can guess the options.
-
-
-     If you are building from a copy of the CVS repository, rather
-     than a release distribution, then you will need these additional
-     tools:
-
-     o  Libtool 1.3.3:
-
-        Make sure that you have libtool 1.3.3 or later installed
-        before trying to configure and build Apache 2.0.  Libtool can
-        be downloaded from the Free Software Foundation (FSF), at
-        http://www.gnu.org/order/ftp.html.
+     NOTES: * Replace PREFIX with the filesystem path under which 
+              Apache should be installed.  A typical installation
+              might use "/usr/local/apache" for PREFIX (without the
+              quotes).
 
-     o  Autoconf 2.13:
+            * If you are building on FreeBSD, be aware that threads will
+              be disabled and the prefork MPM will be used by default,
+              as threads do not work well with Apache on FreeBSD.  If
+              you wish to try a threaded Apache on FreeBSD anyway, use
+              "./configure --enable-threads".
 
-        Make sure that you have autoconf 2.13 or later installed
-        before trying to configure and build Apache 2.0.  Autoconf can
-        be downloaded from the Free Software Foundation (FSF), at
-        http://www.gnu.org/order/ftp.html.
+            * If you are a developer building Apache directly from CVS,
+              you will need to run ./buildconf before running configure.
 
-
-  3. Configuring the source tree
-     ---------------------------
-
-     Setup:
-
-     If you have downloading the Apache 2.0 from the CVS, rather than
-     a release distribution, then you will need to prepare the source
-     tree for configuration and compilation. This is done by running:
- 
-     ./buildconf
-
-     This script ensures that all required programs are installed on
-     the currently machine, and creates the ./configure script.  If
-     you are using a package downloaded from apache.org then this step
-     is not necessary.
-
-     Introduction:
-
-     The next step is to configure the Apache source tree for your
-     particular platform and personal requirements. The most important
-     setup 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.
-
-     For a short impression of what possibilities you have, here is a
-     typical example which compiles Apache for the installation tree
-     /sw/pkg/apache with a particular compiler and flags plus the two
-     additional modules mod_rewrite and mod_speling for later loading
-     through the DSO mechanism:
+  For a short impression of what possibilities you have, here is a
+  typical example which configures Apache for the installation tree
+  /sw/pkg/apache with a particular compiler and flags plus the two
+  additional modules mod_rewrite and mod_speling for later loading
+  through the DSO mechanism:
 
      $ CC="pgcc" CFLAGS="-O2" \
-       ./configure --prefix=/sw/pkg/apache \
-                   --enable-rewrite=shared \
-                   --enable-speling=shared
-
-     The easiest way to find all of the configuration flags for Apache
-     2.0 is to run ./configure --help.  What follows is a brief
-     description of most of the arguments.
-
-     Reference:
-
-     $ [CC=...]        [TARGET=...]
-       [CPPFLAGS=...]  [NOTEST_CPPFLAGS=...]
-       [CFLAGS=...]    [NOTEST_CFLAGS=...]
-       [CXXFLAGS=...]  [NOTEST_CXXFLAGS=...]
-       [LDFLAGS=...]   [NOTEST_LDFLAGS=...]
-       [LIBS=...]      [NOTEST_LIBS=...]
-       [INCLUDES=...]  [SHLIB_PATH=...] 
-
-       ./configure
-           [--quiet]         [--prefix=DIR]            [--enable-NAME=(shared)]
-           [--verbose]       [--exec-prefix=PREFIX]    [--disable-NAME]
-           [--shadow[=DIR]]  [--bindir=EPREFIX]        [--with-mpm=NAME]
-           [--show-layout]   [--sbindir=DIR]           
-           [--help]          [--libexecdir=DIR]        
-                             [--mandir=DIR]            
-                             [--sysconfdir=DIR]        
-                             [--datadir=DIR]           
-                             [--includedir=DIR]        
-                             [--localstatedir=DIR]
-                             [--runtimedir=DIR]        [--enable-suexec]
-                             [--logfiledir=DIR]        [--suexec-caller=UID]
-                             [--proxycachedir=DIR]     [--suexec-docroot=DIR]
-                             [--with-layout=[FILE:]ID] [--suexec-logfile=FILE]
-                                                       [--suexec-userdir=DIR]
-                             [--with-perl=FILE]        [--suexec-uidmin=UID]
-                             [--without-support]       [--suexec-gidmin=GID]
-                             [--without-confadjust]    [--suexec-safepath=PATH]
-                             [--without-execstrip]
-			     [--server-uid=UID]
-			     [--server-gid=GID]
-
-                             [--enable-maintainter-mode]
-                             [--enable-debug]
-
-     Use the CC, CPPFLAGS, CFLAGS, CXXFLAGS, LDFLAGS, LIBS, INCLUDES,
-     SHLIB_PATH and TARGET environment variables to override or expand the
-     corresponding default entries as determined by configure.
-
-     Use NOTEST_CPPFLAGS, NOTEST_CFLAGS, NOTEST_CXXFLAGS, NOTEST_LDFLAGS,
-     and NOTEST_LIBS to add entries that should only be used during
-     the actual build and compilation of Apache, such as -Werror.
-
-     Use the --prefix=PREFIX and --exec-prefix=EPREFIX options to
-     configure Apache to use a particular installation prefix. The
-     default is PREFIX=/usr/local/apache and EPREFIX=PREFIX.
-
-     Use the --bindir=DIR, --sbindir=DIR, --libexecdir=DIR,
-     --mandir=DIR, --sysconfdir=DIR, --datadir=DIR, --iconsdir=DIR,
-     --htdocsdir=DIR, --cgidir=DIR, --includedir=DIR,
-     --localstatedir=DIR, --runtimedir=DIR, --logfiledir=DIR and
-     --proxycachedir=DIR option to change the paths for particular
-     subdirectories of the installation tree.  Defaults are
-     bindir=EPREFIX/bin, sbindir=EPREFIX/bin,
-     libexecdir=EPREFIX/modules, mandir=PREFIX/man,
-     sysconfdir=PREFIX/conf, datadir=PREFIX, iconsdir=PREFIX/icons,
-     htdocsdir=PREFIX/htdocs, cgidir=PREFIX/cgi-bin,
-     includedir=PREFIX/include, localstatedir=PREFIX,
-     runtimedir=PREFIX/logs, logfiledir=PREFIX/logs and
-     proxycachedir=PREFIX/proxy.
-
-         Note: To reduce the pollution of shared installation
-               locations (like /usr/local/ or /etc) with Apache files
-               to a minimum the string ``/apache'' is automatically
-               appended to 'libexecdir', 'sysconfdir', 'datadir',
-               'localstatedir' and 'includedir' if (and only if) the
-               following points apply for each path individually:
-
-                   1. the path doesn't already contain the word ``apache''
-                   2. the path was not directly customized by the user
-
-               Keep in mind that per default these paths are derived
-               from 'prefix' and 'exec-prefix', so usually its only a
-               matter whether these paths contain ``apache'' or
-               not. Although the defaults were defined with experience
-               in mind you always should make sure the paths fit your
-               situation by checking the finally chosen paths via the
-               --layout option.
-
-     Use the --with-layout=[F:]ID option to select a particular
-     installation path base-layout. You always _HAVE_ to select a
-     base-layout. There are currently two layouts pre-defined in the
-     file config.layout: `Apache' for the classical Apache path layout
-     and `GNU' for a path layout conforming to the GNU `standards'
-     document. When you want to use your own custom layout FOO, either
-     add a corresponding "<Layout FOO>...</Layout>" section to
-     config.layout and use --with-layout=FOO or place it into your own
-     file, say config.mypaths, and use
-     --with-layout=config.mypaths:FOO.
- 
-     Use the --show-layout option to check the final installation path
-     layout while fiddling with the options above.
- 
-     Use the --enable-NAME=(shared) and --disable-NAME options to
-     enable or disable a particular already distributed module from
-     the Apache package.
-
-     Use the --with-mpm=NAME option to determine which MPM should be
-     built for your server.
-
-     _________________________________________________________________________
-     LIST OF AVAILABLE MODULES
-
-     Environment creation
-      (+) mod_env .......... Set environment variables for CGI/SSI scripts
-      (+) mod_setenvif ..... Set environment variables based on HTTP headers
-      (-) mod_unique_id .... Generate unique identifiers for request
-
-     Content type decisions
-      (+) mod_mime ......... Content type/encoding determination (configured)
-      (-) mod_mime_magic ... Content type/encoding determination (automatic)
-      (+) mod_negotiation .. Content selection based on the HTTP Accept* headers
-
-     URL mapping
-      (+) mod_alias ........ Simple   URL translation and redirection
-      (-) mod_rewrite ...... Advanced URL translation and redirection
-      (+) mod_userdir ...... Selection of resource directories by username
-      (-) mod_speling ...... Correction of misspelled URLs
-
-     Directory Handling
-      (+) mod_dir .......... Directory and directory default file handling
-      (+) mod_autoindex .... Automated directory index file generation
-
-     Access Control and Authentication
-      (+) mod_access ....... Access Control (user, host, network)
-      (+) mod_auth ......... HTTP Basic Authentication (user, passwd)
-      (-) mod_auth_dbm ..... HTTP Basic Authentication via Unix NDBM files
-      (-) mod_auth_db ...... HTTP Basic Authentication via Berkeley-DB files
-      (-) mod_auth_anon .... HTTP Basic Authentication for Anonymous-style users
-      (-) mod_digest ....... HTTP Digest Authentication
-
-     HTTP response
-      (-) mod_headers ...... Arbitrary HTTP response headers (configured)
-      (-) mod_cern_meta .... Arbitrary HTTP response headers (CERN-style files)
-      (-) mod_expires ...... Expires HTTP responses 
-      (+) mod_asis ......... Raw HTTP responses 
-
-     Scripting
-      (+) mod_include ...... Server Side Includes (SSI) support
-      (+) mod_cgi .......... Common Gateway Interface (CGI) support
-      (+) mod_cgid ......... Common Gateway Interface (CGI) support for 
-                             multi-threaded MPMs
-      (+) mod_actions ...... Map CGI scripts to act as internal `handlers'
-
-     Internal Content Handlers
-      (+) mod_status ....... Content handler for server run-time status
-      (-) mod_info ......... Content handler for server configuration summary
-
-     Request Logging
-      (+) mod_log_config ... Customizable logging of requests
-      (-) mod_usertrack .... Logging of user click-trails via HTTP Cookies
-
-     Content Management
-      (-) mod_dav .......... WebDAV (RFC 2518) support for Apache
-      (-) mod_dav_fs ....... mod_dav backend to managing filesystem content
-
-     Miscellaneous
-      (+) mod_imap ......... Server-side Image Map support
-      (-) mod_proxy ........ Caching Proxy Module (HTTP, HTTPS, FTP)
-      (-) mod_so ........... Dynamic Shared Object (DSO) bootstrapping
-
-     Experimental
-      (-) mod_mmap_static .. Caching of frequently served pages via mmap()
-
-     Development
-      (-) mod_example ...... Apache API demonstration (developers only)
-
-     MPMs
-          mpmt_pthread ..... Multi-process(dynamic) Multi-threaded(static) 
-                             Unix MPM
-          prefork .......... Preforking Unix MPM
-          perchild ......... Multi-process(static) Multi-threaded(dynamic)
-                             Unix MPM, that allows a User per child process
-
-          winnt ............ Multi-process(1) Multi-threaded Windows MPM
-
-          mpmt_beos ........ Multi-process Multi-threaded Beos MPM
-          beos ............. Multi-process Multi-threaded Beos MPM
-
-          spmt_os2 ......... Single-process Multi-threaded OS/2 MPM
-     _________________________________________________________________________
-                    (+) = enabled  per default [disable with --disable-module]
-                    (-) = disabled per default [enable  with --enable-module ]
-
-     Use the --enable-suexec option to enable the suEXEC feature by
-     building and installing the "suexec" support program.
-
-     CAUTION: FOR DETAILS ABOUT THE SUEXEC FEATURE WE HIGHLY RECOMMEND
-              YOU TO FIRST READ THE DOCUMENT htdocs/manual/suexec.html
-              BEFORE USING THE ABOVE OPTIONS.
-     
-              USING THE SUEXEC FEATURE PROPERLY CAN REDUCE
-              CONSIDERABLY THE SECURITY RISKS INVOLVED WITH ALLOWING
-              USERS TO DEVELOP AND RUN PRIVATE CGI OR SSI
-              PROGRAMS. HOWEVER, IF SUEXEC IS IMPROPERLY CONFIGURED,
-              IT CAN CAUSE ANY NUMBER OF PROBLEMS AND POSSIBLY CREATE
-              NEW HOLES IN YOUR COMPUTER'S SECURITY.  IF YOU AREN'T
-              FAMILIAR WITH MANAGING SETUID ROOT PROGRAMS AND THE
-              SECURITY ISSUES THEY PRESENT, WE HIGHLY RECOMMEND THAT
-              YOU NOT CONSIDER USING SUEXEC AND KEEP AWAY FROM THESE
-              OPTIONS!
-
-     Use the --quiet option to disable all configuration verbose
-     messages.
- 
-
-  4. Building the package
-     --------------------
-     
-     Now you can build the various parts which form the Apache package
-     by simply running the command:
- 
-        $ make 
- 
-     Please be patient here, this takes approximately 2 minutes to
-     complete under a Pentium-166/FreeBSD-2.2 system, dependend on the
-     amount of modules you have enabled.
-
- 
-  5. Installing the package
-     ----------------------
-     
-     Now its time to install the package under the configured
-     installation PREFIX (see --prefix option above) by running:
- 
-        $ make install
- 
-     For the paranoid hackers under us: The above command really
-     installs under prefix _only_, i.e. no other stuff from your
-     system is touched. Even if you upgrade an existing installation
-     your configuration files in PREFIX/conf/ are preserved.
-
-
-  6. Testing the package
-     -------------------
- 
-     Now you can fire up your Apache HTTP server by immediately
-     running:
- 
-        $ PREFIX/bin/apachectl start
- 
-     and then you should be able to request your first document via
-     URL http://localhost/ (when you built and installed Apache as
-     root or at least used the --without-confadjust option) or
-     http://localhost:8080/ (when you built and installed Apache as a
-     regular user). Then stop the server again by running:
-
-        $ PREFIX/bin/apachectl stop
-
- 
-  7. Customizing the package
-     -----------------------
- 
-     Finally you can customize your Apache HTTP server by editing the
-     configuration files under PREFIX/conf/.
- 
-        $ vi PREFIX/conf/httpd.conf
- 
-     Have a look at the Apache manual under docs/manual/ or
-     http://httpd.apache.org/docs/ for a complete reference of
-     available configuration directives.
-
-
-  8. Preparing the system
-     --------------------
-
-     Proper operation of a public HTTP server requires at least the
-     following:
-
-     1. A correctly working TCP/IP layer, since HTTP is implemented on
-        top of TCP/IP. Although modern Unix platforms have good
-        networking layers, always make sure you have all official
-        vendor patches referring to the network layer applied.
-
-     2. Accurate time keeping, since elements of the HTTP protocol are
-        expressed as the time of day.  So, it's time to investigate
-        setting some time synchronization facility on your
-        system. Usually the ntpdate or xntpd programs are used for
-        this purpose which are based on the Network Time Protocol
-        (NTP). See the Usenet newsgroup comp.protocols.time.ntp and
-        the NTP homepage at http://www.eecis.udel.edu/~ntp/ for more
-        details about NTP software and public time servers.
-
-
-  9. Contacts
-     --------
-
-     o If you want to be informed about new code releases, bug fixes,
-       security fixes, general news and information about the Apache
-       server subscribe to the apache-announce mailing list as
-       described under http://httpd.apache.org/announcelist.html
-
-     o If you want freely available support for running Apache please
-       join the Apache user community by subscribing at least to the
-       following USENET newsgroup: comp.infosystems.www.servers.unix
-
-     o If you want commercial support for running Apache please
-       contact one of the companies and contractors which are listed
-       at http://httpd.apache.org/info/support.cgi
+     ./configure --prefix=/sw/pkg/apache \
+     --enable-rewrite=shared \
+     --enable-speling=shared 
 
-     o If you have a concrete bug report for Apache please go to the
-       Apache Group Bug Database and submit your report:
-       http://httpd.apache.org/bug_report.html
+  The easiest way to find all of the configuration flags for Apache 2.0
+  is to run ./configure --help.
 
-     o If you want to participate in actively developing Apache please
-       subscribe to the `new-httpd' mailing list as described at
-       http://www.apache.org/foundation/mailinglists.html
+  Thanks for using the Apache HTTP Server, version 2.0.
 
-     Thanks for running Apache httpd.
+                                     The Apache Software Foundation
+                                     http://www.apache.org/
 
-                                          The Apache Group
-                                          http://www.apache.org/