php-src/INSTALL

Installation Instructions for PHP 5
-----------------------------------

STOP!

Before going any further, please remember you are going to find more 
up to date instructions in the online manual, located here:

http://www.php.net/manual/en/install.apache.php

For Apache 2, instructions and up-to-date information regarding its
support status, is available here:

http://www.php.net/manual/en/install.apache2.php

It is strongly recommended that you read the manual page before going
further. However, for the impatient, here is a quick set of steps that 
will build PHP as (first) a dynamic Apache module (DSO) for Apache 1.3.x 
with MySQL support and then a static module.  A more verbose explanation follows.  

For installing PHP on other web servers, refer to one of the following
files:

    sapi/aolserver/README
    sapi/pi3web/README
    sapi/servlet/README
    sapi/thttpd/README
    README.Zeus

Some notes:

1: Only install either the static module or the dynamic one.  Do not
   install both.  

2:  If you are recompiling PHP to add new extensions or upgrading
    something like GD, remove the config.cache file before you re-run 
    configure.

3:  If you are on Linux and have installed shared libraries, make
    sure the location of these shared libraries are listed in your 
    /etc/ld.so.conf file.  For example, if you have:

       /usr/local/lib/mysql/libmysqlclient.so

    Make sure /etc/ld.so.conf contains:

      /usr/local/lib/mysql

    Then run ldconfig.

If you want both PHP 3 and 4 modules in the same Apache server, check the
bottom of this file for instructions.

INSTALLATION WITH THE ZEUS WEB SERVER:
--Please see the 'README.Zeus' file included in this distribution


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.x.y.tar.gz | tar xf -
$ cd php-4.x.y
$ ./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

Make sure you specify the version of apxs that is actually installed on
your system and NOT the one that is in the apache source tarball.

Next you must copy php.ini-dist to the appropriate place (normally
/usr/local/lib/php.ini) and edit it as necessary to set PHP options.

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
$ ./configure
$ cd ..

$ gunzip -c php-4.x.y.tar.gz | tar xf -
$ cd php-4.x.y
$ ./configure --with-mysql --with-apache=../apache_1.3.x
$ make
$ make install

