Update the INSTALL docs

1 files changed, 153 insertions, 12 deletions

diff --git a/INSTALL b/INSTALL
index 79405cd8fd..8ba6a13570 100644
--- a/INSTALL
+++ b/INSTALL
@@ -1,14 +1,54 @@
 Installation Instructions for PHP 4.0
 -------------------------------------
 
-Note!  As of 4.0b3, PHP will require GNU make.
+Note!  PHP will requires GNU make.  Check this by typing: make --version
+If it does not say GNU Make, please install it.
 
 For the impatient here is a quick set of steps that will build PHP as
-an Apache module for Apache 1.3.x with MySQL support.  A more verbose
-explanation follows.
+first a dynamic Apache module (DSO) for Apache 1.3.x with MySQL support 
+and then a static module.  A more verbose explanation follows.  
 
+Note!  Only install either the static module or the dynamic one.  Do not
+install both.  
 
-QUICK INSTALL
+If you want both PHP 3 and 4 modules in the same Apache server, check the
+bottom of this file for instructions.
+
+
+QUICK INSTALL (DSO)
+
+For this to work your Apache httpd must have mod_so enabled.
+Check using httpd -l.  You should see something like:
+
+Compiled-in modules:
+  http_core.c
+  mod_so.c
+
+Chances are you will see a lot more modules than these two. That's ok, 
+as long as mod_so.c shows up you can proceed with the following steps:
+
+$ gunzip -c php-4.0.x.tar.gz | tar xf -
+$ cd php-4.0.x
+$ ./configure --with-mysql --with-apxs
+$ make
+$ make install
+
+If you get an error telling you that the apxs script could not be found,
+look for it on your system and if you find it, provide the full path to it
+as: --with-apxs=/path/to/apxs
+
+The only thing left to do is to edit your httpd.conf file and make sure the
+PHP 4 mime type is there and uncommented.  You need a line that looks like
+this:
+
+   AddType application/x-httpd-php .php
+
+Then restart your server (apachectl restart) and you should be able to
+serve up PHP files now.  Make a test file called test.php and put some 
+PHP tags in it.  Like <?phpinfo()?>, for example.
+
+
+QUICK INSTALL (Static)
 
 $ gunzip -c apache_1.3.x.tar.gz | tar xf -
 $ cd apache_1.3.x
@@ -36,18 +76,66 @@ Edit your httpd.conf or srm.conf file and add:
 
 VERBOSE INSTALL
 
+Chances are you are reading this because the quick install steps above
+did not work for you.  If this is the case, congratulations, you are
+among the elite few that actually reads documentation.  It really is
+not a difficult install and once you have done it once you will fly 
+through it.
+
 Installing PHP can be done in four simple steps:
 
 1. Unpack your distribution file.  
 
-   You will have downloaded a file named something like php4xn.tar.gz.
-   Unzip this file with a command like: gunzip php4xn.tar.gz
+   You will have downloaded a file named something like php-4.0.x.tar.gz.
+   Unzip this file with a command like: gunzip php-4.0.x.tar.gz
 
-   Next you have to untar it with: tar -xvf php4xn.tar
+   Next you have to untar it with: tar -xvf php-4.0.x.tar
 
    This will create a php-4.0.x directory.  cd into this new directory.
 
-2. Configure PHP.
+2a. Configure PHP (Dynamic Module) - Skip to 2b if you wish to build
+    a static module
+
+   You now have to choose the options you would like.  There are quite
+   a few of them.  To see a list, type: ./configure --help
+
+   The only options that you are likely to want to use are the ones in
+   the last section entitled, "--enable and --with options recognized:"
+
+   A popular choice is to build the Apache module version.  In order to
+   build PHP as a dynamic module for Apache-1.3.x you have to first have
+   Apache installed.  Assuming Apache is already installed, make sure
+   the shared object module is enabled.  To check this, type: httpd -l
+   You should see something like:
+
+     Compiled-in modules:
+       http_core.c
+       mod_so.c
+
+   You will most likely have a lot more modules than what is shown here.
+   As long as mod_so.c shows up in the list, PHP should be happy.
+
+   Now, type: ./configure --with-mysql --with-apxs
+
+   If you get an error telling you that the apxs script could not be found,
+   look for it on your system and if you find it, provide the full path to it
+   as: --with-apxs=/path/to/apxs
+
+   You might also want other flags on this configure line.  --with-mysql
+   is just an example.  
+
+   There are a few things that can go wrong during this configure step.
+   The most common is that you have asked for an option and that the
+   configure script can not find the files required to enable this 
+   option in PHP.  Chances are you can provide the full path to the
+   base directory under which the related files were installed.  For
+   example, if you have installed the GD library in /opt/gd which means
+   that /opt/gd/include has your GD header files and /opt/gd/lib contains
+   your GD library files, you would use --with-gd=/opt/gd
+
+   Skip to step 3 for compilation and installation instructions.
+
+2b. Configure PHP (Static Module) - Skip if you performed 2a
 
    You now have to choose the options you would like.  There are quite
    a few of them.  To see a list, type: ./configure --help
