=========================================================================
Requirements
=========================================================================

- PHP 5.1.6 (http://www.php.net/downloads.php)
- Ice for C++ 3.1.1 Development Kit


=========================================================================
Building PHP with the Ice extension (Linux/Solaris/HP-UX/MacOS X/AIX)
=========================================================================

PHP's build system can create several versions of the PHP interpreter.
There are the command-line interface (CLI) and Common Gateway
Interface (CGI) interpreters, both of which are standalone
executables. In addition, the build system can package the interpreter
as a shared library for use as a Web server module.

To further complicate matters, PHP extensions (such as the Ice
extension) can be either static or dynamic. A static extension is
compiled into the interpreter, whereas a dynamic extension is created
as a standalone shared library that is installed in PHP via
configuration directives.

The Ice extension for PHP supports both static and dynamic
configurations. The only supported way to compile the Ice extension is
as part of the larger PHP build process. Unfortunately, PHP's build
system does not completely accommodate extensions written in C++,
therefore some manual intervention is required on certain platforms.

If you are compiling PHP as a Web server module, please be aware that
you will likely also need to install the Web server's development kit.
For example, the apxs utility is required to build PHP for Apache, and
this utility is not typically included in an Apache run time
installation. You must either build Apache from source, or install an
additional package that contains Apache's development tools.


Adding the Ice extension
------------------------

After downloading and extracting the PHP5 source code, you must
incorporate the Ice extension sources into the PHP5 source tree.
There are two ways to do this:

1) Copy the extension source directory.

   $ cd <icephpdir>
   $ cp -r src/ice <phpdir>/ext

2) Create a symbolic link to the extension:

   $ cd <phpdir>/ext
   $ ln -s <icephpdir>/src/ice ice


Updating configure
------------------

In order to make the PHP build system aware of the Ice extension, the
configure script must be updated. The IcePHP distribution includes
a replacement script that you can install:

$ cd <phpdir>
$ cp <icephpdir>/configure.gz .
$ gunzip configure.gz

Alternatively, you can regenerate the configure script yourself if you
have the necessary utilities installed on your system:

$ cd <phpdir>
$ rm -rf configure autom4te.cache
$ ./buildconf --force


Running configure
-----------------

Set the CC and CXX environment variables to the names of your C and
C++ compilers, respectively.

You are now ready to configure PHP. To include support for a static
Ice extension, use the --with-ice option to specify the location of
the Ice installation:

$ ./configure --with-ice=$ICE_HOME ...

If you want to build a dynamic Ice extension, use this version of the
--with-ice option:

$ ./configure --with-ice=shared,$ICE_HOME ...

Note that additional configuration options may be generally necessary.
Please refer to the PHP documentation for more information.


Source patches
--------------

No source patches are necessary to compile PHP 5.1.6 on the supported
platforms.


Platform-specific Issues
------------------------

Please refer to the relevant section for your platform below before
proceeding any further.


Build PHP
---------

Finally, run make:

$ make

Note that if the Ice extension's config.m4 file is changed, then you
must repeat the steps above to regenerate the configure script, then
execute configure again (or use config.nice instead).

See the PHP documentation for more details on the PHP build process.


=========================================================================
Additional Requirements for Linux with GCC
=========================================================================

If you are building the Ice extension in a dynamic configuration,
edit the file <phpdir>/Makefile and add the following definition:

     EXTRA_CXXFLAGS = -DCOMPILE_DL_ICE


=========================================================================
Additional Requirements for Solaris with Sun CC
=========================================================================

1. Edit the file <phpdir>/libtool, search for the line beginning with
   "archive_cmds=", and change \$LD to \$CXX in the value of both
   archive_cmds and archive_expsym_cmds.

2. Edit the file <phpdir>/Makefile and add -D__sparc__ to CFLAGS.

3. If you are building the Ice extension in a dynamic configuration,
   edit the file <phpdir>/Makefile and add the following definition:

     EXTRA_CXXFLAGS = -DCOMPILE_DL_ICE

4. If you are building the Ice extension in a static configuration,
   edit the file <phpdir>/Makefile and make the following changes:

   - If the command-line interpreter is being built, search for the
     definition of the BUILD_CLI variable and change "$(CC)" to
     "$(CXX)".

   - If the CGI interpreter is being built, search for the definition
     of the BUILD_CGI variable and change "$(CC)" to "$(CXX)".

   - If a Web server module is being built, search for the line
     beginning with "libphp5.la:", and change "$(CC)" to "$(CXX)" in
     that rule, as well as in the rule for "libs/libphp5.bundle"
     below.

