EPM Development

This page describes how to develop EPrints Package Management (EPM) extensions using a code versioning tool. The goal is to have your EPM source files managed through a code versioning tool and be able to edit them in a live repository.

Tracking files in EPM and SVN is more complex but allows easier development. Because you can't track individual files in SVN you must place all of your package's files under an independent directory tree and then sym-link them into the correct locations in EPrints. The API:tools/epm provides a link_lib option that makes this easier to achieve, as long as you follow the directory layout described below.

Warning! do not edit files and then enable/disable or install/uninstall an EPM. The EPM will detect the changed files and either create backups or refuse to work. You must edit the EPM and do Save and Return to re-scan the EPM's files (in Admin → EPrints Bazaar, Developer Tools).

Creating a blank EPM

Under Admin (System Tools) → EPrints Bazaar (Developer Tools), enter a unique name for the package in Create a new EPM and click Create. For this howto we will call the extension biscuits.

The GUI will create the lib/epm/biscuits tree for you.

Add the blank EPM to SVN

From your EPrints root directory create a new SVN directory and check it out over the top of the EPM-created directory tree:

svn mkdir https://mysvn.example/biscuits -m " * Biscuits"
svn checkout https://mysvn.example/biscuits lib/epm/biscuits

Add .epmi and cfg to SVN:

cd lib/epm/biscuits
svn add biscuits.epmi cfg/
svn commit -m " * Biscuits EPM blank"

Adding a System-level Plugin

We'll use the epm/biscuits directory to hold our files to be managed by SVN.

pushd lib/epm/biscuits
mkdir -p lib/plugins/EPrints/Plugin/Export/
nano lib/plugins/EPrints/Plugin/Export/Biscuits.pm # Write a basic plugin
svn add lib
svn commit -m " * Biscuits export"
popd

Use the link_lib argument in API:tools/epm to sym-link the plugin into your live repository:

./tools/epm link_lib biscuits

Finally, add your plugin to the list of files the biscuits EPM is tracking. In the Developer Tools screen for biscuits find the plugin and click to track it. (If the file does not appear you may need to refresh the file list by Save and Return and re-editing the EPM.)

This technique can be applied to any other files you want to install below lib/ (and hence be available to all repositories).

Adding a Repository-level Config File

Ensure your EPM is Enabled for the repository you are developing in. The EPM Developer Tools already created a cfg/cfg.d tree in the lib/epm directory. Add a new zz_biscuits.pl configuration file:

pushd lib/epm/biscuits/cfg/cfg.d
nano zz_biscuits.pl # $c->{plugins}->{'Export::Biscuits'}->{params}->{disable} = 0
svn add zz_biscuits.pl
svn ci -m " * zz_biscuits.pl"
popd

In the Developer Tools screen add zz_biscuits.pl to the files controlled by the biscuits EPM.

Normally enabling the EPM would copy the zz_biscuits.pl file into your repository but instead we want to sym-link it so we can edit it:

ln -s lib/epm/biscuits/cfg/cfg.d/zz_biscuits.pl archives/[archiveid]/cfg/cfg.d/zz_biscuits.pl

Any files you add below cfg/ and are tracked by the EPM will be added to the repository when the EPM is enabled.