wez Sun Sep 11 03:18:59 2005 EDT
Modified files:
/phpdoc/en/install pecl.xml
Log:
adjust pecl installation notes
http://cvs.php.net/diff.php/phpdoc/en/install/pecl.xml?r1=1.8&r2=1.9&ty=u
Index: phpdoc/en/install/pecl.xml
diff -u phpdoc/en/install/pecl.xml:1.8 phpdoc/en/install/pecl.xml:1.9
--- phpdoc/en/install/pecl.xml:1.8 Tue Jun 7 18:41:44 2005
+++ phpdoc/en/install/pecl.xml Sun Sep 11 03:18:57 2005
@@ -1,5 +1,5 @@
<?xml version="1.0" encoding="iso-8859-1"?>
-<!-- $Revision: 1.8 $ -->
+<!-- $Revision: 1.9 $ -->
<chapter id="install.pecl">
<title>Installation of PECL extensions</title>
@@ -7,27 +7,27 @@
<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.
+ <ulink url="&url.pecl;">PECL</ulink> is a repository of PHP extensions that
+ are made available to you via the <ulink url="&url.php.pear;">PEAR</ulink>
+ packaging system. This section of the manual is intended to demonstrate
+ how to obtain and install PECL 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
+ to the PHP source distribution, and that <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.
+ To be useful, a shared extension must be built, installed, and loaded. The
+ methods described below provide you with various instructions on how to
+ build and install the extensions, but they do not automatically load them.
+ Extensions can be loaded by adding an <link
+ linkend="ini.extension">extension</link> directive. To this &php.ini;
+ file, or through the use of the <function>dl</function> function.
</simpara>
<simpara>
- When building PHP modules, it's important to have the appropriate versions
+ When building PHP modules, it's important to have known-good 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.
@@ -45,9 +45,10 @@
<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.
+ The PECL web site contains information about the different extensions
+ that are offered by the PHP Development Team. The information available
+ here includes: ChangeLog, release notes, requirements and other similar
+ details.
</simpara>
</listitem>
<listitem>
@@ -55,8 +56,10 @@
<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.
+ PECL extensions that have releases listed on the PECL web site are
+ available for download and installation using the <ulink
+ url="&url.php.pear.cli;">pear command</ulink>.
+ Specific revisions may also be specified.
</simpara>
</listitem>
<listitem>
@@ -64,10 +67,10 @@
<acronym>CVS</acronym>
</simpara>
<simpara>
- All PECL files reside in <acronym>CVS</acronym>. A web-based view may
+ Most PECL extensions also 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
+ To download straight from <acronym>CVS</acronym>, the following
+ sequence of commands may be used. Note that <emphasis>phpfi</emphasis>
is the password for user
<emphasis>cvsread</emphasis>:
</simpara>
<para>
@@ -96,10 +99,10 @@
<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:
+ As with any other PHP extension <acronym>DLL</acronym>, installation is as
+ simple as copying the PECL extension DLLs into the <link
linkend="ini.extension-dir">
+ extension_dir</link> folder and loading them from &php.ini;. For
+ example, add the following line to your &php.ini;:
</simpara>
<para>
<screen>
@@ -123,67 +126,75 @@
</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;
+ This will download the source for <emphasis>extname</emphasis>,
+ compile, and install <filename>extname.so</filename> into your <link
+ linkend="ini.extension-dir">extension_dir</link>.
+ <filename>extname.so</filename> may then be loaded via &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:
+ By default, the <literal>pear</literal> command will not install
+ packages that are marked with the <literal>alpha</literal> or
+ <literal>beta</literal> state. If no <literal>stable</literal> packages
+ are available, you may install a <literal>beta</literal> package using the
+ following command:
</simpara>
<para>
<screen>
-$ pear install extname-0.1.1
+$ pear install extname-beta
+ </screen>
+ </para>
+ <para>
+ You may also install a specific version using this variant:
+ </para>
+ <para>
+ <screen>
+$ pear install extname-0.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:
+ Sometimes, using the <literal>pear</literal> installer is not an option.
+ This could be because you're behind a firewall, or it could be because the
+ extension you want to install is not available as a PEAR compatible
+ package, such as unreleased extensions from CVS. If you need to build such
+ an extension, you can use the lower-level build tools to perform the build
+ manually.
+ </simpara>
+ <simpara>
+ The <literal>phpize</literal> command is used to prepare the build
+ environment for a PHP extension. In the following sample, the sources for
+ an extension are in a directory named <filename>extname</filename>:
</simpara>
<para>
<screen>
<![CDATA[
-$ pear download extname
-$ gzip -d < extname.tgz | tar -xvf -
$ cd extname
$ phpize
-$ ./configure && make
+$ ./configure
+$ make
+# make install
]]>
</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.
+ A successful install will have created <filename>extname.so</filename> and
put it
+ into the PHP
+ <link linkend="ini.extension-dir">extensions directory</link>. You'll need
+ to and adjust &php.ini; and add an <literal>extension=extname.so</literal>
+ line before you can use the extension.
</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:
+ You might find that you need to build a PECL extension statically into your
+ PHP binary. To do this, you'll need to place the extension source under
+ the <filename>php-src/ext/</filename> directory and tell the PHP build
+ system to regenerate its configure script.
</simpara>
<para>
<screen>
@@ -192,7 +203,6 @@
$ pear download extname
$ gzip -d < extname.tgz | tar -xvf -
$ mv extname-x.x.x extname
-$ rm package.xml
]]>
</screen>
</para>
@@ -205,7 +215,7 @@
</screen>
</para>
<simpara>
- From here, build PHP as normal:
+ From here, force PHP to rebuild the configure script, and then build PHP as
normal:
</simpara>
<para>
<screen>
@@ -226,8 +236,8 @@
</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
+ </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>
