PHP Manual
Prev |  | Next

# Chapter 27. PHP's Automatic Build System

PHP 4.0 features an automatic build system that's very flexible. All modules reside in a subdirectory of the `ext` directory. In addition to its own sources, each module consists of an M4 file (for example, see http://www.gnu.org/manual/m4/html_mono/m4.html) for configuration and a Makefile.in file, which is responsible for compilation (the results of autoconf and automake; for example, see http://sourceware.cygnus.com/autoconf/autoconf.html and http://sourceware.cygnus.com/automake/automake.html).

Both files are generated automatically, along with `.cvsignore`, by a little shell script named `ext_skel` that resides in the `ext` directory. As argument it takes the name of the module that you want to create. The shell script then creates a directory of the same name, along with the appropriate `config.m4` and `Makefile.in` files.

Step by step, the process looks like this:

    root@dev:/usr/local/src/php4/ext > ./ext_skel my_module
    Creating directory
    Creating basic files: config.m4 Makefile.in .cvsignore [done].

    To use your new extension, you will have to execute the following steps:

        $ cd ..
        $ ./buildconf
        $ ./configure                 (your extension is automatically enabled)
        $ vi ext/my_module/my_module.c
        $ make

    Repeat the last two steps as often as necessary.

This instruction creates the aforementioned files. To include the new module in the automatic configuration and build process, you have to run `buildconf`, which regenerates the `configure` script by searching through the `ext` directory and including all found `config.m4` files.

Finally, running `configure` parses all configuration options and generates a makefile based on those options and the options you specify in `Makefile.in`.

Listing 9.1 shows the previously generated `Makefile.in`:

Figure 27-1. Listing 9.1. The default `Makefile.in`.

    # $Id: Extending_Zend.xml,v 1.22 2001/12/16 22:01:39 mfischer Exp $

    LTLIBRARY_NAME        = libmy_module.la
    LTLIBRARY_SOURCES     = my_module.c
    LTLIBRARY_SHARED_NAME = my_module.la

    include $(top_srcdir)/build/dynlib.mk

There's not much to tell about this one: It contains the names of the input and output files. You could also specify build instructions for other files if your module is built from multiple source files.

The default `config.m4` shown in Listing 9.2 is a bit more complex:

Figure 27-2. Listing 9.2. The default `config.m4`.

    dnl $Id: Extending_Zend.xml,v 1.22 2001/12/16 22:01:39 mfischer Exp $
    dnl config.m4 for extension my_module
    dnl don't forget to call PHP_EXTENSION(my_module)

    dnl If your extension references something external, use with:

    PHP_ARG_WITH(my_module, for my_module support,
    dnl Make sure that the comment is aligned:
    [  --with-my_module             Include my_module support])

    dnl Otherwise use enable:

    PHP_ARG_ENABLE(my_module, whether to enable my_module support,
    dnl Make sure that the comment is aligned:
    [  --enable-my_module           Enable my_module support])

    if test "$PHP_MY_MODULE" != "no"; then
      dnl Action..
      PHP_EXTENSION(my_module, $ext_shared)
    fi

If you're unfamiliar with M4 files (now is certainly a good time to get familiar), this might be a bit confusing at first; but it's actually quite easy.

Note: Everything prefixed with `dnl` is treated as a comment and is not parsed.

The `config.m4` file is responsible for parsing the command-line options passed to `configure` at configuration time. This means that it has to check for required external files and do similar configuration and setup tasks.

The default file creates two configuration directives in the `configure` script: `--with-my_module` and `--enable-my_module`. Use the first option when referring external files (such as the `--with-apache` directive that refers to the Apache directory). Use the second option when the user simply has to decide whether to enable your extension. Regardless of which option you use, you should uncomment the other, unnecessary one; that is, if you're using `--enable-my_module`, you should remove support for `--with-my_module`, and vice versa.

By default, the `config.m4` file created by `ext_skel` accepts both directives and automatically enables your extension. Enabling the extension is done by using the `PHP_EXTENSION` macro. To change the default behavior to include your module into the PHP binary when desired by the user (by explicitly specifying `--enable-my_module` or `--with-my_module`), change the test for `$PHP_MY_MODULE` to `== "yes"`:

    if test "$PHP_MY_MODULE" == "yes"; then
      dnl Action..
      PHP_EXTENSION(my_module, $ext_shared)
    fi

This would require you to use `--enable-my_module` each time when reconfiguring and recompiling PHP.

Note: Be sure to run `buildconf` every time you change `config.m4`!

We'll go into more details on the M4 macros available to your configuration scripts later in this chapter. For now, we'll simply use the default files. The sample sources on the CD-ROM all have working `config.m4` files. To include them into the PHP build process, simply copy the source directories to your PHP `ext` directory, run `buildconf`, and then include the sample modules you want by using the appropriate `--enable-*` directives with `configure`.

Prev | Home | Next
Complex Types | Up | Creating Extensions