electronic.alchemy :: Pike Module Archive (PMAR) creation
electronic.alchemy
where the past meets the future
pike > PMAR creation

Pike Module Archive (PMAR) creation

Created by hww3. Last updated by hww3, 9 years ago. Version #1.

This document describes the structure and recommended procedures for creating prepackaged module installation archives. These files, called PMARs, can be used with the pmar_install tool (pike -x pmar_install) to install modules without having to run the build process. This tool is primarily intended for distribution of pike-only modules, or for the distribution of modules packaged for systems which typically do not have build environments (such as Microsoft Windows).

Structure of a PMAR

A PMAR file is simply a TAR file that contains files in a particular directory structure. In its simplest forms, it consists of the following:

myModule/
         METADATA.TXT
         MODULE/

That is, you should create a directory (its name is actually not significant), and within that directory, create a file called METADATA.TXT and a directory called MODULE.

The contents of your module should be copied into the MODULE directory. That is, if you have a called Public.Foo, you'd copy the whole Public.pmod/Foo.pmod hierarchy into the MODULE directory. Note that you need to include the whole hierarchy that would be created for your module, so you'd include Public.pmod. If you are working with a standard external pike module build project, the easiest way to get the files in a ready-to-go manner is to run "pike -x module verify", and then copy the contents of plib/modules into the MODULES directory.

Hint: You can bundle multiple modules in one PMAR File by including them in the MODULES directory. For example, we can include both Public.Foo and Public.Tools.Bar, making things simpler. Because we determine module installation status by directly querying the module for pertinent information (see the Pike Module Developer's Guide for more information), we can combine modules with impunity. Note that when doing this, we should provide a comma separated list of modules contained in a PMAR as the value for MODULE in METADATA.TXT.

The file METADATA.TXT contains information that describes the module included in the PMAR file. It consists of a number of lines that contain key-value mappings, in the format:

KEY=value

There are 3 keys that are required for your module package:

For our example module, which is pike-only, we'd create a metadata file that looked like this:

MODULE=Public.Foo
VERSION=1.2
PLATFORM=any/any

Additional key value pairs may be included for record keeping purposes and will be silently ignored.

Optional components

At the moment, there are a few optional components of a PMAR file which may be useful for more exotic installations. These optional components are a set of pike classes that can be run to perform pre- and post-install operations.

To use these features, create a SCRIPTS directory in your package, and place files called "preinstall.pike" and/or "postinstall.pike". These scripts will be run, if present, at the appropriate times.

The constructor of the script will receive the installer object (pmar_install.pike), and a System.Filesystem object of the PMAR file. They should also contain a method called run(), which returns a boolean that indicates success or failure. If a pre/post install activity fails, the installation will halt.

You can use the objects passed to the constructor to get system install directories, and to access files within your package. Note that most packages will not need to make use of this functionality.

You can find a sample make rule that automates the creation of PMARs (and creates module repository releases of your module, as well) in the SampleModule module in Bill Welliver's source repository for this module.

Not categorized | RSS Feed | BackLinks

comments powered by Disqus