# FSL conda package infrastructure


_This documentation is a work in progress_


This repository hosts information and documentation regarding the FSL conda package infrastructure. 

This `README` file contains a general overview. More detailed information on different topics can be found in the folowing files:

 - [`official_fsl_installations.md`](official_fsl_installations.md): Details on "official"/full conda-based FSL installations.
 - [`local_development.md`](local_development.md): Setting up an FSL development environment on your own machine.
 - [`creating_fsl_conda_recipes.md`](creating_fsl_conda_recipes.md): Details on how to create a FSL conda recipe.
 - [`building_fsl_conda_packages.md`](building_fsl_conda_packages.md): Details on how to build a FSL conda package locally.


## Overview

FSL is installed using the [**conda**](https://conda.io/) package and environment management system. Each FSL project is built as a conda package, and published to an internally hosted conda channel.

Prior to FSL 6.1.0, FSL was released and installed as a monolithic archive file, containing most FSL tools, and a separate conda environment called "`fslpython`", configured after the archive file was installed. Some of the reasons for transitioning to a purely conda-based release model are as follows:

 - Simplify FSL installation procedure
 - Reduce the size of `$FSLDIR`
 - Allow "minimal" FSL installations, with only the utilities that are required
 - Improve support for container-based FSL installations
 - Simplify cross-platform management of external dependencies (e.g. VTK, OpenBLAS)


## Official FSL installations


Each official FSL release is defined by a conda [`environment.yml` specification](https://docs.conda.io/projects/conda/en/latest/user-guide/tasks/manage-environments.html#create-env-file-manually). This specification contains a list of all of the packages, including their versions, to be installed.

The official fsl/installer> script performs the following tasks:

1. Downloads a `miniconda` installer.
2. Installs a base `miniconda` environment into `$FSLDIR/../.fslconda/` (where `$FSLDIR` defaults to `/usr/local/fsl/`, or is explicitly specified by the user).
3. Creates a child conda environment at `$FSLDIR`.
4. Installs all FSL packages into the `$FSLDIR` conda environment.


## Partial FSL installations


Users may choose to install specific FSL packages by installing the desired FSL packages directly from the FSL conda channel into their own conda environment.


## FSL conda packages

All FSL projects and their dependencies are published as conda packages, either in the internal FMRIB conda channel, or on https://anaconda.org, in one of the `conda-forge` or `defaults` channels.

All FSL projects, and any dependencies which are not available on https://anaconda.org, are built according to a conda "recipe", which describes how the project can be built as a conda package. All FSL conda recipes are hosted as git repositories on the FMRIB gitlab server, under the `fsl/conda/` group.

To clarify, each FSL project, and internally managed dependency, comprises **two** git repositories:

* The project repository contains the project source code/resources, and is typically hosted at `https://git.fmrib.ox.ac.uk/fsl/<project>`<sup>*</sup>
* The recipe repository contains a conda recipe for the project, and is hosted at `https://git.fmrib.ox.ac.uk/fsl/conda/fsl-<project>`.


> <sup>*</sup> Some FSL projects and dependencies are hosted externally, such as [MSM](https://github.com/ecr05/MSM_HOCR) and [oxford_asl](https://github.com/ibme-qubic/oxford_asl/). The conda recipes for these projects are, however, hosted internally in the `fsl/conda/` gitlab group.


FSL conda packages are built automatically using Gitlab CI - the CI infrastructure for automatically building conda packages is hosted in the fsl/fsl-ci-rules> repository.