Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
116 lines (83 sloc) 4.39 KB

Conda build recipes

Introduction

Building a conda package with conda build involves creating a conda recipe. The recipe is a flat directory holding metadata and the scripts needed to build the package. The conda package is then built from the conda recipe using the conda build command.

Conda packages can be built from a variety of source code projects, most notably Python. Please refer to the Setuptools documentation for help packing a Python project.

TIP: If you are new to building packages with conda, we recommend taking our series of three :doc:`build tutorials </build_tutorials>`.

Conda build requirements

Conda and conda-build are required, and available from either Miniconda or Anaconda. Please follow the :doc:`Quick install</install/quick>` instructions.

All platforms: Install conda-build:

conda install conda-build

OPTIONAL: If you wish to upload packages to Anaconda.org , an Anaconda.org account and client are required.

Update conda build

It is important to keep your version of conda build up to date to take advantage of bug fixes and new features.

All platforms: Upgrade conda-build:

conda update conda
conda update conda-build

Release notes are available on the conda-build Github page.

Conda recipe files overview

The files in a conda recipe are:

  • meta.yaml (metadata file)
  • build.sh (Unix build script which is executed using bash)
  • bld.bat (Windows build script which is executed using cmd)
  • run_test.[py,pl,sh,bat] (optional) test file
  • patches to the source (optional, see below)
  • other resources, which are not included in the source and cannot be generated by the build scripts. Examples are icon files, readme, or build notes.

Conda-build invokes the following steps in this order:

  1. Reads the metadata.
  2. Downloads the source into a cache.
  3. Extracts the source into the source directory.
  4. Applies any patches.
  5. If source was necessary to fill any metadata values, the metadata is re-evaluated.
  6. Creates a build environment and installs the build dependencies there.
  7. Runs the actual build script. The current working directory is the source directory with environment variables set. The build script installs into the build environment.
  8. Does some necessary post-processing steps: shebang, rpath, etc.
  9. Packages up all the files in the build environment that are new from step 5 into a conda package along with the necessary conda package metadata.
  10. Tests the new conda package: deletes the build environment and creates a test environment with the package and its dependencies, and runs the test scripts. This step is not run if there are no tests in the recipe.

There are example recipes for many conda packages in the conda-recipes repo.

NOTE: All recipe files, including meta.yaml and build scripts, are included in the final package archive which is distributed to users, so be careful not to put passwords or other sensitive information into recipes where it could leak to the public.

The :ref:`conda skeleton <skeleton_ref>` command can help to make skeleton recipes for common repositories, such as PyPI.

Adding Windows start menu items

When a package is installed it can add a shortcut to the Windows start menu. Conda and conda build handle this with the package menuinst, which only supports Windows at this time. Instructions for using menuinst are available on the menuinst wiki.

The easiest way to ensure a package made with conda constructor does not install any menu shortcuts is by removing menuinst from the list of conda packages included. To do this, add the following to the constuct.yaml file:

exclude:
  - menuinst

More information about meta.yaml

Next, please continue on to learn more about :doc:`the meta.yaml file<meta-yaml>`.