<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- $Revision: 1.5 $ -->
 <sect1 xml:id="internals2.buildsys.configunix" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Talking to the UNIX build system: config.m4</title>
  <para>
   The <filename>config.m4</filename> file for an extension tells the UNIX
   build system what <filename>configure</filename> options your extension
   supports, what external libraries and includes you require, and what source
   files are to be compiled as part of it. A reference to all the commonly used
   autoconf macros, both PHP-specific and those built into autoconf, is given
   in the <xref linkend="internals2.apiref"/> section.
  </para>
  
  <tip>
   <para>
    When developing a PHP extension, it is <emphasis>strongly</emphasis>
    recommended that <command>autoconf</command> version 2.13 be installed,
    despite the newer releases which are available. Version 2.13 is recognized
    as a common denominator of <command>autoconf</command> availability,
    usability, and user base. Using later versions will sometimes produce
    cosmetic differences from the expected output of
    <command>configure</command>.
   </para>
  </tip>
  
  <example xml:id="internals2.buildsys.configunix.sample-config">
   <title>An example config.m4 file</title>
   <programlisting role="autoconf">
dnl &#x24;Id$
dnl config.m4 for extension example
<![CDATA[
PHP_ARG_WITH(example, for example support,
[  --with-example[=FILE]       Include example support. File is the optional path to example-config])
PHP_ARG_ENABLE(example-debug, whether to enable debugging support in example,
[  --enable-example-debug        example: Enable debugging support in example], no, no)
PHP_ARG_WITH(example-extra, for extra libraries for example,
[  --with-example-extra=DIR      example: Location of extra libraries for example], no, no)

dnl Check whether the extension is enabled at all
if test "$PHP_EXAMPLE" != "no"; then
  
  dnl Check for example-config. First try any path that was given to us, then look in $PATH
  AC_MSG_CHECKING([for example-config])
  EXAMPLE_CONFIG="example-config"
  if test "$PHP_EXAMPLE" != "yes"; then
    EXAMPLE_PATH=$PHP_EXAMPLE
  else
    EXAMPLE_PATH=`$php_shtool path $EXAMPLE_CONFIG`
  fi
  
  dnl If a usable example-config was found, use it
  if test -f "$EXAMPLE_PATH" && test -x "$EXAMPLE_PATH" && $EXAMPLE_PATH --version > /dev/null 2>&1; then
    AC_MSG_RESULT([$EXAMPLE_PATH])
    EXAMPLE_LIB_NAME=`$EXAMPLE_PATH --libname`
    EXAMPLE_INCDIRS=`$EXAMPLE_PATH --incdirs`
    EXAMPLE_LIBS=`$EXAMPLE_PATH --libs`
    
    dnl Check that the library works properly
    PHP_CHECK_LIBRARY($EXAMPLE_LIB_NAME, example_critical_function,
    [
      dnl Add the necessary include dirs
      PHP_EVAL_INCLINE($EXAMPLE_INCDIRS)
      dnl Add the necessary libraries and library dirs
      PHP_EVAL_LIBLINE($EXAMPLE_LIBS, EXAMPLE_SHARED_LIBADD)
    ],[
      dnl Bail out
      AC_MSG_ERROR([example library not found. Check config.log for more information.])
    ],[$EXAMPLE_LIBS]
    )
  else
    dnl No usable example-config, bail  
    AC_MSG_RESULT([not found])
    AC_MSG_ERROR([Please check your example installation.])
  fi
  
  dnl Check whether to enable debugging
  if test "$PHP_EXAMPLE_DEBUG" != "no"; then
    dnl Yes, so set the C macro
    AC_DEFINE(USE_EXAMPLE_DEBUG,1,[Include debugging support in example])
  fi
  
  dnl Check for the extra support
  if test "$PHP_EXAMPLE_EXTRA" != "no"; then
    if test "$PHP_EXAMPLE_EXTRA" == "yes"; then
      AC_MSG_ERROR([You must specify a path when using --with-example-extra])
    fi
    
    PHP_CHECK_LIBRARY(example-extra, example_critical_extra_function,
    [
      dnl Add the neccessary paths
      PHP_ADD_INCLUDE($PHP_EXAMPLE_EXTRA/include)
      PHP_ADD_LIBRARY_WITH_PATH(example-extra, $PHP_EXAMPLE_EXTRA/lib, EXAMPLE_SHARED_LIBADD)
      AC_DEFINE(HAVE_EXAMPLEEXTRALIB,1,[Whether example-extra support is present and requested])
      EXAMPLE_SOURCES="$EXAMPLE_SOURCES example_extra.c"
    ],[
      AC_MSG_ERROR([example-extra lib not found. See config.log for more information.])
    ],[-L$PHP_EXAMPLE_EXTRA/lib]
    )
  fi
  
  dnl Finally, tell the build system about the extension and what files are needed
  PHP_NEW_EXTENSION(example, example.c $EXAMPLE_SOURCES, $ext_shared)
  PHP_SUBST(EXAMPLE_SHARED_LIBADD)
fi
]]>
   </programlisting>
  </example>
  
  <sect2 xml:id="internals2.buildsys.configunix.autoconf">
   <title>A short introduction to autoconf syntax</title>
   <para>
    <filename>config.m4</filename> files are written using the GNU
    <command>autoconf</command> syntax. It can be described in a nutshell as
    shell scripting augmented by a powerful macro language. Comments are
    delimited by the string <literal>dnl</literal>, and strings are quoted
    using left and right brackets (e.g. <literal>[</literal> and
    <literal>]</literal>). Quoting of strings can be nested as many times as
    needed. A full reference to the syntax can be found in the
    <command>autoconf</command> manual at
    <link xlink:href="&url.internals.autoconf;"/>.
   </para>
  </sect2>
  
  <sect2 xml:id="internals2.buildsys.configunix.php-arg">
   <title>PHP_ARG_*: Giving users the option</title>
   <para>
    The very first thing seen in the example <filename>config.m4</filename>
    above, aside from a couple of comments, are three lines using
    <function>PHP_ARG_WITH</function> and <function>PHP_ARG_ENABLE</function>.
    These provide <command>configure</command> with the options and help text
    seen when running <command>./configure --help</command>. As the names
    suggest, the difference between the two is whether they create a
    <option role="configure">--with-*</option> option or an
    <option role="configure">--enable-*</option> option. Every extension should
    provide at least one or the other with the extension name, so that users
    can choose whether or not to build the extension into PHP. By convention,
    <function>PHP_ARG_WITH</function> is used for an option which takes a
    parameter, such as the location of a library or program required by an
    extension, while <function>PHP_ARG_ENABLE</function> is used for an option
    which represents a simple flag.
   </para>
   <example xml:id="internals2.buildsys.configunix.php-arg.configure-out">
    <title>Sample configure output</title>
    <screen>
