PHP: PHP's Automatic Build System - Manual

downloads | documentation | faq | getting help | mailing lists | reporting bugs | php.net sites | links | conferences | my php.net

search for in the

Creating Extensions Source Layout

Last updated: Fri, 26 Jan 2007

view this page in

# PHP's Automatic Build System

PHP 4 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 a config.m4 file, for extension configuration. (for example, see http://www.gnu.org/software/m4/manual/m4.html)

All these stub 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 stub files.

Step by step, the process looks like this:

    :~/cvs/php4/ext:> ./ext_skel --extname=my_module
    Creating directory my_module
    Creating basic files: config.m4 .cvsignore my_module.c php_my_module.h CREDITS EXPERIMENTAL tests/001.phpt my_module.php [done].

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

    1.  $ cd ..
    2.  $ vi ext/my_module/config.m4
    3.  $ ./buildconf
    4.  $ ./configure --[with|enable]-my_module
    5.  $ make
    6.  $ ./php -f ext/my_module/my_module.php
    7.  $ vi ext/my_module/my_module.c
    8.  $ make

    Repeat steps 3-6 until you are satisfied with ext/my_module/config.m4 and
    step 6 confirms that your module is compiled into PHP. Then, start writing
    code and 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.

The default `config.m4` shown in Прим. 46-1 is a bit more complex:

Пример 46-1. The default `config.m4`.

    dnl $Id: build.xml,v 1.1 2005/08/21 16:27:06 goba Exp $
    dnl config.m4 for extension my_module

    dnl Comments in this file start with the string 'dnl'.
    dnl Remove where necessary. This file will not work
    dnl without editing.

    dnl If your extension references something external, use with:

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

    dnl Otherwise use enable:

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

    if test "$PHP_MY_MODULE" != "no"; then
      dnl Write more examples of tests here...

      dnl # --with-my_module -> check with-path
      dnl SEARCH_PATH="/usr/local /usr"     # you might want to change this
      dnl SEARCH_FOR="/include/my_module.h"  # you most likely want to change this
      dnl if test -r $PHP_MY_MODULE/; then # path given as parameter
      dnl   MY_MODULE_DIR=$PHP_MY_MODULE
      dnl else # search default path list
      dnl   AC_MSG_CHECKING([for my_module files in default path])
      dnl   for i in $SEARCH_PATH ; do
      dnl     if test -r $i/$SEARCH_FOR; then
      dnl       MY_MODULE_DIR=$i
      dnl       AC_MSG_RESULT(found in $i)
      dnl     fi
      dnl   done
      dnl fi
      dnl
      dnl if test -z "$MY_MODULE_DIR"; then
      dnl   AC_MSG_RESULT([not found])
      dnl   AC_MSG_ERROR([Please reinstall the my_module distribution])
      dnl fi

      dnl # --with-my_module -> add include path
      dnl PHP_ADD_INCLUDE($MY_MODULE_DIR/include)

      dnl # --with-my_module -> chech for lib and symbol presence
      dnl LIBNAME=my_module # you may want to change this
      dnl LIBSYMBOL=my_module # you most likely want to change this

      dnl PHP_CHECK_LIBRARY($LIBNAME,$LIBSYMBOL,
      dnl [
      dnl   PHP_ADD_LIBRARY_WITH_PATH($LIBNAME, $MY_MODULE_DIR/lib, MY_MODULE_SHARED_LIBADD)
      dnl   AC_DEFINE(HAVE_MY_MODULELIB,1,[ ])
      dnl ],[
      dnl   AC_MSG_ERROR([wrong my_module lib version or lib not found])
      dnl ],[
      dnl   -L$MY_MODULE_DIR/lib -lm -ldl
      dnl ])
      dnl
      dnl PHP_SUBST(MY_MODULE_SHARED_LIBADD)

      PHP_NEW_EXTENSION(my_module, my_module.c, $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.

add a note User Contributed Notes
PHP's Automatic Build System
wilf at bigpond dot net dot au
15-Jun-2003 12:26
`Another caching problem:
If you seen a message saying that 'may contain buggy cache code', ensure that you delete the 'autom4k...cache' directory before running buildconf.
A good test the see if your new module has been picked up by buildconf is:
$ grep -c my_module configure
(if that returns 0 then buildconf did not work).
Unfortunately this means that you have to completely rebuild your configure script each time you change an M4 file but it doesnt take too long.`
wendywds at hotmail dot com
11-May-2003 03:39
`Using php-4.3.1 on Redhat Linux 8, step 6 did not work as written. There is no php executable in /usr/php-4.3.1. Instead, with help from the pear-general mailing list, I discovered that the newly built php executable is in /usr/php-4.3.1/sapi/cli. (The very end of the output of 'make' shows -o sapi/cli/php. According to Johannes on pear-general, it might be in sapi/cgi instead.)
So I had to change step 6 to:
6. $ sapi/cli/php -f ext/my_module/my_module.php`
john dot gallet at wanadoo dot fr
04-Jan-2002 04:39
`Distinction between --with and --enable : the "something external" means for exemple a shared object. If you are writing a C wrapper for an existing .so library, you should use --with
Do not forget the "cache" effect to modifyng M4 files. When you are testing and getting erros, be sure to delete config.cache before re-running buildconf and ./configure (I spent an hour looking for an error that was not there any more because of that).
HTH and happy developpment.`
add a note
Creating Extensions Source Layout

Last updated: Fri, 26 Jan 2007
show source | credits | stats | sitemap | contact | advertising | mirror sites
Copyright © 2001-2007 The PHP Group
All rights reserved.
This mirror generously provided by: Yahoo! Inc.
Last updated: Sat Mar 10 10:36:09 2007 PST