Publishing to the Tool Shed¶
The Galaxy Tool Shed (referred to colloquially in Planemo as the “shed”) can store Galaxy tools, dependency definitions, and workflows among other Galaxy artifacts. This guide will assume some basic familiarity with the shed - please review the Tool Shed Wiki for an introduction.
Configuring a Shed Account¶
Before getting started, it is a good idea to have accounts on the Galaxy test and (optionally) main Tool Sheds. Also, if you haven’t initialized a
global Planemo configuration file (
~/.planemo.yml) this can be done with.
This will populate a template
~/.planemo.yml file and provide locations to
fill in shed credentials for the test and main Tool Sheds. For each shed, fill
in either an API
key or an
password. Also specify the
shed_username created when registering shed accounts. All these options
can be specified and/or overridden on each planemo command invocation - but
that becomes tedious quickly.
Creating a Repository¶
Planemo can be used to used to publish “repositories” to the Tool Shed. A
single GitHub repository or locally managed directory of tools may correspond
to any number of Tool Shed repositories. Planemo maps files to Tool Shed
repositories using a special file called
planemo shed_init --name=<name> --owner=<shed_username> --description=<short description> [--remote_repository_url=<URL to .shed.yml on github>] [--homepage_url=<Homepage for tool.>] [--long_description=<long description>] [--category=<category name>]*
There is not a lot of magic happening here, this file could easily be created
directly with a text editor - but the command has a
--help to assist you
and does some very basic validation.
Periods and hyphens are disallowed in repository names, it is recommended replacing periods in the version number with underscores.
The following naming conventions are recommended and in some cases Planemo will determine the repository type based on adherence to these conventions (for packages and suites specifically).
|Repository Type||Recommended Name||Examples|
More information on
.shed.yml can be found as part of the IUC best
.shed.yml, this configuration file and relevant shed
artifacts can be quickly linted using the following command.
planemo shed_lint --tools
Once the details the
.shed.yml are set and it is time to create the remote
repository and upload artifacts to it - the following two commands can be used
- the first only needs to be run once and creates the repository based the
.shed.yml and the second uploads your actual artifacts to it.
planemo shed_create --shed_target testtoolshed
Updating a Repository¶
Ensure the Galaxy Test Tool Shed is enabled in Galaxy’s
config/tool_sheds_conf.xml file and install and test the new repository.
If modifications are required these can be reviewed using the
planemo shed_diff --shed_target testtoolshed
If you look at tools-iuc you will see it is common practice to leave
details such as shed target and changeset_revision from
repository_dependencies.xml files. These
are required by the Tool Shed but it will populate them on upload and
leaving them blank allows uploading the same artifacts to the Test and
Main sheds. The upshot of this is however is that
shed_diff will always
print diffs on these artifacts.
Modified artifacts can be uploaded using the following command.
planemo shed_update --check_diff --shed_target testtoolshed
--check_diff option here will ensure there are significant differnces
before uploading new contents to the tool shed.
Once tools and required dependency files have been published to the tool shed, the actual shed dependencies can be automatically and installed and tool tests ran using the command:
planemo shed_test --shed_target testtoolshed
Once your artifacts are ready for publication to the main Tool Shed, the following commands to create a repository there and populate it with your repository contents.
The above usage is relatively straight forward - it will map the current directory to a single repository in the Tool Shed.
See Pull Request 143 and linked examples for details on more advanced options such as mapping each tool to its own repository automatically (a best practice) or building enitrely custom repository definitions manually.