Section 12.13. Packaging

12.13. Packaging

In the "Building Packages" section earlier, we saw an example of using pear package to build a release tarball. In this section, we go deeper into that process. The component of the PEAR Installer that creates packages is called the PEAR packager. When we refer to the PEAR packager in this section, know that it is part of the installer.

12.13.1. Source Analysis

One of the things that the PEAR packager does is analyze PHP code to determine what dependencies it has, and what classes and functions it defines. It does this both to ease dependency handling and to catch coding standard-related problems. For example, if a package defines a class with a name that is outside the package's namespace, the packager issues an error.

12.13.2. MD5 Checksum Generation

To give the PEAR Installer a way to check that files in a package tarball are intact, the PEAR packager calculates an MD5 checksum for each file. This checksum is embedded in the tarball as an attribute to the <file> element, for example:

 <file role="php" md5sum="c2aa3b18afa22286e946aeed60b7233c" name="HelloWorld.php"/> 

This is done automatically during packaging so the package.xml file does not have to be updated every time a file is updated.

12.13.3. Package.xml Update

The package.xml file that is embedded in the package tarball is generated during packaging. The results of the source analysis and MD5 checksum steps are embedded in the new package.xml file. To illustrate this, the generated package.xml for our HelloWorld package looks like this:

[View full width]
 <?xml version="1.0" encoding="ISO-8859-1" ?> <package version="1.0">   <name>HelloWorld</name>   <summary>Simple Hello World Package</summary>   <description>This package contains a class that simply prints &quot;Hello, World!&quot;.< /description>   <maintainers>     <maintainer>       <user>ssb</user>       <name>Stig S. Bakken</name>       <email>[e-mail]</email>       <role>lead</role>     </maintainer>   </maintainers>   <release>     <version>1.0</version>     <date>2003-02-24</date>     <license>PHP License</license>     <state>stable</state>     <notes>First production release.</notes>     <provides type="class" name="HelloWorld" />     <filelist>     <file role="php" md5sum="c2aa3b18afa22286e946aeed60b7233c" name="HelloWorld.php"/>     </filelist>   </release> </package> 

The lines that have changed are emphasized in bold. As you can see, the source analysis found our HelloWorld class, and an MD5 checksum has been created for HelloWorld.php.

12.13.4. Tarball Creation

Finally, the tarball is created. If your CLI version of PHP has zlib support enabled, it will be compressed; if not, it will be a plain .tar file. PEAR works without zlib enabled, but it adds some hassle for you during package creation, and downloads takes much longer.

The file layout of the generated tarball is like this:

 package.xml HelloWorld-1.0/HelloWorld.php HelloWorld-1.0/hello HelloWorld-1.0/HelloWorld.phpt 

The file layout inside the package is based on that in the source tree, because that structure is used in the package.xml file.