philip Sun Sep 5 19:23:35 2004 EDT
Added files:
/phpdoc/en/install pecl.xml
Modified files:
/phpdoc manual.xml.in
/phpdoc/RFC manual.xml.in
Log:
Document how to install PECL extensions.
http://cvs.php.net/diff.php/phpdoc/manual.xml.in?r1=1.190&r2=1.191&ty=u
Index: phpdoc/manual.xml.in
diff -u phpdoc/manual.xml.in:1.190 phpdoc/manual.xml.in:1.191
--- phpdoc/manual.xml.in:1.190 Thu Sep 2 18:28:30 2004
+++ phpdoc/manual.xml.in Sun Sep 5 19:23:34 2004
@@ -2,7 +2,7 @@
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
"@srcdir@/dtds/dbxml-4.1.2/docbookx.dtd" [
-<!-- $Revision: 1.190 $ -->
+<!-- $Revision: 1.191 $ -->
<!-- Add translated specific definitions and snippets -->
<!ENTITY % language-defs SYSTEM "@srcdir@/@LANGDIR@/language-defs.ent">
@@ -61,6 +61,7 @@
&install.unix.index;
&install.macos.index;
&install.windows.index;
+ &install.pecl;
&install.problems;
&install.ini;
</part>
http://cvs.php.net/diff.php/phpdoc/RFC/manual.xml.in?r1=1.15&r2=1.16&ty=u
Index: phpdoc/RFC/manual.xml.in
diff -u phpdoc/RFC/manual.xml.in:1.15 phpdoc/RFC/manual.xml.in:1.16
--- phpdoc/RFC/manual.xml.in:1.15 Thu Sep 2 09:54:47 2004
+++ phpdoc/RFC/manual.xml.in Sun Sep 5 19:23:35 2004
@@ -2,7 +2,7 @@
<!DOCTYPE book PUBLIC "-//PHPDocGroup//DTD DocBook XML V4.1.2-Based Variant PHPBook
V1.1//EN"
"@srcdir@/dtds/phpbook.dtd" [
-<!-- $Revision: 1.15 $ --> <!-- Last updated to comply to manual.xml.in 1.189 -->
+<!-- $Revision: 1.16 $ --> <!-- Last updated to comply to manual.xml.in 1.189 -->
<!-- Add translated specific definitions and snippets -->
<!ENTITY % language-defs SYSTEM "@srcdir@/@LANGDIR@/language-defs.ent">
@@ -63,6 +63,7 @@
&install.unix.index;
&install.macos.index;
&install.windows.index;
+ &install.pecl;
&install.problems;
&install.ini;
</part>
http://cvs.php.net/co.php/phpdoc/en/install/pecl.xml?r=1.1&p=1
Index: phpdoc/en/install/pecl.xml
+++ phpdoc/en/install/pecl.xml
<?xml version="1.0" encoding="iso-8859-1"?>
<!-- $Revision: 1.1 $ -->
<chapter id="install.pecl">
<title>Installation of PECL extensions</title>
<simplesect 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>
</simplesect>
<simplesect 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:[EMAIL PROTECTED]:/repository login
$ cvs -d:pserver:[EMAIL PROTECTED]:/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>
</simplesect>
<simplesect 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>
</simplesect>
<simplesect 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>
</simplesect>
<simplesect 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>
$ 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>
</simplesect>
<simplesect 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>
$ 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
$ ./configure --help
$ ./configure --with-extname --enable-someotherext --with-foobar
$ make
$ make install
</screen>
</para>
<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>
</simplesect>
</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
-->
