$Id$

=============================================================================

HOW TO CREATE A SELF-CONTAINED PHP EXTENSION

A self-contained extension can be distributed independently of

the PHP source. To create such an extension, two things are

required:

- Configuration file (config.m4)

- Source code for your module

We will describe now how to create these and how to put things

together.

PREPARING YOUR SYSTEM

While the result will run on any system, a developer's setup needs these

tools:

GNU autoconf

GNU automake

GNU libtool

GNU m4

All of these are available from

ftp://ftp.gnu.org/pub/gnu/

CONVERTING AN EXISTING EXTENSION

Just to show you how easy it is to create a self-contained

extension, we will convert an embedded extension into a

self-contained one. Install PHP and execute the following

commands.

$ mkdir /tmp/newext

$ cd /tmp/newext

You now have an empty directory. We will copy the files from

the mysql extension:

$ cp -rp php-4.0.X/ext/mysql/* .

It is time to finish the module. Run:

$ phpize

You can now ship the contents of the directory - the extension

can live completely on its own.

The user instructions boil down to

$ ./configure \

[--with-php-config=/path/to/php-config] \

[--with-mysql=MYSQL-DIR]

$ make install

The MySQL module will either use the embedded MySQL client

library or the MySQL installation in MYSQL-DIR.

DEFINING THE NEW EXTENSION

Our demo extension is called "foobar".

It consists of two source files "foo.c" and "bar.c"

(and any arbitrary amount of header files, but that is not

important here).

The demo extension does not reference any external

libraries (that is important, because the user does not

need to specify anything).

LTLIBRARY_SOURCES specifies the names of the sources files. You can

name an arbitrary number of source files here.

CREATING THE M4 CONFIGURATION FILE

The m4 configuration can perform additional checks. For a

self-contained extension, you do not need more than a few

macro calls.

------------------------------------------------------------------------------

PHP_ARG_ENABLE(foobar,whether to enable foobar,

[ --enable-foobar Enable foobar])

if test "$PHP_FOOBAR" != "no"; then

PHP_NEW_EXTENSION(foobar, foo.c bar.c, $ext_shared)

fi

------------------------------------------------------------------------------

PHP_ARG_ENABLE will automatically set the correct variables, so

that the extension will be enabled by PHP_NEW_EXTENSION in shared mode.

The first argument of PHP_NEW_EXTENSION describes the name of the

extension. The second names the source-code files. The third passes

$ext_shared which is set by PHP_ARG_ENABLE/WITH to PHP_NEW_EXTENSION.

Please use always PHP_ARG_ENABLE or PHP_ARG_WITH. Even if you do not

plan to distribute your module with PHP, these facilities allow you

to integrate your module easily into the main PHP module framework.

CREATING SOURCE FILES

ext_skel can be of great help when creating the common code for all modules

in PHP for you and also writing basic function definitions and C code for

handling arguments passed to your functions. See README.EXT_SKEL for further

information.

As for the rest, you are currently alone here. There are a lot of existing

modules, use a simple module as a starting point and add your own code.

CREATING THE SELF-CONTAINED EXTENSION

Put config.m4 and the source files into one directory. Then, run phpize

(this is installed during make install by PHP 4.0).

For example, if you configured PHP with --prefix=/php, you would run

$ /php/bin/phpize

This will automatically copy the necessary build files and create

configure from your config.m4.

And that's it. You now have a self-contained extension.

INSTALLING A SELF-CONTAINED EXTENSION

An extension can be installed by running:

$ ./configure \

[--with-php-config=/path/to/php-config]

$ make install

ADDING SHARED MODULE SUPPORT TO A MODULE

In order to be useful, a self-contained extension must be loadable

as a shared module. I will explain now how you can add shared module

support to an existing module called foo.

1. In config.m4, use PHP_ARG_WITH/PHP_ARG_ENABLE. Then you will

automatically be able to use --with-foo=shared[,..] or

--enable-foo=shared[,..].

2. In config.m4, use PHP_NEW_EXTENSION(foo,.., $ext_shared) to enable

building the extension.

3. Add the following lines to your C source file:

#ifdef COMPILE_DL_FOO

ZEND_GET_MODULE(foo)

#endif