Part 1: XML Descriptors (Appendix)

Author

Sandro Zic

Intended Audience

This hands-on tutorial is intended for readers who have no knowledge about the ZZ/OSS Installer Client (ZIC) and want to get started with it. For example, to bundle their own PHP application with the ZIC.

Introduction

In a series of tutorials, you are guided through the process of making phpMyAdmin installable by ZIC. The example of bundling phpMyAdmin for ZIC will teach you how to prepare any other applications for ZIC.

Part 1: XML Descriptors: teaches you how to create the XML descriptors that define packages, applications, and distributions. This will get you to the point where the source files are correctly installed to the build tree of the application.

Why phpMyAdmin?

phpMyAdmin is a tool written in PHP intended to handle the administration of MySQL over the Web. Almost every PHP developer knows about it. It is not developed by ZZ/OSS, thus this tutorial demonstrates the power of ZIC to integrate third-party software into a unified installation process and software distribution system for PHP applications.

1. Install ZIC

Get the latest version of the ZIC and install it as described on the ZIC homepage.

2. Get phpMyAdmin

This tutorial is based on phpMyAdmin 2.5.6. Make sure that you download this specific version from the phpMyAdmin download page. Otherwise things might not work as shown here. Also, make sure that you get the .tar.bz2 or .zip archive, as various files are missing in the .tar.gz!

Then extract the downloaded file to any directory you wish: tar -xzvf phpMyAdmin_2.5.6.tar.bz2. Use WinZip on Windows.

We assume that the archive has been extracted to /home/ordnas/software/phpMyAdmin-2.5.6/.

3. Describe the Package

Next, we create a package containing the extracted files by defining the package.xml descriptor. This descriptor will contain all data necessary for the installer to display information about the package and to understand how to install it.

Go to /home/ordnas/software/phpMyAdmin-2.5.6/ and create a new file in this directory called package.xml. Open this file and add the following content. Take a close look at the XML which is quite self-explanatory. All information is taking from the phpMyAdmin Website or the downloaded files.

The naming convention for the package name net.sf.phpmyadmin.core conforms with the way how Java packages are named. The reasons and benefits will be explained later.

<?xml version="1.0" encoding="ISO-8859-1" ?>
<package version="1.0">
    <name>net.sf.phpmyadmin.core</name>
    <summary>phpMyAdmin Core Package</summary>
    <description>
    Core files equivalent to the phpMyAdmin download archive.
    </description>
    <homepage>http://www.phpmyadmin.net</homepage>
    <maintainers>
        <maintainer>
          <user>ordnas</user>
          <name>Sandro Zic</name>
          <email>sandro.zic at zzos.com</email>
          <role>distributor</role>
        </maintainer>
    </maintainers>
    <release>
        <version>2.5.6</version>
        <date>2004-03-01</date>
        <license url="http://www.gnu.org/licenses/gpl.txt" version="2">GPL</license>
        <state>stable</state>
        <notes>... add the release notes here ...</notes>
        <copyright>
            <holder year="2001-">Olivier M?ller, Lo?c Chapeaux, Marc Delisle</holder>
            <holder year="1998-2000">Tobias Ratschiller</holder>
        </copyright>
    </release>
</package>

Due to the fact that the package has been named net.sf.phpmyadmin.core in the package.xml, we need to rename the directory where the extracted source lie from /home/ordnas/software/phpMyAdmin-2.5.6/ to /home/ordnas/software/net.sf.phpmyadmin.core-2.5.6/

Furthermore, we need to delete the version information from the directory name, because the ZIC will otherwise not be able to deal with this source package. So we end up with the following source directory: /home/ordnas/software/net.sf.phpmyadmin.core/.

4. Package the Files

Now you have stored some general information about the package in the package.xml. It's time to add the file list to the package.xml. The filelist tells the installer which files actually belong to the package and how to treat them.

The ZIC comes with a tool that helps creating the filelist. Open ZIC in your browser and navigate to Develop Applications -> Packages -> Create package.xml. There you specify in the form field "Path to package files" the path to the phpMyAdmin sources with /home/ordnas/software/net.sf.phpmyadmin.core/. See this screenshot "Create package.xml" for details.

Click next and you will get the following XML filelist.

<filelist>
    <file role="php" baseinstalldir="" name="RELEASE-DATE-2.5.6"/>
    <file role="php" baseinstalldir="" name="TODO"/>
    ...
    <file role="php" baseinstalldir="" name="images/item_ltr.png"/>
    <file role="php" baseinstalldir="" name="images/button_primary.png"/>
</filelist>

Place this XML fragment right below the closing tag of the <copyright> element in the package.xml. At the end of this tutorial, the complete package.xml is listed in the Appendix.

You can download net.sf.phpmyadmin.core-2.5.6.tgz from the ZZ/OSS project Web site on Sourceforge.

5. Describe the Application

You might now ask yourself: "What, I have to describe the application - but I have already done that when describing the package?". That's wrong, because ZIC distinguishes between packages and applications: an application consists of one or several packages. Don't get confused just because the application named phpmyadmin currently consists of only one package called net.sf.phpmyadmin.core - we could potentially split it up in several packages, e.g. one package for the PHP files, another one for all the documentation files (like README, LICENSE, etc.) - or a package for the build files as explained in part 2 of the tutorial.

Describing an application is very similar to describing a package: you do this in an application.xml descriptor and most elements are the same as in the package.xml.

Create a file called application.xml somewhere in your filesystem and paste the following content:

