<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.34 $ -->
<chapter xml:id="faq.build" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
  <title>Build Problems</title>
  <titleabbrev>Build Problems</titleabbrev>

   <para>
    This section gathers most common errors that occur at 
    build time.
   </para>

  <qandaset>
   <qandaentry xml:id="faq.build.configure">
    <question>
     <para>
      I got the latest version of PHP using the anonymous CVS service, 
      but there's no configure script!
     </para>
    </question>
    <answer>
     <para>
      You have to have the GNU autoconf package installed so you can
      generate the configure script from <filename>configure.in</filename>. Just run
      <command>./buildconf</command> in the top-level directory after getting
      the sources from the CVS server. (Also, unless you run configure
      with the <literal>--enable-maintainer-mode</literal> option, the
      configure script will not automatically get rebuilt when the
      <filename>configure.in</filename> file is updated, so you should make sure to do that
      manually when you notice configure.in has changed. One symptom
      of this is finding things like @VARIABLE@ in your Makefile after
      configure or <filename>config.status</filename> is run.)
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.build.configuring">
    <question>
     <para>
      I'm having problems configuring PHP to work with Apache. 
      It says it can't find <filename>httpd.h</filename>, but it's right where I said it is!
     </para>
    </question>
    <answer>
     <para>
      You need to tell the configure/setup script the location of the
      top-level of your Apache source tree. This means that
      you want to specify <option 
      role="configure">--with-apache=/path/to/apache</option>
      and <emphasis>not</emphasis> <option 
      role="configure">--with-apache=/path/to/apache/src</option>.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.build.lex">
    <question>
     <para>
      While configuring PHP (<literal>./configure</literal>), you come across
      an error similar to the following:
     </para>
     <para>
      <screen>
       checking lex output file root... ./configure: lex: command not found
       configure: error: cannot find output from lex; giving up
      </screen>
     </para>
    </question>
    <answer>
     <para>
      Be sure to read the <link linkend="install.unix">installation</link>
      instructions carefully and note that you need both flex and bison
      installed to compile PHP.  Depending on your setup you will install 
      bison and flex from either source or a package, such as a RPM.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.build.apache-sharedcore">
    <question>
     <para>
      When I try to start Apache, I get the following message:
     </para>
     <para>
      <screen>
       fatal: relocation error: file /path/to/libphp4.so:
       symbol ap_block_alarms: referenced symbol not found
      </screen>
     </para>
    </question>
    <answer>
     <para>
      This error usually comes up when one compiles the Apache
      core program as a DSO library for shared usage.  Try to
      reconfigure apache, making sure to use at least the
      following flags:
     </para>
     <para>
      <screen>
      --enable-shared=max --enable-rule=SHARED_CORE
      </screen>
     </para>
     <para>
      For more information, read the top-level Apache
      <filename>INSTALL</filename> file or the Apache
      <link xlink:href="&url.apachedso;">DSO manual page</link>.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.build.not-found">
    <question>
     <para>
      When I run configure, it says that it can't find the 
      include files or library for GD, gdbm, or some other package!
     </para>
    </question>
    <answer>
     <para>
      You can make the configure script looks for header files and libraries
      in non-standard locations by specifying additional flags to pass to
      the C preprocessor and linker, such as:
      <programlisting>
<![CDATA[
    CPPFLAGS=-I/path/to/include LDFLAGS=-L/path/to/library ./configure
]]>
      </programlisting>
      If you're using a csh-variant for your login shell (why?), it would be:
      <programlisting>
