The config.m4 File (Programming PHP)

14.4. The config.m4 File

The config.m4 file contains the code that will go into the configure script. This includes the switch that enables the extension (e.g., --enable-rot13 or --with-rot13), the name of the shared library to build, code to search for prerequisite libraries, and much more. The skeletal config.m4 file contains sample code for the various things you might want to do, commented out.

There are conventions governing the configure switch to enable your extension. If your extension does not rely on any external components, use --enable-foo. If it does have some nonbundled dependencies, such as a library, use --with-foo. Optionally, you can specify a base path using --with-foo=/some/path, which helps configure find the dependencies.

PHP uses the grand unifying scheme of autoconf, automake, and libtool to build extensions. These three tools, used together, can be extremely powerful, but they can also be extremely frustrating. Getting this stuff right is a bit of a black art. When an extension is part of the PHP source tree and you run the buildconf script in the top directory of the tree, it scans through all its subdirectories looking for config.m4 files. It grabs all the config.m4 files and creates a single configure script that contains all the configure switches. This means that each extension needs to implement its own configure checks to check for whatever dependencies and system-level features might be needed to build the extension.

These checks are done through autoconf macros and general m4 scripting in the config.m4 file. Your best bet is probably to look at some of the existing config.m4 files in the various PHP extensions to see how different types of checks are done.

14.4.1. No External Dependencies

Here is a sample from the simple EXIF extension, which has no external dependencies:

dnl config.m4 for extension exif
  
PHP_ARG_ENABLE(exif, whether to enable exif support,
 [  --enable-exif           Enable exif support])
  
if test "$PHP_EXIF" != "no"; then
  AC_DEFINE(HAVE_EXIF, 1, [Whether you want exif support])
  PHP_EXTENSION(exif, $ext_shared)
fi

The dnl string indicates a comment line. Here we define HAVE_EXIF if --enable-exif was given. In our exif.c code, we then surround the whole file with:

#if HAVE_EXIF
...
#endif

This ensures that no EXIF functionality is compiled in unless the feature was requested. The PHP_EXTENSION line enables this extension to be compiled as a shared, dynamically loadable extension using --enable-exif=shared.

14.4.2. External Dependencies

The libswf extension (which builds Flash animations) requires the libswf library. To enable it, configure PHP with --with-swf. The config.m4 file for libswf must find the library if it wasn't supplied via --with-swf=/path/to/lib: for the libswf extension.

dnl config.m4 for extension libswf
  
PHP_ARG_WITH(swf, for libswf support,
[  --with-swf[=DIR]        Include swf support])
  
if test "$PHP_SWF" != "no"; then
  if test -r $PHP_SWF/lib/libswf.a; then
    SWF_DIR=$PHP_SWF
  else
    AC_MSG_CHECKING(for libswf in default path)
    for i in /usr/local /usr; do
      if test -r $i/lib/libswf.a; then
        SWF_DIR=$i
        AC_MSG_RESULT(found in $i)
      fi
    done
  fi
  
  if test -z "$SWF_DIR"; then
    AC_MSG_RESULT(not found)
    AC_MSG_ERROR(Please reinstall the libswf distribution - swf.h should 
                 be <swf-dir>/include and libswf.a should be in <swf-dir>/lib)
  fi
  PHP_ADD_INCLUDE($SWF_DIR/include)
  
  PHP_SUBST(SWF_SHARED_LIBADD)
  PHP_ADD_LIBRARY_WITH_PATH(swf, $SWF_DIR/lib, SWF_SHARED_LIBADD)
  AC_DEFINE(HAVE_SWF,1,[ ])
  
  PHP_EXTENSION(swf, $ext_shared)
fi

The AC_MSG_CHECKING( ) macro is used to make configure print a message about what it's checking for. When we've found the include files, we add them to PHP's standard include search path with the PHP_ADD_INCLUDE( ) macro. When we find the SWF shared libraries, we add them to the library search path and ensure that we link them into the final binary through the PHP_ADD_LIBRARY_WITH_PATH( ) macro. Things can get a lot more complex than this once you start worrying about different versions of libraries and different platforms. For a very complex example, see the GD library's config.m4 in ext/gd/config.m4.