<![CDATA[
$ ./configure --help
...
  --with-example[=FILE]       Include example support. FILE is the optional path to example-config
  --enable-example-debug        example: Enable debugging support in example
  --with-example-extra=DIR      example: Location of extra libraries for example
...

$ ./configure --with-example=/some/library/path/example-config --disable-example-debug --with-example-extra=/another/library/path
...
checking for example support... yes
checking whether to enable debugging support in example... no
checking for extra libraries for example... /another/library/path
...
]]>
    </screen>
   </example>
   <note>
    <para>
     Regardless of the order in which options are specified on the command line
     when <command>configure</command> is called, the checks will be run in the
     order they are specified in <filename>config.m4</filename>.
    </para>
   </note>
  </sect2>
  
  <sect2 xml:id="internals2.buildsys.configunix.processing">
   <title>Processing the user's choices</title>
   <para>
    Now that <filename>config.m4</filename> can provide the user with some
    choices of what to do, it's time to act upon those choices. In the example
    above, the obvious default for all three options, if any of them are
    unspecified, is &quot;no&quot;. As a matter of convention, it is best to
    use this as the default for the option which enables the extension, as it
    will be overridden by <command>phpize</command> for extensions built
    separately, and should not clutter the extension space by default when
    being built into PHP. The code to process the three options is by far the
    most complicated.
   </para>
   
   <sect3 xml:id="internals2.buildsys.configunix.processing.with-example">
    <title>Handling the --with-example[=FILE] option</title>
    <para>
     The first check made of the
     <option role="configure">--with-example[=FILE]</option> option is whether
     it was set at all. As this option controls the inclusion of the entire
     extension, if it was unspecified, given in the negative form
     (<option role="configure">--without-example</option>), or given the value
     &quot;no&quot;, nothing else is done at all. In the example above, it is
     specified with the value
     <literal>/some/library/path/example-config</literal>, so the first test
     succeeds.
    </para>
    
    <para>
     Next, the code calls <function>AC_MSG_CHECKING</function>, an
     <command>autoconf</command> macro which outputs a standard
     &quot;checking for something&quot; line, and checks whether the user gave
     an explicit path to the fictional <command>example-config</command>. In
     this example, <literal>PHP_EXAMPLE</literal> got the value
     <literal>/some/library/path/example-config</literal>, which is now copied
     into the EXAMPLE_PATH variable. Had the user specified only
     <option role="configure">--with-example</option>, the code would have
     executed <command>$php_shtool path $EXAMPLE_CONFIG</command>, which would
     try to guess the location of <command>example-config</command> using the
     user's current <literal>PATH</literal>. Either way, the next step is to
     check whether the chosen <literal>EXAMPLE_PATH</literal> is a regular
     file, is executable, and can be run successfully. If so,
     <function>AC_MSG_RESULT</function> is called, which completes the output
     line started by <function>AC_MSG_CHECKING</function>. Otherwise,
     <function>AC_MSG_ERROR</function> is called, which prints the given
     message and halts <command>configure</command> immediately.
    </para>
    
    <para>
     The code now determines some site-specific configuration information by
     running <command>example-config</command> several times. The next call is
     to <function>PHP_CHECK_LIBRARY</function>, a macro provided by the PHP
     buildsystem as a wrapper around <command>autoconf</command>'s
     <function>AC_CHECK_LIB</function>. <function>PHP_CHECK_LIBRARY</function>
     attempts to compile, link, and run a program which calls the symbol
     specified by the second parameter in the library specified by the first,
     using the string given in the fifth as extra linker options. If the
     attempt succeeds, the script given in the third parameter is run. This
     script tells the PHP buildsystem to extract include paths, library paths,
     and library names from the raw option strings
     <command>example-config</command> provided. If the attempt fails, the
     script in the fourth parameter is run instead. In this case,
     <function>AC_MSG_ERROR</function> is called to stop processing.
    </para>
   </sect3>
   
   <sect3 xml:id="internals2.buildsys.configunix.processing.enable-example-debug">
    <title>Handling the --enable-example-debug option</title>
    <para>
     Processing the <option role="configure">--enable-example-debug</option> is
     much simpler. A simple check for its truth value is performed. If that
     check succeeds, <function>AC_DEFINE</function> is called to make the C
     macro <literal>USE_EXAMPLE_DEBUG</literal> available to the source of the
     extension. The third parameter is a comment string for
     <filename>config.h</filename>; it is safe to leave this empty, and often is.
    </para>
   </sect3>
   
   <sect3 xml:id="internals2.buildsys.configunix.processing.with-example-extra">
    <title>Handling the --with-example-extra=DIR option</title>
    <para>
     For the sake of this example, the fictional &quot;extra&quot;
     functionality requested by the
     <option role="configure">--with-example-extra=DIR</option> option does not
     share the fictional <command>example-config</command> program, nor does it
     have any default paths to search. Therefore, the user is required to
     provide the installation prefix of the necessary library. This setup is
     somewhat unlikely in a real-world extension, but is considered
     illustrative.
    </para>
    
    <para>
     The code begins in a now-familiar way by checking the truth value of
     <literal>PHP_EXAMPLE_EXTRA</literal>. If a negative form was provided, no
     further processing is done; the user did not request extra functionality.
     If a positive form was provided without a parameter,
     <function>AC_MSG_ERROR</function> is called to halt processing. The next
     step is another invocation of <function>PHP_CHECK_LIBRARY</function>. This
     time, since there is no set of predefined compiler options provided,
     <function>PHP_ADD_INCLUDE</function> and
     <function>PHP_ADD_LIBRARY_WITH_PATH</function> are used to construct the
     necessary include paths, library paths, and library flags for the extra
     functionality. <function>AC_DEFINE</function> is also called to indicate
     to the code that the extra functionality was both requested and available,
     and a variable is set to tell later code that there are extra source files
     to build. If the check fails, the familiar
     <function>AC_MSG_ERROR</function> is called. A different way to handle the
     failure would have been to call <function>AC_MSG_WARNING</function>
     instead, e.g.:
    </para>
    <informalexample>
     <programlisting role="autoconf">
