Difference between revisions of "EPM Specification"

From EPrints Documentation
Jump to: navigation, search
m (iiiits typo time!)
 
(5 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 +
[[Category:Contribute]]
 +
[[Category:Plugins]]
 +
[[Category:Bazaar Package]]
 +
[[Category:EPrints Bazaar]]
 +
 
=The EPM Specification=
 
=The EPM Specification=
  
Line 17: Line 22:
 
Example Spec file:
 
Example Spec file:
 
   package: test_package
 
   package: test_package
   version: 0.4
+
   version: 0.0.1
 
   title: Test Package
 
   title: Test Package
 
   description: This is a simple test screen plugin
 
   description: This is a simple test screen plugin
   creator: Dave Tarrant <davetaz@foo.bar.org>, Creator 2 <c2@foo.bar.org>
+
   creator: Dave Tarrant <davetaz@foo.bar.org>
 +
  creator: Creator 2 <c2@foo.bar.org>
 
   configuration_file: Admin::TestScreen
 
   configuration_file: Admin::TestScreen
 
   icon: icon.png
 
   icon: icon.png
 
   license: GPLv2
 
   license: GPLv2
 +
  category: example
 +
  category: input_output
 
   optional_key: key value
 
   optional_key: key value
 +
 
  
 
===package===
 
===package===
Line 34: Line 43:
  
 
===version===
 
===version===
* A decimal only separated package version!
+
* A semantic version complient version number (major release . minor release . bugfix release)
* One recommendataion is to use the revision number of the tag/trunk checkout.  
+
* See http://semver.org/ for more details
  
 
===title===
 
===title===
Line 48: Line 57:
 
* A creator listed as follows:
 
* A creator listed as follows:
 
   Dave Tarrant <foo@bar.com>
 
   Dave Tarrant <foo@bar.com>
* More than one creator can be specified in this way (comma separated)
+
* More than one creator can be specified by adding additional creator lines.
  
 
===icon===
 
===icon===
 
* The icon file which should be within the root directory of the package
 
* 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)===
 
===configuration_file (not required)===
Line 83: Line 97:
 
* Get sword working for submission of EPMs
 
* 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.
 
* 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

Latest revision as of 00:11, 12 September 2018


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