Midgard CMS
Open Source Content Management System
Midgard Project > Development > Midgard RFCs > PEAR Packaging MidCOM

mRFC 0021: PEAR Packaging MidCOM

  1. Current situation
  2. Proposed solution
    1. Dependency handling
    2. Availability of the PEAR installer
    3. Installing packages outside PEAR repository
    4. PEAR channels and the future
    5. Handling MgdSchemas
    6. Handling static files
  3. Generating package.xml files
    1. Extensions to the component manifest
      1. Example manifest
    2. Generating the package
  4. Tasks caused by this mRFC
    1. For component developers
    2. For the MidCOM maintainer
    3. For the Midgard maintainer

This document outlines how to package the Midgard Components Framework using the PEAR package format. This mRFC been submitted to the Midgard Community for discussion and approval under the Creative Commons Attribution-ShareAlike license.

Current situation

Currently MidCOM is released as a tar package containing the MidCOM framework and all components and libraries.

This method makes it difficult to upgrade individual components within the system, and for third party developers like the OpenPsa project to make their components easily installable.

Inclusion of all MidCOM components from the CVS repository into the packages also makes the system confusing as the component selection dialogue in AIS is cluttered with several unnecessary or out-of-date components.

Proposed solution

The proposed solution to this situation is to start using the PEAR 1.4 packaging format for both the MidCOM framework itself and individual components.

MidCOM framework would be shipped as one PEAR package, and each component or library as its own package.

Dependency handling

Using the PEAR package format would enable components to state their dependencies. This would mean that it would be easier for component authors to utilize PEAR packages and MidCOM purecode libraries as they could trust the package management system to look after getting the packages they depend on installed.

This means that MidCOM component developers can focus less on reinventing the wheel, and more on their actual functionality.

Availability of the PEAR installer

The PEAR package manager has been bundled with PHP releases since 4.3.0. As MidCOM requires on several modern PHP features, the PEAR dependency should be reasonable requirement.

However, as we will require some features that are only available in PEAR 1.4 and newer, the users will need to upgrade. This shouldn't be an unreasonable requirement as earlier PEAR releases have known security holes, and the upgrade is fairly straightforward:

# pear clear-cache
# pear upgrade PEAR

Installing packages outside PEAR repository

As MidCOM has a heavy dependency on the Midgard Framework, the MidCOM packages cannot be placed into the official PEAR repository.

However, the PEAR installer supports installing packages outside the repository by giving their full URL path. From PEAR manual:

pear install [options] ...
Installs one or more PEAR packages. You can specify a package to install in four ways:

"Package-1.0.tgz" : installs from a local file

"http://example.com/Package-1.0.tgz" : installs from anywhere on the net.

"package.xml" : installs the package described in package.xml. Useful for testing, or for wrapping a PEAR package in another package manager such as RPM.

"Package" : queries your configured server (pear.php.net) and downloads the newest package with the preferred quality/state (stable).

PEAR channels and the future

In addition to the official PEAR repository, PEAR 1.4 provides the option to set up third-party PEAR repositories, or Channels. This feature would enable Midgard Project to provide its own MidCOM PEAR channel making package installation and browsing even easier.

The proposal is to start by handling the packaging, and set up a channel at pear.midcom-project.org as soon as it becomes convenient.

Handling MgdSchemas

MgdSchema provides component developers with a way to extend the Midgard database with their own objects. This feature is utilized already in several MidCOM components. Now users have to manually include the MgdSchema files to their main MgdSchema configuration.

In this proposal we would create a custom MgdSchema role to be used with the PEAR packages that would automatically be applied to the config/mgdschema.xml file of each component. This role would do the following:

  • Add the file as an include statement into the /usr/share/midgard/schema/includes.xml file
  • Generate the necessary database tables using the midgard-schema utility

The latter will be implemented only for the Midgard 1.8 branch where the tool is available.

Handling static files

MidCOM includes a static directory for to be used images, javascript and CSS files needed in components. At the moment this directory is symlinked by the Datagard tool under the DocumentRoot of each site.