<![CDATA[
      AC_MSG_WARNING([example-extra lib not found. example will be built without extra functionality.])
]]>
     </programlisting>
    </informalexample>
    <para>
     In this case, <command>configure</command> would print a warning message
     rather than an error, and continue processing. Which way such failures are
     handled is a design decision left to the extension developer.
    </para>
   </sect3>
  </sect2>
  
  <sect2 xml:id="internals2.buildsys.configunix.finishing">
   <title>Telling the buildsystem what was decided</title>
   <para>
    With all the necessary includes and libraries specified, with all the
    options processed and macros defined, one more thing remains to be done:
    The build system must be told to build the extension itself, and which
    files are to be used for that. To do this, the
    <function>PHP_NEW_EXTENSION</function> macro is called. The first parameter
    is the name of the extension, which is the same as the name of the
    directory containing it. The second parameter is the list of all source
    files which are part of the extension. See
    <function>PHP_ADD_BUILD_DIR</function> for information about adding source
    files in subdirectories to the build process. The third parameter should
    always be <literal>$ext_shared</literal>, a value which was determined by
    <command>configure</command> when <function>PHP_ARG_WITH</function> was
    called for <option role="configure">--with-example[=FILE]</option>. The
    fourth parameter specifies a &quot;SAPI class&quot;, and is only useful for
    extensions which require the CGI or CLI SAPIs specifically. It should be
    left empty in all other cases. The fifth parameter specifies a list of
    flags to be added to <literal>CFLAGS</literal> while building the
    extension; the sixth is a boolean value which, if &quot;yes&quot;, will
    force the entire extension to be built using <literal>$CXX</literal>
    instead of <literal>$CC</literal>. All parameters after the third are
    optional. Finally, <function>PHP_SUBST</function> is called to enable
    shared builds of the extension. See <xref linkend="internals2.faq"/> for
    more information on disabling support for building an extension in shared
    mode.
   </para>
  </sect2>

  <sect2 xml:id="internals2.buildsys.configunix.counter">
   <title>The counter extension's config.m4 file</title>
   <para>
    The counter extension previously documented has a much simpler
    <filename>config.m4</filename> file than that described above, as it doesn't
    make use of many buildsystem features. This is a preferred method of
    operation for any extension that doesn't use an external or bundled library.
   </para>
   <example xml:id="internals2.buildsys.configunix.counter.configunix">
    <title>counter's config.m4 file</title>
    <programlisting role="autoconf">
<![CDATA[
dnl ]]>&#x24;<![CDATA[Id$
dnl config.m4 for extension counter

PHP_ARG_ENABLE(counter, for counter support,
[  --enable-counter            Include counter support])

dnl Check whether the extension is enabled at all
if test "$PHP_COUNTER" != "no"; then
  dnl Finally, tell the build system about the extension and what files are needed
  PHP_NEW_EXTENSION(counter, counter.c counter_util.c, $ext_shared)
  PHP_SUBST(COUNTER_SHARED_LIBADD)
fi
]]>
    </programlisting>
   </example>
  </sect2>

 </sect1>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"../../../manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->