$ cd ../apache_1.3.x
$ ./configure --prefix=/www --activate-module=src/modules/php5/libphp5.a
 (The above line is correct!  Yes, we know libphp5.a does not exist at this
  stage.  It isn't supposed to.  It will be created.)
$ make
 (you should now have an httpd binary which you can copy to your Apache bin dir if
  is is your first install then you need to "make install" as well)
$ cd ../php-4.x.y
$ cp php.ini-dist /usr/local/lib/php.ini
You can edit /usr/local/lib/php.ini file to set PHP options.
Edit your httpd.conf or srm.conf file and add:
  AddType application/x-httpd-php .php


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 php-4.x.y.tar.gz.
   Unzip this file with a command like: gunzip php-4.x.y.tar.gz

   Next you have to untar it with: tar -xvf php-4.x.y.tar

   This will create a php-4.x.y directory.  cd into this new directory.

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

   Make sure you specify the version of apxs that is actually installed on
   your system and NOT the one that is in the apache source tarball.
   
   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

   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.  You need
   to know where the source code directory for your Apache server is
   located.  Then use an option like: --with-apache=/usr/local/src/apache
   if that is your Apache source code directory.  If you only specify
   --with-apache, then it will default to look for your Apache source 
   in /usr/local/etc/httpd.

   NOTE: The directory you specify should be the top-level of the
   unpacked Apache (or Stronghold) distribution. The configure program
   will automatically look for httpd.h in different directories under that
   location depending on which version of Apache, including Stronghold,
   you are running.

   For MySQL support, since newer versions of MySQL installs its various
   components under /usr/local, this is the default.  If you have
   changed the location you can specify it with: --with-mysql=/opt/local
   for example.  Otherwise just use: --with-mysql

   *NOTE*  If you are using Apache 1.3b6 or later, you should run the 
   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/php5 directory in your Apache distribution if
   you are using Apache 1.3.x.  If you are still running Apache 1.2.x
   these files will be copied directly to the main src directory.

   For Apache 1.3b6 and later, you can use the new APACI configuration
   mechanism.  To automatically build Apache with PHP support, use:

       cd apache_1.3.x
       ./configure --prefix=/<path>/apache \
                   --activate-module=src/modules/php5/libphp5.a
       make
       make install

   If you do not wish to use this new configuration tool, the old
   install procedure (src/Configure) will work fine.

   If you are using the old Apache ./Configure script, you will have to 
   edit the Apache src/Configuration file manually.  If you do not have 
   this file, copy Configuration.tmpl to Configuration.

   For Apache 1.3.x add:

      AddModule modules/php5/libphp5.a

   For Apache 1.3.x don't do anything else.  Just add this line and then
   run "./Configure" followed by "make".

   For Apache 1.2.x add:

      Module php5_module mod_php5.o

   For Apache 1.2.x you will also have to look in the libphp5.module file,
   which was copied to the src directory. The EXTRA_LIBS line in the Apache
   Configuration file needs to be set to use the same libs as specified on
   the LIBS line in libphp5.module. You also need to make sure to add
   "-L." to the beginning of the EXTRA_LIBS line.

   So, as an example, your EXTRA_LIBS line might look like:

	EXTRA_LIBS=-L. -lphp5 -lgdbm -ldb -L/usr/local/mysql/lib -lmysqlclient

   NOTE: You should not enclose the EXTRA_LIBS line in double-quotes, as it
   is in the libphp5.module file.

   Also, look at the RULE_WANTHSREGEX setting in the libphp5.module file 
   and set the WANTHSREGEX directive accordingly in your Configuration file.
   This last step applies to versions of Apache prior to 1.3b3.

   This is a bit of a hassle, but should serve as incentive to move to
   Apache 1.3.x where this step has been eliminated.

   Once you are satisfied with your Configuration settings, type: ./Configure
   If you get errors, chances are that you forgot a library or made a typo
   somewhere.  Re-edit Configuration and try again.  If it goes well,
   type: make

   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 php5_module libexec/libphp5.so

   The actual path before the libphp5.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 libphp5.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_php5.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.

   Finally you need to copy php.ini-dist to the appropriate place
   (normally /usr/local/lib/php.ini) and edit if necessary.

   Once you have made these changes you should be ready to restart your
   server and try it out.  Type: apachectl restart
   
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/httpd.conf file
   and add the line:

      AddType application/x-httpd-php .php

   There is also an interesting feature which can be quite instructive and
   helpful while debugging.  That is the option of having colour syntax
   highlighting.  To enable this, add the following line:

      AddType application/x-httpd-php-source .phps

   Any file ending in .phps will now be displayed with full colour syntax
   highlighting instead of being executed.

   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.

   When you are finished making changes to your httpd.conf file, you need
   to copy php.ini-dist to the appropriate place (normally
   /usr/local/lib/php.ini) and edit if necessary. You can then
   start up your server.

5. Testing it all worked

   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.  


WHY DISABLING -fPIC WORKS ON LINUX

    From: Martin v. Loewis <martin@loewis.home.cs.tu-berlin.de>
    To: glibc-linux@ricardo.ecn.wfu.edu
    Subject: Re: Shared library -shared vs. -fpic

    [In reply to Kaz Kylheku <kaz@ashi.footprints.net>]

    > PIC stands for Position-Independent Code. 

    Correct.

    > Code isn't position-independent (or ``relocatable'') cannot be
    > loaded at an arbitrary address;

    Wrong.

    > it requires some references to be patched at load time.

    Correct.

    > Shared libraries need to be relocatable because it's not known
    > beforehand what address they will be loaded at

    Correct, depending on the meaning of "relocatable". PIC code typically
    does not contain relocations; that's why its position-independent.

    > Just because you don't specify -fPIC doesn't mean that the compiler
    > won't emit position-independent code; the option prevents it from
    > emitting position-dependent code in situations where it otherwise
    > would.

    Correct. However, a non-trivial shared library typically won't be
    position-independent unless explicitly compiled with
    -fPIC. Linux/glibc indeed does not require a shared library to be
    position-independent; instead, it will perform the relocations in the
    binary, even if they refer to code pages. As a result, those relocated
    pages won't be shared across processes, anymore.

    Regards,
    Martin

USING PHP 3 AND PHP 4 AS CONCURRENT APACHE MODULES

   With some (newer) installations of Apache, it's possible to compile both
   PHP 3 and PHP 4, and run them concurrently. 

   Note, it's only really wise to do this if you need to use the PHP 3 engine
   to maintain backwards compatibility. 
   
   To enable it, configure PHP 3 and PHP 4 to use APXS (--with-apxs) and the
   necessary link extensions (--enable-versioning). Otherwise, all standard
   installations instructions apply. For example:

   		$ ./configure \
				--with-apxs=/apache/bin/apxs \
				--enable-versioning \
				--with-mysql \