@@ -77,8 +165,16 @@ Installing PHP can be done in four simple steps:
    Apache Configure script at least once before compiling PHP.  It 
    doesn't matter how you have Apache configured at this point.
 
+   Skip to step 3b at this point.
+
 3. Compile and install the files.  Simply type: make install
 
+3a.   Dynamic Module Installation
+
+   Nothing else is needed here.  Proceed to step 4a.
+
+3b.   Static Module Installation
+
    For the Apache module version this will copy the appropriate files
    to the src/modules/php4 directory in your Apache distribution if
    you are using Apache 1.3.x.  If you are still running Apache 1.2.x
@@ -136,11 +232,51 @@ Installing PHP can be done in four simple steps:
    somewhere.  Re-edit Configuration and try again.  If it goes well,
    type: make
 
-4. Setting up the server.
+   Assuming it compiles without errors, proceed to step 4b.
+
+4a. Setting up the server. (Dynamic Module)
+
+   The make install command in step 3 should have done most of your
+   work for you.  It actually edits your httpd.conf file and tries to
+   enable the dynamic PHP module.  To verify this, look for a line that
+   looks like this:
+
+      LoadModule php4_module libexec/libphp4.so
+
+   The actual path before the libphp4.so part might differ slightly.  This
+   is likely fine.  If you are paranoid you can examine the output from the
+   make install step to see where the libphp4.so file was actually put and
+   place the full path to this file on this LoadModule line.
+
+   If somewhere in your httpd.conf file you have a ClearModuleList line
+   then you also need this line:
+
+      AddModule mod_php4.c
+
+   And finally you need to tell Apache which file extension should trigger
+   PHP.  You do this by creating a special mime type and associating it
+   with an extension.  We suggest using:
+
+      AddType application/x-httpd-php .php
+  
+   You are however free to use any extension you wish, including .html.
+
+   Note!  If a line has a # at the beginning, then it is commented out
+   and you need to remove the # for that line to take effect.
+
+   Once you have made these changes you should be ready to restart your
+   server and try it out.  Type: apachectl restart
+   
+   The create a test file named test.php in your web tree somewhere and
+   put some test PHP tags in it.  <?phpinfo()?> is a good first test.
+   This tag tells PHP to do a braindump and tells you all sorts of things
+   about itself.  
+
+4b. Setting up the server. (Static Module)
    
    You should now have a new httpd binary.  Shut down your existing server,
    if you have one, and copy this new binary overtop of it.  Perhaps make
-   a backup of your previous one first.  Then edit your conf/srm.conf file
+   a backup of your previous one first.  Then edit your conf/httpd.conf file
    and add the line:
 
       AddType application/x-httpd-php .php
@@ -154,8 +290,13 @@ Installing PHP can be done in four simple steps:
    Any file ending in .phps will now be displayed with full colour syntax
    highlighting instead of being executed.
 
-   When you are finished making changes to your srm.conf file, you can
-   start up your server.
+   When you are finished making changes to your httpd.conf file, you can
+   start up your server.  Note that on some older server setups, the 
+   AddType lines are in the conf/srm.conf file instead of conf/httpd.conf.
+
+   Note!  If a line has a # at the beginning, then it is commented out
+   and you need to remove the # for that line to take effect.
+
 
 USING PHP3 AND PHP4 AS CONCURRENT APACHE MODULES