Note that PHP 5 cannot be compiled using Sun CC 5.3.


=========================================================================
Additional Requirements for HP-UX with aCC
=========================================================================

The Ice extension currently cannot be used in a dynamic configuration.
To build the Ice extension in a static configuration:

- Edit the file <phpdir>/libtool, search for the line beginning with
  "archive_cmds=", and change \$LD to \$CXX.

- Edit the file <phpdir>/Makefile and make the following changes:

  - Append "-lxnet" to EXTRA_LIBS, as shown below:

    EXTRA_LIBS = -lm -lnsl -lIce -lSlice -lIceUtil -lxnet

  - Add a definition for EXTRA_CXXFLAGS. For 32-bit platforms, use the
    following setting:

    EXTRA_CXXFLAGS = -AA +Z -mt +DA2.0N

    For 64-bit platforms, use this setting:

    EXTRA_CXXFLAGS = -AA +Z -mt +DD64

  - Modify EXTRA_LDFLAGS_PROGRAM to append "$(EXTRA_CXXFLAGS) -Wl,+s"

  - If the command-line interpreter is being built, search for the
    definition of the BUILD_CLI variable and change "$(CC)" to
    "$(CXX)".

  - If the CGI interpreter is being built, search for the definition
    of the BUILD_CGI variable and change "$(CC)" to "$(CXX)".

  - If a Web server module is being built, search for the line
    beginning with "libphp5.la:", and change "$(CC)" to "$(CXX)" in
    that rule, as well as in the rule for "libs/libphp5.bundle" below.


=========================================================================
Additional Requirements for MacOS X
=========================================================================

Edit the file <phpdir>/libtool, search for the line beginning with
"archive_cmds=", and change \$CC to \$CXX.

If you are building the Ice extension in a static configuration, edit
the file <phpdir>/Makefile and make the following changes:

- If the command-line interpreter is being built, search for the
  definition of the BUILD_CLI variable and change "$(CC)" to "$(CXX)".

- If the CGI interpreter is being built, search for the definition of
  the BUILD_CGI variable and change "$(CC)" to "$(CXX)".

- If a Web server module is being built, search for the line beginning
  with "libphp5.la:", and change "$(CC)" to "$(CXX)" in that rule, as
  well as in the rule for "libs/libphp5.bundle" below.

If you are building the Ice extension in a dynamic configuration,
edit the file <phpdir>/Makefile and add the following definition:

     EXTRA_CXXFLAGS = -DCOMPILE_DL_ICE


=========================================================================
Additional Requirements for AIX with VisualAge 6.0
=========================================================================

The Ice extension currently cannot be used in a dynamic configuration.
To build the Ice extension in a static configuration:

- Edit the file <phpdir>/Makefile and make the following changes:

  - Add a definition for EXTRA_CXXFLAGS. For 32-bit platforms, use the
    following setting:

    EXTRA_CXXFLAGS = -brtl -qrtti=all -qstaticinline -D_LARGE_FILES

    For 64-bit platforms, use this setting:

    EXTRA_CXXFLAGS = -brtl -qrtti=all -qstaticinline

  - If the command-line interpreter is being built, search for the
    definition of the BUILD_CLI variable and change "$(CC)" to
    "$(CXX)".

    In the same variable, replace this portion

    BUILD_CLI = echo '\#! .' > php.sym ...

    with

    BUILD_CLI = echo > php.sym ...

  - If the CGI interpreter is being built, search for the definition
    of the BUILD_CGI variable and change "$(CC)" to "$(CXX)".

    In the same variable, replace this portion

    BUILD_CGI = echo '\#! .' > php.sym ...

    with

    BUILD_CGI = echo > php.sym ...

  - If a Web server module is being built, search for the line
    beginning with "libphp5.la:", and change "$(CC)" to "$(CXX)" in
    that rule, as well as in the rule for "libs/libphp5.bundle" below.


=========================================================================
Building PHP with the Ice extension (Windows)
=========================================================================

Compiling PHP from source code on Windows is a tedious process,
therefore we recommend that you download the precompiled dynamic
Ice extension from the ZeroC web site (included in the Ice installer
for Visual C++ 6.0) and use the binary PHP distribution if possible.

If you prefer to build the Ice extension yourself, you must first
understand the C run time dependency issues. Specifically, the Ice
extension must use the same C run time as PHP5. Since the binary
distribution of PHP5 available from php.net depends on the Visual C++
6.0 run time DLL (MSVCRT), you must also build the Ice extension using
Visual C++ 6.0 if you want to use Ice with this PHP distribution. This
is the reason why the precompiled Ice extension is included in the Ice
installer for Visual C++ 6.0, as attempting to use an Ice extension
that was built with a newer compiler together with the binary PHP
distribution results in undefined behavior.