<?xml version="1.0" encoding="ISO-8859-1" ?>
<application version="1.0">
    <name>phpmyadmin</name>
    <summary>phpMyAdmin</summary>
    <description>
    phpMyAdmin is a tool written in PHP intended to handle the administration of MySQL
    over the Web. Currently it can create and drop databases, create/drop/alter tables,
    delete/edit/add fields, execute any SQL statement, manage keys on fields, manage
    privileges,export data into various formats and is available in 47 languages.
    </description>
    <homepage>http://www.phpmyadmin.net</homepage>
    <maintainers>
        <maintainer>
          <user>ordnas</user>
          <name>Sandro Zic</name>
          <email>sandro.zic@zzoss.com</email>
          <role>distributor</role>
        </maintainer>
    </maintainers>
    <release>
        <version>2.5.6</version>
        <date>2004-03-01</date>
        <license url="http://www.gnu.org/licenses/gpl.txt" version="2">GPL</license>
        <state>stable</state>
        <notes>The first phpMyAdmin bundle for ZIC.</notes>
        <copyright>
            <holder year="2001-">Olivier M?ller, Lo?c Chapeaux, Marc Delisle</holder>
            <holder year="1998-2000">Tobias Ratschiller</holder>
        </copyright>
    </release>
</application>

Up to know, the application.xml only differs in the root element <application> from the package.xml. But again: don't assume that packages are the same as applications, only because the XML elements are very similar.

6. Add the Package to the Application

The package net.sf.phpmyadmin.core is supposed to be part of the application phpmyadmin. To indicate this relationship, we add the following XML fragment to the application.xml, right below the closing tag of the <copyright> element:

<packages>
    <package name="net.sf.phpmyadmin.core" version="2.5.6" use="required"/>
</packages>

Within the <packages> element, several packages can be specified within the child element <package>. Currently, we only specify the core package and we provide the version number with the package name. Additionally, we say that the package is required and cannot be deselected during the installation process. If you want to specify a package as optional, you simply omit the @use attribute.

Clearly, the <packages> element is what distinguishes the application.xml from the package.xml.

The complete application.xml is listed in the Appendix.

7. Describe the Distribution

The last XML descriptor we need to create is the distribution.xml. A distribution contains one or several applications. In the hierarchy of the ZIC descriptors, it is thus the top entity in the topology, followed by the application.xml and the package.xml.

For convenience reason, it is best to create the distribution.xml in the same directory as the application.xml. Paste the following XML into the newly created file. Notice that the distribution has been named "Sourceforge" because phpMyAdmin is hosted and developed there.

<?xml version="1.0" encoding="ISO-8859-1" ?>
<distribution version="1.0">
    <name>net.sf</name>
    <summary>Sourceforge</summary>
    <description>Distribution of software available at Sourceforge.</description>
    <homepage>http://www.sourceforge.net</homepage>
    <maintainers>
        <maintainer>
            <user>ordnas</user>
            <name>Sandro Zic</name>
            <email>sandro.zic at zzoss.com</email>
            <role>lead</role>
        </maintainer>
    </maintainers>
    <release>
        <version>1.0.0dev1</version>
        <date>2004-03-29</date>
        <state>dev</state>
        <copyright>
            <holder>See copyright notices of each application or package.</holder>
        </copyright>
        <notes>The very first Sourceforge distribution bundled by ZZ/OSS.</notes>
        <license url="http://www.opensource.org">OSI conform</license>
    </release>
</distribution>

8. Add the Application to ZIC

With all necessary XML descriptors set up, we can start devloping phpMyAdmin in ZIC.

Point your browser to ZIC, e.g. http://localhost/zic-x.x.x/, and navigate to Develop Applications -> Descriptors -> Add Application. Provide the paths to the distribution.xml and application.xml as shown in the screenshot of "Add Application".

Click next and phpMyAdmin will be displayed in the list of applications (see screenshot "Develop Applications"). Here you can view the distribution information by clicking on the distribution name (screenshot "Distribution Information") as well as the application information by clicking on the application name (screenshot "Application Information"). If you changed something in one of the XML descriptors, click on the "Descriptors" icon in the column "Actions" of the phpMyAdmin row in the list of applications to update the installer.

9. Install the Application with ZIC

In the "Actions" column, click the "Install" icon to trigger the installation process. The ZIC will ask you for the paths where to install the application to. Also, you can provide paths to the source directories of the application you develop. In our case, we fill in the path to the directory where the phpMyAdmin sources aka the net.sf.phpmyadmin.core package resides.

Keep in mind that here you provide the path to the parent directory of the packages, simply because the installer will scan this directory for any packages that reside there. Given that the phpmyadmin package path is /home/ordnas/software/net.sf.phpmyadmin.core/, we here specify the source path /home/ordnas/software/. Take a look at the screenshot "Installation Paths" which shows the correct path.

Click next and chose the installation profile: full, minimum, custom. To better control if the package(s) of your application have been registered properly, you are advised to chose "custom" as the installation profile (see screenshot "Installation Profile").

On the next GUI, the ZIC tells you that you have no plugins defined for your application. Don't worry about it, we will deal with it in the second part of this tutorial. For now, simply procede and you will get to the page where ZIC builds the package(s) from the sources you defined (screenshot "Packages Sources").

The succeeding package manager allows you to decide upon the installation actions of each package, like install, update, remove. If a package has been defined as @use="required" in the application.xml, then it can only be installed (screenshot "Application Packages"). Check out the package information by clicking on the package name (screenshot "Package Information"). The next page will ask you to confirm the package actions (screenshot "Confirm Actions").

One more step, and you you can view the installed phpMyAdmin as well as the installation log files (screenshot "Installation Done").

Further Reading

Available online is an introduction to ZIC in the International PHP Magazine.

If you want to learn more about the package.xml, read The package definition file package.xml in the PEAR manual.

Appendix

The complete descriptor XMLs are listed in the Appendix.