For information on updating Planemo, installing the latest development release,
or installing planemo via bioconda - checkout the installation
documentation.

Planemo is also available as a virtual appliance bundled
with a preconfigured Galaxy server and set up for Galaxy tool development.
You can choose from open virtualization format (OVA, .ova), Docker,
or Vagrant appliances.

Planemo Basics

This quick start will assume you have a directory with one or more
tool XML files. If none is available, one can be quickly created for
demonstrating planemo as follows mkdir mytools; cd mytools; planemo
project_init --template=demo.

Planemo can check tools containing XML for common problems and best
practices using the lintcommand
(also aliased as l).

$ planemo lint

Like many planemo commands - by default this will search the
current directory and use all tool files it finds. It can be explicitly
passed a path to tool files or a directory of tool files.

$ planemo l randomlines.xml

The lint command takes in additional options related to
reporting levels, exit code, etc. These options are described
in the docs
or (like with all commands) can be accessed by passing --help to it.

$ planemo l --help
Usage: planemo lint [OPTIONS] TOOL_PATH

Once tools are syntactically correct - it is time to test. The testcommand
can be used to test a tool or a directory of tools.

$ planemo test --galaxy_root=../galaxy randomlines.xml

If no --galaxy_root is defined, planemo will check for a default in
~/.planemo.yml and finally
search the tool’s parent directories for a Galaxy root directory.
Planemo can also download and configure a disposable Galaxy instance for
testing. Pass --install_galaxy instead of --galaxy_root.

$ planemo t --install_galaxy

Planemo will create a HTML output report in the current directory named
tool_test_output.html (override with --test_output). See an
example
of such a report for Tophat.

Once tools have been linted and tested - the tools can be viewed in a
Galaxy interface using the serve (s) command.

$ planemo serve

Like test, serve requires a Galaxy root and one can be
explicitly specified with --galaxy_root or installed dynamically
with --install_galaxy.

The test and serve commands above require the target Galaxy to be 16.01 or higher.

Galaxy can also simply run inside an existing conda environment and
rather than using dependency resolution Conda packages can just be picked
up from the PATH.

Note: This isn’t a well supported approach yet, and when possible Planemo
and Galaxy should not be installed inside of Conda and the conda dependency
resolution (as described above) should be used to allow tools to find Conda
packages.

To run Galaxy within a Conda environment, Planemo must be installed outside the
Conda environment - via pip into a virtual environment or via homebrew. In the
former case, don’t place the virtualenv’s bin directory on your PATH - it
will conflict with Conda. Just reference Planemo directly
/path/to/planemo_venv/bin/planemo test.

To run Galaxy from within the environment you will need to install Galaxy
dependencies into the conda environment. Target the development branch of Galaxy
for this since it has “unpinned” dependencies that are easier to fullfill for
conda.

TravisCI

When tools are ready to be published to GitHub, it may be valuable to setup
continuous integration to test changes committed and new pull requests.
Travis CI is a service providing free testing and deep integration with
GitHub.

The travis_initcommand will bootstrap a project with files to ease continuous integration
testing of tools using a Planemo driven approach inspired by this great blog
post by Peter Cock.

In this example the file .travis/setup_custom_dependencies.bash should
install the dependencies required to test your files on to the Travis user’s
PATH.

This testing approach may only make sense for smaller repositories with a
handful of tools. For larger repositories, such as tools-devteam or
tools-iuc simply linting tool and tool shed artifacts may be more feasible.
Check out the .travis.yml file used by the IUC as example.

Docker Containers

Galaxy has experimental support for running jobs in
Docker containers. Planemo contains tools to assist in development of Docker
images for Galaxy tools.

A shell can be launched to explore the Docker environment referenced by tools
that are annotated with publically registered Docker images.

$ (planemo docker_shell bowtie2.xml)

For Docker containers still in development - a Dockerfile can be associated
with a tool by sticking it in the tool’s directory. Planemo can then build
and tag a Docker image for this tool and launch a shell into it using the
following commands.

Brew

The Galaxy development team was exploring (the effort has since shifted towards
Conda) different options for integrating Homebrew and linuxbrew with Galaxy.
One angle is resolving the tool requirements using brew. An experimental
approach for versioning of brew recipes will be used. See full discussion on
the homebrew-science issues page
here.
Information on the implementation can be found
https://github.com/jmchilton/platform-brew until a more permanent project home
is setup.