To use a later version of Visual C++, you must obtain (or build) PHP5
with the desired compiler, and use the same compiler to build the Ice
extension.

Follow these instructions to build the Ice extension:

1) Download and extract the PHP5 sources so that the PHP header files
   are available.

2) Download and extract the PHP5 binary distribution for Windows.

3) Have a suitable Ice development environment.

4) Configure the include and library paths in Visual C++ for PHP and
   Ice. Assuming that you've extracted the PHP5 sources into C:\PHP5,
   the binary distribution into C:\PHP5-Win32, and installed Ice into
   C:\Ice, then the following paths must be configured:

   Include:
     C:\PHP5
     C:\PHP5\main
     C:\PHP5\Zend
     C:\PHP5\TSRM
     C:\Ice\include

   Library:
     C:\PHP5-Win32\dev
     C:\Ice\lib

   If you are using Visual C++ 6.0, then you must also be sure to
   include the appropriate paths for STLport.

4) Open the workspace icephp.dsw, select the Debug or Release
   configuration, and build php_ice.dll. Note that the Ice extension
   must be compiled using the same Debug/Release configuration as PHP
   itself. If you are linking against the dynamic libraries included
   in the binary PHP distribution, you must use the Release
   configuration when compiling the Ice extension.


=========================================================================
Installing a Dynamic Extension
=========================================================================

If you are using the dynamic Ice extension, you must move the
extension's shared library into PHP's extension directory. This
directory is determined by the PHP configuration directive
"extension_dir". You can determine the default value for this
directive by running the command-line version of PHP with the -i
option.

After compiling the dynamic extension on Linux and Solaris, the shared
library can be found in the "modules" subdirectory of the PHP source
tree. If you've compiled the dynamic Ice extension on Windows, the
DLL is located in bin/debug/php_ice.dll or bin/release/php_ice.dll,
depending on the build configuration you selected.

Once you've copied the dynamic extension to PHP's extension directory,
you will need to enable the extension in PHP configuration. In php.ini,
use the following directive on Linux and Solaris:

extension = ice.so

On Windows, use this directive:

extension = php_ice.dll


=========================================================================
Dependencies
=========================================================================

Whether you build a dynamic or static Ice extension, PHP will need
to be able to locate the Ice run-time libraries "Ice", "Slice",
"IceUtil" and "bzip2" (Windows) or "libbz2" (Unix). In general, these
libraries must reside in a directory of the user's PATH.

For Web servers, the libraries may need to reside in a system
directory. For example, on Linux you can add the directory containing
the Ice run-time libraries to /etc/ld.so.conf and run ldconfig. On
Windows, you can copy the DLLs to the C:\WINDOWS\system32 directory,
or to the Apache installation directory.

You can verify that the Ice extension is installed properly by
examining the output of the "php -m" command, or by calling the
phpinfo() function from a script.

Note that if you want to use IceSSL from the Ice extension, then PHP
will also need access to the shared library for IceSSL.

Finally, the Ice extension will need to execute the Ice preprocessor
(icecpp), therefore this binary must reside in an accessible directory.


=========================================================================
SELinux Notes
=========================================================================

By default, the security restrictions in "Security Enhanced Linux"
(SELinux) prevent an IcePHP script from connecting to an Ice server on
the Web server host. With sufficient privileges, you can modify the
security policies on your system to relax this restriction for the
Web server daemon, or you can temporarily change SELinux to
"permissive" mode with the following command:

# setenforce 0

See this FAQ for more information on SELinux:

http://fedora.redhat.com/docs/selinux-faq/


=========================================================================
Running the Tests
=========================================================================

The test subdirectory contains PHP implementations of the core Ice
test suite. In order to run these tests, you must have Python 2.2
or later, and the Ice for C++ tests must be built in the directory
specified by the ICE_HOME environment variable.

The test scripts require that the CLI version of the PHP interpreter
be available in your PATH, and assume that the Ice extension was
built in a static configuration.

To run all of the tests, do the following:

$ python allTests.py

You can also run tests individually by changing to the test directory
and running this command:

$ python run.py

In order to run the tests using a dynamic Ice extension, you will
need to edit the php.ini files in each test directory and add the
following configuration directives:

extension_dir=<phpdir>/modules
extension=ice.so
