# Guidelines for bioconda recipes¶

## bioconda recipe checklist¶

• Source URL is stable (details)
• Appropriate build number (details)
• .bat file for Windows removed (details)
• Files created by the recipe follow the FSH (details)
• License allows redistribution and license is indicated in meta.yaml
• Package does not already exist in the defaults, r, or conda-forge channels with some exceptions (details)
• Package is appropriate for bioconda (details)
• If the recipe installs custom wrapper scripts, usage notes should be added to extra -> notes in the meta.yaml.
• Update 7 Feb 2018: Previously we had recommended that if the recipe is a pure Python package, it should be marked as a “noarch” package (details). However due to technical incompatibilies we can’t do this – so please DO NOT use "noarch" for now.
• Update 7 Mar 2018: When patching a recipe, please provide details on how you tried to address the problem upstream (details)

### Stable urls¶

While supported by conda, git_url and git_rev are not as stable as a git tarball. Ideally a github repo should have tagged releases that are accessible as tarballs from the “releases” section of the github repo.

TODO: additional info on the various R and bioconductor URLs

### Hashes¶

We support either sha256 or md5 checksums to verify the integrity of the source package. If a checksum is provided alongside the source package, then use that. Otherwise we prefer sha256 over md5.

Use shasum -a 256 ... (or sha256sum or openssl sha256 etc) on a file to compute its sha256 hash, and copy this into the recipe, for example:

## Perl¶

Use conda skeleton cpan <packagename> to build a recipe for Perl and place the recipe in the recipes dir. The recipe will have the perl- prefix.

An example of such a package is perl-module-build.

Alternatively, you can additionally ensure the build requirements for the recipe include perl-app-cpanminus, and then the build.sh script can be simplified. An example of this simplification is perl-time-hires.

If the recipe was created with conda skeleton cpan, the tests are likely sufficient. Otherwise, test the import of modules (see the imports section of the meta.yaml files in above examples).

## C/C++¶

Build tools (e.g., autoconf) and compilers (e.g., gcc) should be specified in the build requirements.

We have decided that to optimize compatibility, gcc needs to be added as a dependency rather than assume it is in the build environment. However there is still discussion on how best to do this on OSX. For now, please add gcc (for Linux packages) and llvm (for OSX packages) to the meta.yaml as follows:

requirements:
build:
- gcc   # [not osx]
- llvm  # [osx]

run:
- libgcc    # [not osx]


If the package uses zlib, then please see the troubleshooting section on zlib.

• example requiring autoconf: srprism
• simple example: samtools

If your package links dynamically against a particular library, it is often necessary to pin the version against which it was compiled, in order to avoid ABI incompatibilities. Instead of hardcoding a particular version in the recipe, we use jinja templates to achieve this. This helps ensure that all bioconda packages are binary-compatible with each other. For example, bioconda provides an environnmnet variable CONDA_BOOST that contains the current major version of Boost. You should pin your boost dependency against that version. An example is the salmon recipe. You find the libraries you can currently pin in scripts/env_matrix.yml. If you need to pin another library, please notify @bioconda/core, and we will set up a corresponding environment variable.

It’s not uncommon to have difficulty compiling package into a portable conda package. Since there is no single solution, here are some examples of how bioconda contributors have solved compiling issues to give you some ideas on what to try:

• ococo edits the source in build.sh to accommodate the C++ compiler on OSX
• muscle patches the makefile on OSX so it doesn’t use static libs
• metavelvet, eautils, preseq have several patches to their makefiles to fix LIBS and INCLUDES, INCLUDEARGS, and CFLAGS
• mapsplice includes an older version of samtools; the included samtools’ makefile is patched to work in conda envs.
• mosaik has platform-specific patches – one removes -static on linux, and the other sets BLD_PLATFORM correctly on OSX
• mothur and soapdenovo have many fixes to makefiles

## General command-line tools¶

If a command-line tool is installed, it should be tested. If it has a shebang line, it should be patched to use /usr/bin/env for more general use. An example of this is fastq-screen.

For command-line tools, running the program with no arguments, checking the programs version (e.g. with -v) or checking the command-line help is sufficient if doing so returns an exit code 0. Often the output is piped to /dev/null to avoid output during recipe builds.

Examples:

If a package depends on Python and has a custom build string, then py{{CONDA_PY}} must be contained in that build string. Otherwise Python will be automatically pinned to one minor version, resulting in dependency conflicts with other packages. See mapsplice for an example of this.

## Metapackages¶

Metapackages tie together other packages. All they do is define dependencies. For example, the hubward-all metapackage specifies the various other conda packages needed to get full hubward installation running just by installing one package. Other metapackages might tie together conda packages with a theme. For example, all UCSC utilities related to bigBed files, or a set of packages useful for variant calling.

For packages that are not anchored to a particular package (as in the last example above), we recommended semantic versioning starting at 1.0.0 for metapackages.

## Other examples of interest¶

Packaging is hard. Here are some examples, in no particular order, of how contributors have solved various problems:

• graphviz has an OS-specific option to configure
• crossmap removes libs that are shipped with the source distribution
• hisat2 runs 2to3 to make it Python 3 compatible, and copies over individual scripts to the bin dir
• krona has a post-link.sh script that gets called after installation to alert the user a manual step is required
• htslib has a small test script that creates example data and runs multiple programs on it
• spectacle runs 2to3 to make the wrapper script Python 3 compatible, patches the wrapper script to have a shebang line, deletes example data to avoid taking up space in the bioconda channel, and includes a script for downloading the example data separately.
• gatk is a package for licensed software that cannot be redistributed. The package installs a placeholder script (in this case doubling as the jar wrapper) to alert the user if the program is not installed, along with a separate script (gatk-register) to copy in a user-supplied archive/binary to the conda environment

## Name collisions¶

In some cases, there may be a name collision when writing a recipe. For example the wget recipe is for the standard command-line tool. There is also a Python package called wget on PyPI. In this case, we prefixed the Python package with python- (see python-wget). A similar collision was resolved with weblogo and python-weblogo.

If in doubt about how to handle a naming collision, please submit an issue.

## Tests¶

An adequate test must be included in the recipe. An “adequate” test depends on the recipe, but must be able to detect a successful installation. While many packages may ship their own test suite (unit tests or otherwise), including these in the recipe is not recommended since it may timeout the build system on CircleCI. We especially want to avoid including any kind of test data in the repository.

Note that a test must return an exit code of 0. The test can be in the test field of meta.yaml, or can be a separate script (see the relevant conda docs for testing).

It is recommended to pipe unneeded stdout/stderr to /dev/null to avoid cluttering the output in the CircleCI build environment.

It is possible to include scripts that are executed before or after installing a package, or before uninstalling a package. These scripts can be helpful for alerting the user that manual actions are required after adding or removing a package. For example, a post-link.sh script may be used to alert the user that he or she will need to create a database or modify a settings file. Any package that requires a manual preparatory step before it can be used should consider alerting the user via an echo statement in a post-link.sh script. These scripts may be added at the same level as meta.yaml and build.sh:

• pre-link.sh is executed prior to linking (installation). An error causes conda to stop.
• post-link.sh is executed after linking (installation). When the post-link step fails, no package metadata is written, and the package is not considered installed.
• pre-unlink.sh is executed prior to unlinking (uninstallation). Errors are ignored. Used for cleanup.

• $PREFIX The install prefix • $PKG_NAME The name of the package
• $PKG_VERSION The version of the package • $PKG_BUILDNUM` The build number of the package