DOC: Overview on building conda packages locally

building_fsl_conda_packages.md

+# Building FSL conda packages locally
+
+
+This document describes how to build a conda package for an FSL project from the corresponding conda reicpe.
+
+
+It does not describe how to *create* a conda recipe for a FSL project - that is described in [`fsl_conda_recipes.md`](fsl_conda_recipes.md).
+
+
+Normally there should be no need to build FSL conda packages by hand, as stable and development packages are automatically built using Gitlab CI. However the need may arise for development, testing, or debugging purposes, and hence is described here.
+
+
+In order to build a FSL conda package locally, all you need is a (mini)conda environment with `conda-build` installed. You do not need to have a compiler, or even FSL, installed.
+
+
+## Step 1: Clone the recipe repository
+
+
+You must have a local clone of the recipe repository. For example, if you would like to build a package for `fsl/avwutils`:
+
+
+```bash
+git clone https://git.fmrib.ox.ac.uk/fsl/conda/fsl-avwuitls
+```
+
+
+By default, the `fsl-avwutils` conda recipe will build a package from the last released version (tag) on the `fsl/avwutils` gitlab repository. If you would like to build a package for a different release, or for a specific branch, you can set the `FSLCONDA_REVISION` variable to override the default setting. For example, if you want to build a package for the `master` branch:
+
+
+```bash
+export FSLCONDA_REVISION=master
+```
+
+
+If you would like to build a package from a *local* clone of `fsl/avwutils`, you can use the `FSLCONDA_REPOSITORY` variable to override the default setting (which is to build from the gitlab `fsl/avwutils` project):
+
+
+```bash
+git clone https://git.fmrib.ox.ac.uk/fsl/avwuitls.git
+export FSLCONDA_REPOSITORY=$(pwd)/avwutils
+```
+
+
+> Note: It is not currently possible to build a conda package from a local copy of a project which is *not* a git repository. This functionality may be added in the future if it is deemed necessary.
+
+
+Now you can run `conda build` to build the conda package. The channel order is very important, and must be:
+ 
+1. `conda-forge` Packages from conda-forge have highest priority
+2. `defaults` Packages from anaconda have higher priority than the FSL channel
+3. The FSL conda channel has the lowest priority.
+
+
+> Note: The FSL conda channel URL is not yet finalised. 
+
+
+```bash
+cd fsl-avwutils
+conda build                  \
+  -c conda-forge             \
+  -c defaults                \
+  -c <fsl-conda-channel-url> \
+  --output-folder=dist       \
+  .
+```