<![CDATA[
    env CPPFLAGS=-I/path/to/include LDFLAGS=-L/path/to/library ./configure
]]>
      </programlisting>
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.build.yytname">
    <question>
     <para>
      When it is compiling the file <filename>language-parser.tab.c</filename>, it gives me errors 
      that say <literal>yytname undeclared</literal>.
     </para>
    </question>
    <answer>
     <para>
      You need to update your version of Bison. You can find the latest version
      at <link xlink:href="&url.bison;">&url.bison;</link>.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.build.link">
    <question>
     <para>
      When I run <command>make</command>, it seems to run fine but then fails when it tries 
      to link the final application complaining that it can't find some files.
     </para>
    </question>
    <answer>
     <para>
      Some old versions of make that don't correctly put the compiled
      versions of the files in the functions directory into that same
      directory. Try running <command>cp *.o functions</command> and then
      re-running <command>make</command> to see if that helps. If it does, you should really
      upgrade to a recent version of GNU make.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.build.undefined">
    <question>
     <para>
      When linking PHP, it complains about a number of undefined references.
     </para>
    </question>
    <answer>
     <para>
      Take a look at the link line and make sure that all of the appropriate  
      libraries are being included at the end. Common ones that you might have
      missed are '-ldl' and any libraries required for any database support
      you included.
     </para>
     <para>
      If you're linking with Apache 1.2.x, did you remember to add the
      appropriate information to the EXTRA_LIBS line of the Configuration
      file and re-rerun Apache's Configure script? See the <link
       linkend="install">installation chapter</link> for more information.
     </para>
     <para>
      Some people have also reported that they had to add '-ldl' immediately
      following <filename>libphp4.a</filename> when linking with Apache.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.build.Apache">
    <question>
     <para>
      I can't figure out how to build PHP with Apache 1.3.
     </para>
    </question>
    <answer>
     <para>
      This is actually quite easy.  Follow these steps carefully:
      <itemizedlist>
       <listitem>
        <simpara>
         Grab the latest Apache 1.3 distribution from 
         <link xlink:href="&url.apache.source;">&url.apache.source;</link>.
        </simpara>
       </listitem>
       <listitem>
        <simpara>
         Ungzip and untar it somewhere, for example 
         <filename>/usr/local/src/apache-1.3</filename>.
        </simpara>
       </listitem>
       <listitem>
        <simpara>
         Compile PHP by first running 
         <command>./configure --with-apache=/&lt;path&gt;/apache-1.3</command>
         (substitute &lt;path&gt; for the actual path to your apache-1.3 directory.
        </simpara>
       </listitem>
       <listitem>
        <simpara>
         Type <command>make</command> followed by <command>make install</command>
         to build PHP and copy the necessary files to the Apache distribution tree.
        </simpara>
       </listitem>
       <listitem>
        <simpara>
         Change directories into to your <filename>/&lt;path&gt;/apache-1.3/src</filename>
         directory and edit the <filename>Configuration</filename> file. 
         Add to the file: 
         <literal>AddModule modules/php4/libphp4.a</literal>.
        </simpara>
       </listitem>
       <listitem>
        <simpara>
         Type: <command>./configure</command> followed by <literal>make</literal>.
        </simpara>
       </listitem>
       <listitem>
        <simpara>
         You should now have a PHP-enabled httpd binary!
        </simpara>
       </listitem>
      </itemizedlist>
     </para>
     <para>
      <emphasis>Note:</emphasis> You can also use the new Apache 
      <literal>./configure</literal> script. See the instructions in 
      the <literal>README.configure</literal> file which is part of 
      your Apache distribution.  Also have a look at the <filename>INSTALL</filename> 
      file in the PHP distribution.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.build.not-running">
    <question>
     <para>
      I have followed all the steps to install the Apache module version on 
      Unix, and my PHP scripts show up in my browser or I am being asked to 
      save the file.
     </para>
    </question>
    <answer>
     <para>
      This means that the PHP module is not getting invoked for some reason.
      Three things to check before asking for further help:
      <itemizedlist>
       <listitem>
        <simpara>
         Make sure that the httpd binary you are running is the actual 
         new httpd binary you just built.  To do this, try running: 
         <literal>/path/to/binary/httpd -l</literal>
        </simpara>
        <simpara>
         If you don't see <filename>mod_php4.c</filename> listed then
         you are not running the right binary.  Find and install the
         correct binary.
        </simpara>
       </listitem>
       <listitem>
        <simpara>
         Make sure you have added the correct Mime Type to one of your 
         <literal>Apache .conf</literal> files.  It should be: 
         <literal>AddType application/x-httpd-php .php</literal>
        </simpara>
        <simpara> 
         Also make sure that this AddType line is not hidden away inside a
         &lt;Virtualhost&gt; or &lt;Directory&gt; block which would
         prevent it from applying to the location of your test script.
        </simpara>
       </listitem>
       <listitem>
        <simpara>
         Finally, the default location of the Apache configuration files 
         changed between Apache 1.2 and Apache 1.3.  You should check to 
         make sure that the configuration file you are adding the AddType 
         line to is actually being read. You can put an obvious syntax error
         into your &httpd.conf; file or some other obvious change that will 
         tell you if the file is being read correctly.
        </simpara>
       </listitem>
      </itemizedlist>
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.build.activate-module">
    <question>
     <para>
      It says to use: <literal>--activate-module=src/modules/php4/libphp4.a</literal>, 
      but  that file doesn't exist, so I changed it to 
      <literal>--activate-module=src/modules/php4/libmodphp4.a</literal> and it 
      doesn't work!? What's going on?
     </para>
    </question>
    <answer>
     <para>
      Note that the <filename>libphp4.a</filename> file is not supposed to exist.  The
      apache process will create it!
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.build.ansi">
    <question>
     <para>
      When I try to build Apache with PHP as a static module using 
      <literal>--activate-module=src/modules/php4/libphp4.a</literal> 
      it tells me that my compiler is not ANSI compliant.
     </para>
    </question>
    <answer>
     <para>
      This is a misleading error message from Apache that has been fixed
      in more recent versions.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.build.apxs">
    <question>
     <para>
      When I try to build PHP using <option 
      role="configure">--with-apxs</option> I get strange error messages.
     </para>
    </question>
    <answer>
     <para>
      There are three things to check here.  First, for some reason
      when Apache builds the apxs Perl script, it sometimes ends up
      getting built without the proper compiler and flags variables.
      Find your apxs script (try the command <command>which apxs</command>), 
      it's sometimes found in <filename>/usr/local/apache/bin/apxs</filename>
      or <filename>/usr/sbin/apxs</filename>.
      Open it and check for lines similar to these:
      <programlisting>
<![CDATA[
my $CFG_CFLAGS_SHLIB  = ' ';          # substituted via Makefile.tmpl
my $CFG_LD_SHLIB      = ' ';          # substituted via Makefile.tmpl
my $CFG_LDFLAGS_SHLIB = ' ';          # substituted via Makefile.tmpl
]]>
      </programlisting>
      If this is what you see, you have found your problem.  They may 
      contain just spaces or other incorrect values, such as 'q()'.  Change 
      these lines to say:
      <programlisting>
<![CDATA[
my $CFG_CFLAGS_SHLIB  = '-fpic -DSHARED_MODULE'; # substituted via Makefile.tmpl
my $CFG_LD_SHLIB      = 'gcc';                   # substituted via Makefile.tmpl
my $CFG_LDFLAGS_SHLIB = q(-shared);              # substituted via Makefile.tmpl 
]]>
      </programlisting>
      The second possible problem should only be an issue on Red Hat 6.1
      and 6.2.  The apxs script Red Hat ships is broken.  Look for this line:
      <programlisting>
<![CDATA[
my $CFG_LIBEXECDIR    = 'modules';         # substituted via APACI install
]]>
      </programlisting>
      If you see the above line, change it to this:
      <programlisting>
<![CDATA[
my $CFG_LIBEXECDIR    = '/usr/lib/apache'; # substituted via APACI install
]]>
      </programlisting>
       Last, if you reconfigure/reinstall Apache, add a <command>make clean</command> 
       to the process after <command>./configure</command> and before <command>make</command>.
     </para>
    </answer>
   </qandaentry>

   <qandaentry xml:id="faq.build.microtime">
    <question>
     <para>
      During <command>make</command>, I get errors in microtime, 
      and a lot of <literal>RUSAGE_</literal> stuff.
    </para>
    </question>
    <answer>
     <para>
      During the <command>make</command> portion of installation, 
      if you encounter problems that look similar to this:
      <programlisting>
<![CDATA[
microtime.c: In function `php_if_getrusage':
microtime.c:94: storage size of `usg' isn't known
microtime.c:97: `RUSAGE_SELF' undeclared (first use in this function)
microtime.c:97: (Each undeclared identifier is reported only once
microtime.c:97: for each function it appears in.)
microtime.c:103: `RUSAGE_CHILDREN' undeclared (first use in this function)
make[3]: *** [microtime.lo] Error 1
make[3]: Leaving directory `/home/master/php-4.0.1/ext/standard'
make[2]: *** [all-recursive] Error 1
make[2]: Leaving directory `/home/master/php-4.0.1/ext/standard'
make[1]: *** [all-recursive] Error 1
make[1]: Leaving directory `/home/master/php-4.0.1/ext'
make: *** [all-recursive] Error 1
]]>
      </programlisting>
     </para>
     <para>
      Your system is broken.  You need to fix your <filename>/usr/include</filename> files by
      installing a glibc-devel package that matches your glibc.  This has
      absolutely nothing to do with PHP.  To prove this to yourself, try this
      simple test:
     <programlisting>
<![CDATA[
$ cat >test.c <<X
#include <sys/resource.h>
X
$ gcc -E test.c >/dev/null
]]>
      </programlisting>
      If that spews out errors, you know your include files are messed up. 
     </para>
    </answer>
   </qandaentry>
   
   <qandaentry xml:id="faq.build.mysql.tempnam">
    <question>
     <para>
      When compiling PHP with MySQL, configure runs fine but during
      <literal>make</literal> I get an error similar to the following:
      <emphasis>ext/mysql/libmysql/my_tempnam.o(.text+0x46): In function 
      my_tempnam': /php4/ext/mysql/libmysql/my_tempnam.c:103: the 
      use of tempnam' is dangerous, better use mkstemp'</emphasis>, 
      what's wrong?
     </para>
    </question>
    <answer>
     <para>
      First, it's important to realize that this is a <literal>
      Warning</literal> and not a fatal error.  Because this is
      often the last output seen during <literal>make</literal>,
      it may seem like a fatal error but it's not.  Of course, if
      you set your compiler to die on Warnings, it will.  Also
      keep in mind that MySQL support is enabled by default.
     </para>
     <note>
      <para>
       As of PHP 4.3.2, you'll also see the following text after
       the build (make) completes:
      </para>
      <para>
       <screen>
        Build complete.
        (It is safe to ignore warnings about tempnam and tmpnam).
       </screen>
      </para>
     </note>
    </answer>
   </qandaentry>
   
   <qandaentry xml:id="faq.build.upgrade">
    <question>
     <para>
      I want to upgrade my PHP. Where can I find the <command>./configure</command>
      line that was used to build my current PHP installation?
     </para>
    </question>
    <answer>
     <para>
      Either you look at config.nice file, in the source tree of your current PHP
      installation or, if this is not available, you simply run a 
      <programlisting role="php">
<![CDATA[
       <?php phpinfo(); ?> 
]]>
      </programlisting>
      script. On top of the output the <command>./configure</command> line, that was used
      to build this PHP installation is shown.
     </para>
    </answer>
   </qandaentry>
   
   <qandaentry xml:id="faq.build.gdlibs">
    <question>
     <para>
      When building PHP with the GD library it either gives strange compile errors
      or segfaults on execution.
     </para>
    </question>
    <answer>
     <para>
      Make sure your GD library and PHP are linked against the same depending
      libraries (e.g. libpng).
     </para>
    </answer>
   </qandaentry>   
   
   <qandaentry xml:id="faq.installation.needgnu">
    <question>
     <para>
      When compiling PHP I seemingly get random errors, like it hangs.
      I'm using Solaris if that matters.
     </para>
    </question>
    <answer>
     <para>
      Using non-GNU utilities while compiling PHP may cause problems.  Be
      sure to use GNU tools in order to be certain that compiling PHP will
      work.  For example, on Solaris, using either the SunOS BSD-compatible
      or Solaris versions of <literal>sed</literal> will not work, but using
      the GNU or Sun POSIX (xpg4) versions of <literal>sed</literal> will
      work.  Links: <link xlink:href="&url.sed;">GNU sed</link>,
      <link xlink:href="&url.flex;">GNU flex</link>, and
      <link xlink:href="&url.bison;">GNU bison</link>.
     </para>
    </answer>
   </qandaentry>
  </qandaset>
 </chapter>

<!-- 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
-->