PackagingDrafts/PHP

From FedoraProject

< PackagingDrafts(Difference between revisions)
Jump to: navigation, search
(Packages with Channels)
(Paste the actual approved Guidelines)
Line 7: Line 7:
 
This page describes items that need to be changed in the [http://fedoraproject.org/wiki/Packaging/PHP PHP Guidelines]  or other items that need to be reviewed or ratified by the [http://fedoraproject.org/wiki/Packaging/Committee Fedora Packaging Comittee]  and [http://fedoraproject.org/wiki/Development/SteeringCommittee FESCo] .
 
This page describes items that need to be changed in the [http://fedoraproject.org/wiki/Packaging/PHP PHP Guidelines]  or other items that need to be reviewed or ratified by the [http://fedoraproject.org/wiki/Packaging/Committee Fedora Packaging Comittee]  and [http://fedoraproject.org/wiki/Development/SteeringCommittee FESCo] .
  
== PHP Guidelines Changes ==
+
= Guidelines for packaging PHP addon modules =
  
==== Different kinds of packages ====
 
  
To be add
 
* CHANNEL : a package which register a channel which provides extensions from another repository
 
* Other package providing php extension not handled by pear/pecl mechanisms
 
  
3 channels are defined on installation of php-pear
+
== Different kinds of packages ==
* <code>pear.php.net</code> (alias pear) : the default channel for PHP Extension and Application Repository
+
* <code>pecl.php.net</code> (alias pecl) : the default channel for PHP Extension Community Library
+
* <code>__uri</code> : Pseudo-channel for static packages
+
  
Other channels must be installed at RPM build time and at at RPM installation time.
+
There are basically two different kinds of php modules, which are packaged for Fedora Extras:
  
'''FPC notes''' : we already have 4 extras channels in repository (phing, phpdb, symfony and phpunit). A new one (ezc) is on the road. This Guidelines update proposal "try" to avoid change for already approved packages.
+
* [http://pecl.php.net PECL]  (PHP Extention Community Library), which are PHP modules usually written in C, which are dynamically loaded by the PHP interpreter on startup.
 +
* [http://pear.php.net PEAR]  (PHP Extension and Application Repository), which are reusable components written in PHP, usually classes, which can be used in your own PHP applications and scripts by using e.g. the include() directive.
  
==== Naming scheme ====
+
While upstream used the same package and distribution format for both, creating RPMs has to take some differences into account.
  
* PECL packages from standard pecl channel should be named php-pecl-PECLPackageName-%{version}-%{release}.%{arch}.rpm.
+
{{Anchor|NamingScheme}}
* PEAR packages from standard pear channel should be named php-pear-PEARPackageName-%{version}-%{release}.noarch.rpm.
+
== Naming scheme ==
* CHANNEL packages should be named php-channel-ChannelAlias-%{version}-%{release}.noarch.rpm
+
* Packages from another channel  should be named php-ChannelAlias-PackageName-%{version}-%{release}.noarch.rpm.
+
  
 +
* PECL packages should be named ''php-pecl-PECLPackageName-%{version}-%{release}.%{arch}.rpm''.
 +
* PEAR packages should be named ''php-pear-PEARPackageName-%{version}-%{release}.noarch.rpm''.
 +
* Other packages should be named ''php-PackageName-%{version}-%{release}.%{arch}.rpm''; %{arch} can be "noarch" where appropriate.
  
'''FPC notes''' : PECL/PEAR package from standard channel also follow naming scheme for packages from another channel :)
+
Please make sure that the PEAR package is correctly being built for noarch.
  
Packages which doesn't follow this Guidelines update:
+
The PECLPackageName and the PEARPackageName should be consistent with the upstream naming scheme.
* php-pear-creole => php-phpdb-creole
+
The Crack PHP Extension would thus be named ''php-pecl-crack'' with the resulting packages being ''php-pecl-crack-0.4-1.i386.rpm'' and ''php-pecl-crack-0.4-1.src.rpm''.
* php-pear-propel_runtime => php-phpdb-propel-runtime
+
* php-pear-propel_generator => php-phpdb-propel-generator
+
* php-pear-phing => php-phing-phing
+
* php-pear-PHPUnit => php-phpunit-PHPUnit
+
* php-pear-pake => php-symfony-pake
+
  
We could probably accept an exception for this already accepted packages
+
Note that web applications that happen to be written in PHP do not belong under the php-* namespace.
  
=== CHANNEL Packages  ===
+
== File Placement ==
  
A CHANNEL package ''''MUST''' have :
+
Non-PEAR PHP extensions should put their Class files in /usr/share/php.
<pre>
+
 
Requires: php-pear(PEAR)
+
== Requires and Provides ==
Requires(post): %{__pear}
+
Requires(postun): %{__pear}
+
Provides: php-channel(channelname)
+
</pre>
+
  
=== PEAR Packages from non standard repository ===
+
=== PEAR Packages ===
  
 
A PEAR package '''MUST''' have:
 
A PEAR package '''MUST''' have:
  
 
<pre>
 
<pre>
BuildRequires: php-channel(channelname)
 
 
BuildRequires: php-pear(PEAR)
 
BuildRequires: php-pear(PEAR)
 
Requires: php-pear(PEAR)
 
Requires: php-pear(PEAR)
 
Requires(post): %{__pear}
 
Requires(post): %{__pear}
 
Requires(postun): %{__pear}
 
Requires(postun): %{__pear}
Requires: php-channel(channelname)
+
Provides:    php-pear(foo) = %{version}
Provides:    php-pear(channelname/foo) = %{version}
+
 
</pre>
 
</pre>
  
 +
=== PECL Packages ===
  
== Macros and scriptlets ==
+
A PECL package '''MUST''' have:
 
+
=== CHANNEL package ===
+
 
+
 
+
For non default channel extension, pear command requires the channel, so %postun scriplet must specify it
+
  
 
<pre>
 
<pre>
%post
+
BuildRequires: php-devel, php-pear
if [ $1 -eq  1 ] ; then
+
Requires(post): %{__pecl}
  %{__pear} channel-add %{pear_xmldir}/%{name}.xml > /dev/null || :
+
Requires(postun): %{__pecl}
else
+
  %{__pear} channel-update %{pear_xmldir}/%{name}.xml > /dev/null ||:
+
fi
+
  
 +
%if %{?php_zend_api}0
 +
Requires:    php(zend-abi) = %{php_zend_api}
 +
Requires:    php(api) = %{php_core_api}
 +
%else
 +
Requires:    php-api = %{php_apiver}
 +
%endif
  
%postun
+
Provides:    php-pecl(foo) = %{version}
if [ $1 -eq 0 ] ; then
+
  %{__pear} channel-delete %{channelname} > /dev/null || :
+
fi
+
 
</pre>
 
</pre>
  
'''FPC notes''' : I recommend to use %{name} for XML file rather than channel or extension name to avoid possible conflicts
+
=== Other Packages ===
  
 +
PHP addons which are neither PEAR nor PECL should require what makes sense (either a base PHP version or a php-api as necessary).
 +
 +
== Macros and scriptlets ==
  
 
=== PEAR Modules ===
 
=== PEAR Modules ===
  
...
+
The php-pear package in Fedora Core 5 and above (version 1:1.4.9-1.2) provides several useful macros:
 +
* %{pear_phpdir}
 +
* %{pear_docdir}
 +
* %{pear_testdir}
 +
* %{pear_datadir}
 +
* %{pear_xmldir}
  
 
These defintions for the .spec should be of interest:
 
These defintions for the .spec should be of interest:
Line 102: Line 90:
 
BuildRequires:    php-pear >= 1:1.4.9-1.2
 
BuildRequires:    php-pear >= 1:1.4.9-1.2
 
Provides:        php-pear(PackageName) = %{version}
 
Provides:        php-pear(PackageName) = %{version}
Requires:        php-common >= 4.3, php-pear(PEAR)
+
Requires:        php >= 4.3, php-pear(PEAR)
 
Requires(post):  %{_bindir}/pear
 
Requires(post):  %{_bindir}/pear
 
Requires(postun): %{_bindir}/pear
 
Requires(postun): %{_bindir}/pear
 
</pre>
 
</pre>
  
'''FPC notes''' : i change php to php-common (to avoid httpd dependency)
+
And here are some recommended scriptlets for properly registering and unregistering the module:
 
+
...
+
 
+
And here are some recommended scriptlets for properly registering the module:
+
 
<pre>
 
<pre>
 
%post
 
%post
%{_bindir}/pear install --nodeps --soft --force --register-only %{pear_xmldir}/%{name}.xml >/dev/null ||:
+
%{_bindir}/pear install --nodeps --soft --force --register-only %{pear_xmldir}/Foo_Bar.xml >/dev/null ||:
</pre>
+
  
And here are some recommended scriptlets for properly unregistering the module, from standard channel:
 
<pre>
 
 
%postun
 
%postun
 
if [ "$1" -eq "0" ] ; then
 
if [ "$1" -eq "0" ] ; then
Line 125: Line 106:
 
</pre>
 
</pre>
  
From non standard channel;
+
=== PECL Modules ===
 +
 
 +
The php-pear package in Fedora Core 5 and above (version 1:1.4.9-1.2) provides several useful macros:
 +
* %{pecl_phpdir}
 +
* %{pecl_docdir}
 +
* %{pecl_testdir}
 +
* %{pecl_datadir}
 +
* %{pecl_xmldir}
 +
 
 +
You may need to define a few additional macros to extract some information from PHP. It is recommended that you use the following:
 
<pre>
 
<pre>
 +
%global php_apiver  %((echo 0; php -i 2>/dev/null | sed -n 's/^PHP API => //p') | tail -1)
 +
%{!?__pecl:    %{expand: %%global __pecl    %{_bindir}/pecl}}
 +
%{!?php_extdir: %{expand: %%global php_extdir %(php-config --extension-dir)}}
 +
</pre>
 +
 +
And here are some recommended scriptlets for properly registering and unregistering the module:
 +
<pre>
 +
%if 0%{?pecl_install:1}
 +
%post
 +
%{pecl_install} %{pecl_xmldir}/%{name}.xml >/dev/null || :
 +
%endif
 +
 +
 +
%if 0%{?pecl_uninstall:1}
 
%postun
 
%postun
if [ "$1" -eq "0" ] ; then
+
if [ $1 -eq 0 ] ; then
%{_bindir}/pear uninstall --nodeps --ignore-errors --register-only Foo_channel/Foo_Bar >/dev/null ||:
+
%{pecl_uninstall} %{pecl_name} >/dev/null || :
 
fi
 
fi
 +
%endif
 
</pre>
 
</pre>
  
 +
=== Other Modules ===
  
'''FPC notes''' : I also recommend to use %{name} for XML file rather than extension name to avoid possible conflicts (we can only use this for non standard channel ank keep using extension name for standard one and for existing package)
+
If your module includes compiled code, you may need to define some macros to extract some information from PHP.  It is recommended that you user the following:
 +
<pre>
 +
%global php_apiver  %((echo 0; php -i 2>/dev/null | sed -n 's/^PHP API => //p') | tail -1)
 +
%global php_extdir  %(php-config --extension-dir 2>/dev/null || echo "undefined")
 +
%global php_version %(php-config --version 2>/dev/null || echo 0)
 +
</pre>
 +
 
 +
== Additional Hints for Packagers ==
 +
 
 +
=== PEAR & PECL Packages ===
 +
 
 +
The source archive contains a package.xml outside any directory, so you have to use use
 +
<pre>
 +
%setup -q -c
 +
</pre>
 +
in your %prep section to avoid writing files to the build root.
 +
 
 +
=== PEAR Packages ===
 +
 
 +
To create your initial specfile, you can use the default template provided by the rpmdevtools package:
 +
 
 +
<pre>
 +
fedora-newrpmspec -t php-pear php-pear-Foo
 +
</pre>
 +
 
 +
Or you can generate one; make sure you have the php-pear-PEAR-Command-Packaging package installed:
 +
 
 +
<pre>
 +
pear make-rpm-spec Foo.tgz
 +
</pre>
  
=== Packages with Optional Requires ===
+
= Packages with Optional Requires =
  
 
TODO: Some PEAR packages such as [http://pear.php.net/package/Auth Auth]  have many other PEAR packages that are optional Requires.  We need to discuss how to handle splitting up large packages such as this.
 
TODO: Some PEAR packages such as [http://pear.php.net/package/Auth Auth]  have many other PEAR packages that are optional Requires.  We need to discuss how to handle splitting up large packages such as this.

Revision as of 17:52, 16 February 2009

[[TableOfContents(3)]

Contents

Proposed Changes to PHP Guidelines

Synopsis

This page describes items that need to be changed in the PHP Guidelines or other items that need to be reviewed or ratified by the Fedora Packaging Comittee and FESCo .

Guidelines for packaging PHP addon modules

Different kinds of packages

There are basically two different kinds of php modules, which are packaged for Fedora Extras:

  • PECL (PHP Extention Community Library), which are PHP modules usually written in C, which are dynamically loaded by the PHP interpreter on startup.
  • PEAR (PHP Extension and Application Repository), which are reusable components written in PHP, usually classes, which can be used in your own PHP applications and scripts by using e.g. the include() directive.

While upstream used the same package and distribution format for both, creating RPMs has to take some differences into account.

Naming scheme

  • PECL packages should be named php-pecl-PECLPackageName-%{version}-%{release}.%{arch}.rpm.
  • PEAR packages should be named php-pear-PEARPackageName-%{version}-%{release}.noarch.rpm.
  • Other packages should be named php-PackageName-%{version}-%{release}.%{arch}.rpm; %{arch} can be "noarch" where appropriate.

Please make sure that the PEAR package is correctly being built for noarch.

The PECLPackageName and the PEARPackageName should be consistent with the upstream naming scheme. The Crack PHP Extension would thus be named php-pecl-crack with the resulting packages being php-pecl-crack-0.4-1.i386.rpm and php-pecl-crack-0.4-1.src.rpm.

Note that web applications that happen to be written in PHP do not belong under the php-* namespace.

File Placement

Non-PEAR PHP extensions should put their Class files in /usr/share/php.

Requires and Provides

PEAR Packages

A PEAR package MUST have:

BuildRequires: php-pear(PEAR)
Requires: php-pear(PEAR)
Requires(post): %{__pear}
Requires(postun): %{__pear}
Provides:     php-pear(foo) = %{version}

PECL Packages

A PECL package MUST have:

BuildRequires: php-devel, php-pear
Requires(post): %{__pecl}
Requires(postun): %{__pecl}

%if %{?php_zend_api}0
Requires:     php(zend-abi) = %{php_zend_api}
Requires:     php(api) = %{php_core_api}
%else
Requires:     php-api = %{php_apiver}
%endif

Provides:     php-pecl(foo) = %{version}

Other Packages

PHP addons which are neither PEAR nor PECL should require what makes sense (either a base PHP version or a php-api as necessary).

Macros and scriptlets

PEAR Modules

The php-pear package in Fedora Core 5 and above (version 1:1.4.9-1.2) provides several useful macros:

  •  %{pear_phpdir}
  •  %{pear_docdir}
  •  %{pear_testdir}
  •  %{pear_datadir}
  •  %{pear_xmldir}

These defintions for the .spec should be of interest:

BuildRequires:    php-pear >= 1:1.4.9-1.2
Provides:         php-pear(PackageName) = %{version}
Requires:         php >= 4.3, php-pear(PEAR)
Requires(post):   %{_bindir}/pear
Requires(postun): %{_bindir}/pear

And here are some recommended scriptlets for properly registering and unregistering the module:

%post
%{_bindir}/pear install --nodeps --soft --force --register-only %{pear_xmldir}/Foo_Bar.xml >/dev/null ||:

%postun
if [ "$1" -eq "0" ] ; then
%{_bindir}/pear uninstall --nodeps --ignore-errors --register-only Foo_Bar >/dev/null ||:
fi

PECL Modules

The php-pear package in Fedora Core 5 and above (version 1:1.4.9-1.2) provides several useful macros:

  •  %{pecl_phpdir}
  •  %{pecl_docdir}
  •  %{pecl_testdir}
  •  %{pecl_datadir}
  •  %{pecl_xmldir}

You may need to define a few additional macros to extract some information from PHP. It is recommended that you use the following:

%global php_apiver  %((echo 0; php -i 2>/dev/null | sed -n 's/^PHP API => //p') | tail -1)
%{!?__pecl:     %{expand: %%global __pecl     %{_bindir}/pecl}}
%{!?php_extdir: %{expand: %%global php_extdir %(php-config --extension-dir)}}

And here are some recommended scriptlets for properly registering and unregistering the module:

%if 0%{?pecl_install:1}
%post
%{pecl_install} %{pecl_xmldir}/%{name}.xml >/dev/null || :
%endif


%if 0%{?pecl_uninstall:1}
%postun
if [ $1 -eq 0 ]  ; then
%{pecl_uninstall} %{pecl_name} >/dev/null || :
fi
%endif

Other Modules

If your module includes compiled code, you may need to define some macros to extract some information from PHP. It is recommended that you user the following:

%global php_apiver  %((echo 0; php -i 2>/dev/null | sed -n 's/^PHP API => //p') | tail -1)
%global php_extdir  %(php-config --extension-dir 2>/dev/null || echo "undefined")
%global php_version %(php-config --version 2>/dev/null || echo 0)

Additional Hints for Packagers

PEAR & PECL Packages

The source archive contains a package.xml outside any directory, so you have to use use

%setup -q -c

in your %prep section to avoid writing files to the build root.

PEAR Packages

To create your initial specfile, you can use the default template provided by the rpmdevtools package:

fedora-newrpmspec -t php-pear php-pear-Foo

Or you can generate one; make sure you have the php-pear-PEAR-Command-Packaging package installed:

pear make-rpm-spec Foo.tgz

Packages with Optional Requires

TODO: Some PEAR packages such as Auth have many other PEAR packages that are optional Requires. We need to discuss how to handle splitting up large packages such as this.

Other Items

No additional items required.