This however makes it difficult to version these files as they are maintained separately from the components that use them.

The proposal is to move the static directory of each component under the component itself and then utilize the PEAR Role_Web package to install them under a directory specified by:

# pear config-set web_dir /var/lib/midgard/midcom-static

Then this directory can be symlinked with datagard to each VirtualHost's directory.

Generating package.xml files

As MidCOM uses a highly standardized directory and file structure for its components, it is possible to generate the package.xml files automatically based on the directory hierarchies and the mRFC 0019 MidCOM component manifest files.

Extensions to the component manifest

The PEAR package format 1.0 would impose the following requirements for adding new fields to the component manifest. The additional fields are grouped under a package.xml toplevel key.

  • license: the license the package is available under
  • maintainers: array of package maintainers with username as the key and containing following information in array format:
    • name: full name of the maintainer
    • email: email address of the maintainer
    • role: project role of the maintainer
  • summary: short textual summary of the package (optional)
  • description: longer textual description of the package (optional)

In addition, a toplevel state key has to be added to the manifest telling the package status (beta, alpha, stable, etc.).

The toplevel version key must be converted to use a PHP version_compare() compatible version string, as otherwise PEAR will complain:

Warning: Channel validator warning: field "version" - A version number should have 3 decimals (x.y.z)

Example manifest

'name' => 'net.nemein.ping',    
'purecode' => true,  
'version' => '0.0.1',  
'state' => 'beta',  
'privileges' =>  Array(),  
'class_definitions' => Array(),  
'watches' => Array(  
    Array(  
        'classes' => Array(  
            'midcom_baseclasses_database_article',  
        ),  
        'operations' =>   
              MIDCOM_OPERATION_DBA_UPDATE  
            | MIDCOM_OPERATION_DBA_CREATE,  
    ),  
),  
'package.xml' => Array(  
    'license' => 'GPL',  
    'maintainers' => Array( 
        'bergie' => Array(  
            'name' => 'Henri Bergius',  
            'email' => 'henri.bergius@iki.fi',  
            'role' => 'lead',  
        ),  
    ),  
    'dependencies' => Array(  
        'midcom' => Array(  
            'version' => '2.5.0',  
            'rel'     => 'ge',  
        ),  
    ),  
),

Generating the package

Once the component manifest has been modified to include the required information, go to the component directory and generate the package.xml file:

$ php ../../../../support/pear-package.php net.nemein.ping > package.xml

Then validate the generated file for any missing information:

$ pear package-validate package.xml

And if there are no errors, generate the package:

$ pear package package.xml

After this the result should be a tarball. In this example, net_nemein_ping-0.0.1.tgz.

Tasks caused by this mRFC

This mRFC changes the distribution model of MidCOM completely, and so modifies the processes related to package development, and MidCOM and Midgard releases.

For component developers

Component developers simply have to make the modifications outlined in Extensions to the component manifest to their component's config/manifest.inc file and generate the component packages.

If they want to ship an MgdSchema file with their component, it must be named config/mgdschema.xml.

For the MidCOM maintainer

The maintainer of the MidCOM framework must now start to maintain the list of files in MidCOM distribution in the lib/midcom/config/package.xml file.

For the Midgard maintainer

MidCOM must be removed from the midgard-data package itself, and instead be installed using the pear install command.

If user doesn't have PEAR 1.4 or newer installed, it should be upgraded by datagard using

pear clear-cache
pear upgrade PEAR

For static file support, datagard should run the following:

mkdir /var/lib/midgard/midcom-static
pear channel-discover pearified.com
pear install pearified/Role_Web
pear config-set web_dir /var/lib/midgard/midcom-static

The directory /var/lib/midgard/midcom-static should be symlinked under all Midgard VirtualHost DocumentRoot directories as midcom-static.

Before the channel there must be a file in datagard listing absolute URLs of all MidCOM packages to be installed by default.

After the channel is running, datagard must simply do:

pear channel-discover pear.midcom-project.org
pear install midcom/midcom

Back

Development

Copyright © 1999-2008 The Midgard Project. Open Content
Designed by Nemein, hosted by Anykey