consolidate hints/instructions about using APR (and maybe APR-util) with httpd

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

3 files changed, 68 insertions, 25 deletions

diff --git a/INSTALL b/INSTALL
index 82c5acfd01..63a43d696e 100644
--- a/INSTALL
+++ b/INSTALL
@@ -17,17 +17,7 @@
               might use "/usr/local/apache2" for PREFIX (without the
               quotes).
 
-            * Consider if you want to use a previously installed APR and
-              APR-Util (such as those provided with many OSes) or if
-              you need to use the APR and APR-Util from the
-              httpd-2.5.x-deps.tar.gz tarball via ./configure's
-              --with-included-apr option. This is required if you don't
-              have the compiler which the system APR was built with.  It
-              can also be advantageous if you are a developer who will be
-              linking your code with Apache or using a debugger to step
-              through server code, as it removes the possibility of
-              version or compile-option mismatches with APR and APR-util
-              code.
+            * Read the section "APR - Unix" below.
 
             * If you are a developer building Apache directly from
               Subversion, you will need to run ./buildconf before running
@@ -63,6 +53,65 @@
   The easiest way to find all of the configuration flags for Apache 2.5
   is to run ./configure --help.
 
+  APR - Unix
+  ----------
+
+  httpd trunk (httpd development version 2.5) can use APR trunk (future
+  APR version 2.0) or the combination of the current APR 1.x branch and
+  the current APR-util 1.x branch.  (APR trunk bundles the features in
+  APR-util 1.x.)
+
+  The httpd buildconf step, required when building httpd from Subversion,
+  must have access to the APR source.  The httpd configure step, always
+  required, can configure the APR source in srclib or use a previously-
+  built APR.
+
+  APR (and APR-util if using APR 1.x) can be built with httpd from httpd's
+  srclib directory or can be built separately, prior to building httpd.
+ 
+  Building APR with httpd from httpd's srclib directory is required if
+  you don't have the compiler which the system APR was built with, and it
+  can also be advantageous if you are a developer who will be linking your
+  code with httpd or using a debugger to step through server code, as it
+  removes the possibility of version or compile-option mismatches with
+  APR and APR-util code.
+
+  To use APR trunk in srclib:
+
+    Check out APR trunk in srclib/apr with the following command:
+
+    svn co http://svn.apache.org/repos/asf/apr/apr/trunk srclib/apr
+
+    buildconf will find it automaticaly.  Use the --with-included-apr
+    argument to httpd configure.
+
+  To use APR 1.x and APR-util 1.x in srclib:
+
+    Check out the current branches as srclib/apr and srclib/apr-util with
+    the following commands:
+
+    svn co http://svn.apache.org/repos/asf/apr/apr/branches/1.4.x srclib/apr
+    svn co http://svn.apache.org/repos/asf/apr/apr-util/branches/1.5.x srclib/apr-util
+
+    buildconf will find them automaticaly.  Use the --with-included-apr
+    argument to httpd configure.
+
+  To use existing checkouts of APR (and APR-util if using APR 1.x):
+
+    httpd buildconf must have access to the source trees.  Use these arguments
+    to httpd buildconf:
+
+    --with-apr=[path to apr source] --with-apr-util=[path to apr-util source]
+  
+    (Omit --with-apr-util if using APR trunk.)
+
+    httpd configure must have access to a previously build apr.  Use these
+    arguments to httpd configure:
+
+    --with-apr=[path to apr install] --with-apr-util=[path to apr-util install]
+  
+    (Omit --with-apr-util if using APR trunk.)
+
 
   Quick Start - Windows
   ---------------------
diff --git a/buildconf b/buildconf
index a58845d7c4..652454018e 100755
--- a/buildconf
+++ b/buildconf
@@ -81,12 +81,9 @@ done
 
 if [ $apr_found -lt 1 ]; then
     echo ""
-    echo "You don't have a copy of the apr source in srclib/apr. "
-    echo "Please get the source using the following instructions," 
-    echo "or specify the location of the source with " 
-    echo "--with-apr=[path to apr] :"
+    echo "APR could not be found automatically."
     echo ""
-    echo "   svn co http://svn.apache.org/repos/asf/apr/apr/trunk srclib/apr"
+    echo "Please refer to the documentation on APR in the httpd INSTALL file."
     echo ""
     should_exit=1
 else
@@ -113,12 +110,9 @@ if [ $apr_major_version -lt 2 ] ; then
 
     if [ $apu_found -lt 1 ]; then
         echo ""
-        echo "You don't have a copy of the apr-util source in srclib/apr-util. "
-        echo "Please get one the source using the following instructions, "
-        echo "or specify the location of the source with "
-        echo "--with-apr-util=[path to apr-util]:"
+        echo "You are using APR 1.x but APR-util 1.x was not found."
         echo ""
-        echo "   svn co http://svn.apache.org/repos/asf/apr/apr-util/branches/1.5.x srclib/apr-util"
+        echo "Please refer to the documentation on APR in the httpd INSTALL file."
         echo ""
         should_exit=1
     fi
diff --git a/configure.in b/configure.in
index c4c17591ce..2cce0404b2 100644
--- a/configure.in
+++ b/configure.in
@@ -90,7 +90,7 @@ APACHE_HELP_STRING(--with-included-apr,Use bundled copies of APR/APR-Util))
 if test "x$with_included_apr" = "xyes"; then
   apr_found=reconfig
   if test ! -d srclib/apr && test ! -d $srcdir/srclib/apr; then
-    AC_MSG_ERROR([Bundled APR requested but not found at ./srclib/. Download and unpack the corresponding apr and apr-util packages to ./srclib/.])
+    AC_MSG_ERROR([Bundled APR requested but not found at ./srclib/. Please refer to the documentation on APR in the httpd INSTALL file.])
   fi
 else 
   APR_FIND_APR("$srcdir/srclib/apr", "./srclib/apr", 1, 1 2, [
@@ -106,7 +106,7 @@ else
 fi
 
 if test "$apr_found" = "no"; then
-  AC_MSG_ERROR([APR not found.  Please read the documentation.])
+  AC_MSG_ERROR([APR not found.  Please refer to the documentation on APR in the httpd INSTALL file.])
 fi
 
 if test "$apr_found" = "reconfig"; then
@@ -150,7 +150,7 @@ if test "x${apr_major_version}" = "x2"; then
 elif test "x$with_included_apr" = "xyes"; then
   apu_found=reconfig
   if test ! -d srclib/apr-util && test ! -d $srcdir/srclib/apr-util; then
-    AC_MSG_ERROR([Bundled APR-Util requested but not found at ./srclib/. Download and unpack the corresponding apr and apr-util packages to ./srclib/.])
+    AC_MSG_ERROR([Bundled APR-Util requested but not found at ./srclib/.  Please refer to the documentation on APR in the httpd INSTALL file.])
   fi
 else 
    dnl If httpd is buildconf'ed against an apr 2.x tree, then 1.x
@@ -162,7 +162,7 @@ else
 fi
 
 if test "$apu_found" = "no"; then
-  AC_MSG_ERROR([APR-util not found.  Please read the documentation.])
+  AC_MSG_ERROR([APR-util not found.  Please refer to the documentation on APR in the httpd INSTALL file.])
 fi
 
 # Catch some misconfigurations: