===================
Conda build recipes
===================

To enable building conda packages, :doc:`install and update conda
and conda build <install-conda-build>`.

Building a conda package requires a recipe. A conda build recipe
is a flat directory that contains the following files:

* ``meta.yaml``---A file that contains all the metadata in the
  recipe. Only ``package/name`` and ``package/version`` are
  required.

* ``build.sh``---The script that installs the files for the
  package on macOS and Linux. It is executed using the ``bash``
  command.

* ``bld.bat``---The build script that installs the files for the
  package on Windows. It is executed using ``cmd``.

* ``run_test.[py,pl,sh,bat]``---An optional Python test file, a
  test script that runs automatically if it is part of the recipe.

* Optional patches that are applied to the source.

* Other resources that are not included in the source and cannot
  be generated by the build scripts. Examples are icon files,
  readme files and build notes.

TIP: When you use the `conda skeleton <skeleton_ref>` command,
the first 3 files---``meta.yaml``, ``build.sh`` and
``bld.bat``---are automatically generated for you.


Conda build process
====================

``conda-build`` performs the following steps:

#. Reads the metadata.

#. Downloads the source into a cache.

#. Extracts the source into the source directory.

#. Applies any patches.

#. Re-evaluates the metadata, if source is necessary to fill any
   metadata values.

#. Creates a build environment, and then installs the build
   dependencies there.

#. Runs the build script. The current working directory is the
   source directory with environment variables set. The build
   script installs into the build environment.

#. Performs some necessary post-processing steps, such as shebang
   and rpath.

#. Creates a conda package containing all the files in the build
   environment that are new from step 5, along with the necessary
   conda package metadata.

#. Tests the new conda package if the recipe includes tests:
  
   #. Deletes the build environment.

   #. Creates a test environment with the package and its
      dependencies.

   #. Runs the test scripts.

The `conda-recipes
<https://github.com/continuumio/conda-recipes>`_ repo
contains example recipes for many conda packages.

CAUTION: All recipe files, including ``meta.yaml`` and build
scripts, are included in the final package archive that is
distributed to users. Be careful not to put sensitive information
such as passwords into recipes where it could be made public.

The `conda skeleton <skeleton_ref>` command can help to make
skeleton recipes for common repositories, such as `PyPI
<https://pypi.python.org/pypi>`_.
