<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.7 $ -->

<chapter id="install.pecl">
 <title>Installation of PECL extensions</title>

 <sect1 id="install.pecl.intro">
  <title>Introduction to PECL Installations</title>
  <simpara>
   PHP extensions may be installed in a variety of ways. 
   <ulink url="&url.pecl;">PECL</ulink> is a repository of PHP extensions 
   living within the <ulink url="&url.php.pear;">PEAR</ulink> structure, and 
   the following demonstrates how to install these extensions.
  </simpara>
  <simpara>
   These instructions assume <literal>/your/phpsrcdir/</literal> is the path
   to the PHP source, and <literal>extname</literal> is the name of the
   PECL extension.  Adjust accordingly.  These instructions also assume a 
   familiarity with the <ulink url="&url.php.pear.cli;">pear command</ulink>.
  </simpara>
  <simpara>
   Shared extensions may be installed by including them inside of &php.ini;
   using the <link linkend="ini.extension">extension</link> PHP directive. See
   also the <link linkend="ini.extension-dir">extensions_dir</link>
   directive, and <function>dl</function>.  The installation methods described
   below do not automatically configure PHP to include these extensions, this 
   step must be done manually.
  </simpara>
  <simpara>
   When building PHP modules, it's important to have the appropriate versions 
   of the required tools (autoconf, automake, libtool, etc.) See the 
   <ulink url="&url.php.anoncvs;">Anonymous CVS Instructions</ulink> for 
   details on the required tools, and required versions.
  </simpara>
 </sect1>

 <sect1 id="install.pecl.downloads">
  <title>Downloading PECL extensions</title>
  <simpara>
   There are several options for downloading PECL extensions, such as:
  </simpara>
  <itemizedlist>
   <listitem>
    <simpara>
     <ulink url="&url.pecl;">&url.pecl;</ulink>
    </simpara>
    <simpara>
     Listed here is information like the ChangeLog, release information, 
     requirements, revisions, etc.  Although not every PECL extension has a
     webpage, most do.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <literal>pear download extname</literal>
    </simpara>
    <simpara>
     The <ulink url="&url.php.pear.cli;">pear command</ulink> may also be used 
     to download source files.  Specific revisions may also be specified.
    </simpara>
   </listitem>
   <listitem>
    <simpara>
     <acronym>CVS</acronym>
    </simpara>
    <simpara>
     All PECL files reside in <acronym>CVS</acronym>.  A web-based view may
     be seen at <ulink url="&url.php.cvs;pecl/">&url.php.cvs;pecl/</ulink>.  
     To download straight from <acronym>CVS</acronym>, consider the following 
     where <emphasis>phpfi</emphasis> is the password for user 
     <emphasis>cvsread</emphasis>:
    </simpara>
    <para>
     <screen>
$ cvs -d:pserver:cvsread@cvs.php.net:/repository login 
$ cvs -d:pserver:cvsread@cvs.php.net:/repository co pecl/extname
     </screen>
    </para>
   </listitem>
   <listitem>
    <simpara>
     Windows downloads
    </simpara>
    <simpara>
     Windows users may find compiled PECL binaries by downloading the
     <emphasis>Collection of PECL modules</emphasis> from the 
     <ulink url="&url.php.downloads;">PHP Downloads</ulink> page, and by
     retrieving a <ulink url="&url.php.snapshots;">PECL Snapshot</ulink>.  To
     compile PHP under Windows, read the 
     <ulink url="&url.php.win32.build.readme;">Win32 Build README</ulink>.
    </simpara>
   </listitem>
  </itemizedlist>
 </sect1>

 <sect1 id="install.pecl.windows">
  <title>PECL for Windows users</title>
  <simpara>
   Like with any other PHP extension <acronym>DLL</acronym>, to install move 
   the PECL extension DLLs into the <link linkend="ini.extension-dir">
   extension_dir</link> folder and include them within &php.ini;.  For 
   example:
  </simpara>
  <para>
   <screen>
