Github Repositories

Most tool developers are on GitHub, and have chosen to lay out their repositories in a structure similar to the following:

tools-iuc/
├── data_managers
│   └── data_manager_NAME/...
├── LICENSE
├── packages/
│   └── package_NAME_VERSION/tool_dependencies.xml
├── README.rst
├── suites/
│   └── suite_name/...
└── tools/
    └── NAME
        ├── macros.xml
        ├── my_tool.xml
        ├── CHANGELOG.md
        ├── other_tool.xml
        ├── test-data/
        └── tool_dependencies.xml

The highest level directory contains only a few folders for the major types of Galaxy repositories; tools, packages, data managers, and sometimes visualizations and datatypes.

ToolShed Repositories

A Github repository may correspond to any number of published ToolShed repositories.

Every unrestricted tool shed repository should contain a README file - named either README or README.txt (if plain text) or README.rst (if reStructuredText). A reStructuredText README.rst is generally preferred. For a good example of such a file - please see Peter Cock’s NCBI Blast+ Suite’s README.rst.

The Tool Shed recognizes many more types of README files than this - but these are not encouraged and may be deprecated in the future. Markdown is not supported by the Tool Shed at this time and so README.md are not recognized at all.

Package Repositories

These may only contain a tool_dependencies.xml file

Suites

The Toolshed offers the concept of a suite which is simply a meta-package listing several other packages. For example the suite_hmmer_3 provides a package that depends on all of the individual hmmer_.* packages, defined by a repository_dependencies.xml file:

<repositories description="HMMER v3 HMM based sequence alignment and database search tools">
  <repository changeset_revision="ddda6eae7b23" name="hmmer_hmmemit" owner="iuc" toolshed="https://testtoolshed.g2.bx.psu.edu" />
  <repository changeset_revision="5ec773098cb9" name="hmmer_hmmconvert" owner="iuc" toolshed="https://testtoolshed.g2.bx.psu.edu" />
  ...

Manually curated suites are most commonly used to package together related pieces of software by different groups, when that functionality all serves a common purpose.

Suites should NOT be used for a single set of highly related tools from the same group, like the hmmer example above, or bedtools. Instead, a suite can be automatically created for those sets of tools by Planemo.

Tools

Tool often contain:

  • Tool XML files
  • macros.xml file for use in keeping tools DRY
  • test-data/ directory, because all tools need test data
  • tool-data/ directory, for things like *.loc files
  • tool_dependencies.xml file for specifying associated packages
  • CHANGELOG.md file for tracking the history of features over time in your tool