0.46.1 (2017-09-26)

0.46.0 (2017-09-15)

Change behavior of --docker flag, for a few releases it would require
Galaxy use a container for every non-upload tool. This breaks various
conversion tools for instance and so was reverted.
Pull Request 733

Implement an open (or just o) command to quickly open the last test results
(or any file if supplied). Pull Request 641

Linting improvements and fixes due to galaxy-lib update.
* WARN on test output names not found or not matching.
* INFO correct information about stdio if profile version is found.
* WARN if profile version is incorrect.
* INFO profile version
* Fix assert_command not detected as a valid test (fixes Issue 260).

Have lint --conda_requirements check that at least one actual requirement is found.
6638caa

Allow conda_install to work with packages as well as just tools.
8faf661

Add --global option to conda_install to install requirements into global Conda setup
instead of using an environment.
8faf661

Implement planemo lint --biocontainer that checks that a tool has an available BioContainer
registered.
0a1abfe

Add more options and more documentation to the planemo mull command.
0a1abfe

Hack around a bug in Conda 4.2 that makes it so planemo mull doesn’t work out of the box on
Mac OS X.
0a1abfe

Allow URIs to be used instead of paths for a couple operations. ce0dc4e

0.37.0 (2017-01-25)

Update to the latest galaxy-lib release. This means new installs start with
Miniconda 3 instead of Minicoda 2 and at a newer version. This fixes many
Conda related bugs.

Change defaults so that Conda automatically initializes and performs tool installs
by default from within the spawned Galaxy server. The trio of flags
--conda_dependency_resolution, --conda_auto_install, and --conda_auto_init
are effectively enabled by default now. 4595953

0.34.0 (2016-10-05)

Implement --mulled_containers flag on test, serve, and run
commands to run tools in “mulled” containers. Galaxy will first search
locally cache containers (such as ones built with mull), then search
the mulled namespace of quay.io, and finally build one on-demand if
needed using galaxy-lib and Involucro developed by @thriqon.

Implement --conda_requirements flag on lint command to ensure requirements
can be resolved in best practice channels. 9da8387

0.25.1 (2016-05-11)

0.25.0 (2016-05-11)

Implement Galaxy “profiles” - the ability to configure
perisistent, named environments for serve and test.
5d08b67

Greatly improved serve command - make test-data
available as an FTP folder, (on 16.07) automatically log
in an admin user, and many more options (such as those
required for “profiles” and a --daemon mode).

0.9.0 (2015-05-03)

Implement smarter shed_diff command - it now produces a meaningful
exit codes and doesn’t report differences if these correspond to attributes
that will be automatically populated by the Tool Shed. Issue 167

Use new smarter shed_diff code to implement a new --check_diff
option for shed_upload - to check for meaningful differences before
updating repositories. Issue 168

Record git commit hash during shed_upload if the .shed.yml is
located in a git repository. Issue 170

0.8.2 (2015-04-29)

0.8.1 (2015-04-28)

Fixes for the source distribution to allow installation of 0.8.0 via Homebrew.

0.8.0 (2015-04-27)

Implement the new shed_lint command that verifies various aspects of tool
shed repositories - including XSD validation of repository_dependencies.xml
and tool_dependencies.xml files, best practices for README files, and the
contents of .shed.yml files. This requires the lxml library to be available
to Planemo or the application xmllint to be on its PATH. Pull Request 130Issue 89Issue 91912df02d26929e36ac6d8

Allow skipping specific linters when using the lint command using the new
--skip option. 26e3cdb

Implement sophisticated options in .shed.yml to map a directory to many,
custom Tool Shed repositories during shed operaitons such shed_upload
including automatically mapping tools to their own directories and automatically
building suites repositories. Pull Request 143

Make shed_upload more intelligent when building tar files so that package
and suite repositories may have README files in source control and they will
just be filtered out during upload. 53edd99

Implement a new shed_init command that will help bootstrap .shed.yml
files in the specified directory. cc1a447

Fix test data command-line argument name (was test-data now it is
test_data). 834bfb2

Use tool_data_table_conf.xml.sample file if
tool_data_table_conf.xml.test is unavailable. Should allow some
new tools to be tested without modifying Galaxy’s global
tool_data_table_conf.xml file. ac4f828

0.2.0 (2015-01-13)

Improvements to way Planemo loads its own copy of Galaxy modules to prevent
various conflicts when launching Galaxy from Planemo. Pull Request 56