extension=php_extname.dll
   </screen>
  </para>
  <simpara>
   After doing this, restart the web server.
  </simpara>
 </sect1>
 
 <sect1 id="install.pecl.pear">
  <title>Compiling shared PECL extensions with PEAR</title>
  <simpara>
   PEAR makes it easy to create shared PHP extensions. Using the 
   <ulink url="&url.php.pear.cli;">pear command</ulink>, do the following:
  </simpara>
  <para>
   <screen>
$ pear install extname
   </screen>
  </para>
  <simpara>
   That will download the source for <emphasis>extname</emphasis>, and 
   compile it on the system. This results in an 
   <filename>extname.so</filename> file that may then be included in &php.ini;
  </simpara>
  <simpara>
   In case the systems <emphasis>preferred_state</emphasis> is set higher than
   an available <emphasis>extname</emphasis> version, like it's set to stable 
   and the extension is still in beta, either alter the 
   <emphasis>preferred_state</emphasis> via <literal>pear config-set</literal> 
   or specify a specific version of the PECL extension. For example:
  </simpara>
  <para>
   <screen>
$ pear install extname-0.1.1
   </screen>
  </para>
  <simpara>
   Regardless, pear will copy this <filename>extname.so</filename> into the 
   <link linkend="ini.extension-dir">extensions directory</link>. Adjust  
   &php.ini; accordingly.
  </simpara>
 </sect1>

 <sect1 id="install.pecl.phpize">
  <title>Compiling shared PECL extensions with phpize</title>
  <simpara>
   If using pear is not an option, like for building shared PECL extensions
   from <acronym>CVS</acronym>, or for unreleased PECL packages, then creating 
   a shared extension may also be done by manually using the 
   <literal>phpize</literal> command. The pear command essentially does this 
   but it may also be done manually. Assuming the source file is named 
   <filename>extname.tgz</filename>, and that it was downloaded into the 
   current directory, consider the following:
  </simpara>
  <para>
   <screen>
<![CDATA[
$ pear download extname
$ gzip -d < extname.tgz | tar -xvf -
$ cd extname
$ phpize
$ ./configure && make
]]>
   </screen>
  </para>
  <simpara>
   Upon success, this will create <filename>extname.so</filename> and put it 
   into the <filename>modules/</filename> and/or <filename>.libs/</filename> 
   directory within the <filename>extname/</filename> source. Move this 
   shared extension (<filename>extname.so</filename>) into the PHP 
   <link linkend="ini.extension-dir">extensions directory</link>, and adjust
   &php.ini; accordingly.
  </simpara>
 </sect1>

 <sect1 id="install.pecl.static">
  <title>Compiling PECL extensions statically into PHP</title>
  <simpara>
   To statically include the extension within the PHP build, put the 
   extensions source into the <filename>ext/</filename> directory found in 
   the PHP source. For example:
  </simpara>
  <para>
   <screen>
<![CDATA[
$ cd /your/phpsrcdir/ext
$ pear download extname
$ gzip -d < extname.tgz | tar -xvf -
$ mv extname-x.x.x extname
$ rm package.xml
]]>
   </screen>
  </para>
  <simpara>
   This will result in the following directory:
  </simpara>
  <para>
   <screen>
    /your/phpsrcdir/ext/extname
   </screen>
  </para>
  <simpara>
   From here, build PHP as normal:
  </simpara>
  <para>
   <screen>
$ cd /your/phpsrcdir 
$ ./buildconf --force
$ ./configure --help
$ ./configure --with-extname --enable-someotherext --with-foobar
$ make
$ make install
   </screen>
  </para>
  <note>
   <simpara>
    To run the 'buildconf' script you need autoconf 2.13 and automake 1.4+
    (newer versions of autoconf may work, but are not supported).
   </simpara>
  </note>
  <simpara>
   Whether <literal>--enable-extname</literal> or <literal>--with-extname
   </literal> is used depends on the extension. Typically an extension that 
   does not require external libraries uses <literal>--enable</literal>. To be
   sure, run the following after buildconf:
  </simpara>
  <para>
   <screen>
$ ./configure --help | grep extname
   </screen>
  </para>
 </sect1>
</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
-->