EPM Specification

The EPM Specification

The EPrints Package/Plug-in Manager (EPM) is designed to install EPM (EPrints Modules) in the EPM format.

EPM is a simple format consisting of a directory structure which is dropped into the ARCHIVE_ID directory.

In order to make an EPM you also require a specification file and an icon to represent the EPM in the EPM repository.

For more details on the Package Manager see EPrints_Package_Manager.

The EPM Spec File

The EPM Spec file contains a series of ":" separated keypairs, each on it's own line. Unless otherwise specified, ALL the fields detailed here are required. If a package wishes to add it's own configuration variables these should be added to the package's own configuration file and not the EPM spec.

The spec file should be called package_name ("package") in the spec file, e.g. (test_package.spec).

Example Spec file:

 package: test_package
 version: 0.0.1
 title: Test Package
 description: This is a simple test screen plugin
 creator: Dave Tarrant <davetaz@foo.bar.org>
 creator: Creator 2 <c2@foo.bar.org>
 configuration_file: Admin::TestScreen
 icon: icon.png
 license: GPLv2
 category: example
 category: input_output
 optional_key: key value
 

package

• A globally unique package identifier, used for management of the package versions, upgrades and local over rides.
• The main EPM repository will be files.eprints.org and this can be searched to find if your package_name exists. Alternatively files should tell you when you try and submit the package.

package_url (optional)

• An official url for the package.

version

• A semantic version complient version number (major release . minor release . bugfix release)
• See http://semver.org/ for more details

title

• The title/name of the package.
• A pretty string.

description

• Description of the package.
• A pretty string.

creator

• A creator listed as follows:

 Dave Tarrant <foo@bar.com>

• More than one creator can be specified by adding additional creator lines.

icon

• The icon file which should be within the root directory of the package

category

• The category of the plug-in, again multiple categories can be specified.
• More can be found on these at http://bazaar.eprints.org (or via the store into which the package is being submitted).

configuration_file (not required)

• A Screen or Config File in cfg/cfg.d.

If a cfg/cfg.d config file is listed (e.g. cfg/cfg.d/myscreen.pl), then the EPM Manager will re-direct the user to the built in editor for editing this config file. If a screen is specified (as per the example above) then the user will be re-directed to this screen when they press the configure button against the installed package.

The EPM Package Structure

The following shows the package structure for the package "test_package".

 - test_package.spec
 - icon.png
 - cfg/cfg.d/test_package.cfg
 - cfg/plugins/EPrints/Plugin/Screen/Admin/TestScreen.pm

In this only test_package.spec and icon.png are required, all the rest of the files are installed if possible.

Bundling an EPM

• Compress the directory structure shown above into a zip file
• Change the extenstion on this zip file to .epm

Submitting an EPM

This can either be done via the web interface of your chosen EPM repository, or via the submit to EPM repository button which can be accessed on the "Local Packages" tab of the EPrints Bazaar admin GUI.

If you have filled in all the metadata then there is no need to fill this in again via the web interface as it will be extracted from the spec file automatically.

TODO

• Finalise the specification for an EPM repository.
• Get sword working for submission of EPMs
• Write an upload handler for EPM files which extracts the metadata and icon. If invalid or data missing this should throw an error back to the client, both in the interface and via sword.
• Link EPData XML Representation at an appropriate place; it appears to be what EPM spec is based on