Chapter 27. 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 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.

Example 27-1shows the previously generated Makefile.in:

# $Id: Extending_Zend_Build.xml,v 1.6 2002/03/25 08:13:46 hholzgra 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 Example 27-2'/> is a bit more complex:

dnl $Id: Extending_Zend_Build.xml,v 1.6 2002/03/25 08:13:46 hholzgra 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.