Commit bf5f8ba4 authored by Paul McCarthy's avatar Paul McCarthy 🚵
Browse files

DOC: Updates to bring in line with recent developments

parent 0af6f7e3
......@@ -24,6 +24,26 @@ different topics can be found in the folowing files:
on how to create a FSL conda recipe.
## Quick summary
FSL is organised into a number of repositories hosted at
https://git.fmrib.ox.ac.uk.
- `fsl/conda/docs`: (this repository): High level documentation
- `fsl/<project>`: Source code repository for FSL project `<project>`
- `fsl/conda/fsl-<project>`: Conda recipe repository for FSL project
`<project>`
- `fsl/fsl-ci-rules`: CI rules for automated building and publishing of
FSL conda packages
- `fsl/conda/manifest`: Generating and releasing `manifest.json` and
`environment.yml` files for public and internal FSL releases.
- `fsl/conda/manifest-rules`: Scripts used by the `fsl/conda/manifest`
repository.
- `fsl/conda/installer`: Home of the `fslinstaller.py` script, for
installing FSL
## Overview
FSL is installed using the [**conda**](https://conda.io/) package and
......@@ -31,7 +51,7 @@ 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
Prior to FSL 6.0.6, 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
......@@ -47,24 +67,30 @@ follows:
OpenBLAS)
## Official FSL installations
## FSL releases
FSL releases are installed via a script called `fslinstaller.py`, which is
maintained at the fsl/conda/installer> repository.
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.
Each available build (e.g. Linux, macOS, etc) for 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. Available `environment.yml` builds are described by
a `manifest.json` file. The `manifest.json` and `environment.yml` files for
both public and internal releases are generated from information stored in the
fsl/conda/manifest> repository.
The official fsl/installer> script performs the following tasks:
The `fslinstaller.py` 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.
1. Downloads the FSL release `manifest.json` file, and the appropriate
`environment.yml` file for the platform.
2. Downloads a `miniconda` installer.
3. Installs a base `miniconda` environment into `$FSLDIR` (where `$FSLDIR`
defaults to `/usr/local/fsl/`, or is explicitly specified by the user).
4. Installs all FSL packages into the `$FSLDIR` base conda environment.
5. Sets up the user shell profile so that FSL is configured in their shell
environment by default.
......@@ -88,9 +114,9 @@ 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 their dependencies are published as conda packages. Most
FSL conda packages are published to an internally maintained channel, but some
packages are published to the `conda-forge` channel at https://anaconda.org.
All FSL projects, and any dependencies which are not available on
......@@ -119,25 +145,29 @@ fsl/fsl-ci-rules> repository.
> [`fsl/fdt`](https://git.fmrib.ox.ac.uk/fsl/fdt) project has two recipes -
> the [`fsl/conda/fsl-fdt`](https://git.fmrib.ox.ac.uk/fsl/conda/fsl-fdt)
> recipe provides CPU executables, and the
> [`fsl/conda/fsl-fdt-gpu`](https://git.fmrib.ox.ac.uk/fsl/conda/fsl-fdt-gpu)
> [`fsl/conda/fsl-fdt-cuda`](https://git.fmrib.ox.ac.uk/fsl/conda/fsl-fdt-cuda)
> recipe provides GPU/CUDA executables.
## Production and staging channels
## Public and internal channels
FSL projects are published to one of two conda internally managed conda
channels:
FSL projects are published to two separate conda channels:
- The **public** channel contains stable and development packages for most
FSL projects. Every time a new tag is added to a project repository, a
stable conda package is built and published to the public channel. Every
time commits are merged into the master branch of a repository, a
development conda package is built and published to the public channel.
- The **production** channel contains stable packages for public release.
Every time a new tag is added to a project repository, a conda package is
built and published to the production channel.
- The **staging** channel contains development packages for internal use.
Every time new commits are added to the master branch of a project
repository, a conda package is built and published to the
staging channel.
- The **internal** channel contains stable and development packages for FSL
projects which are not part of official FSL releases, and are only part of
internal release.
These channels are currently hosted online at the following URLs, although
their location will potentially change in the future:
- http://3.9.49.129/fslconda/staging/
- http://3.9.49.129/fslconda/production/
- http://18.133.213.73/public/
- http://18.133.213.73/internal/
......@@ -10,19 +10,21 @@ 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
production/stable and staging/development packages are automatically built
using Gitlab CI. However the need may arise for development, testing, or
debugging purposes, and hence the process is described here.
stable and development packages are automatically built and published using
Gitlab CI. However the need may arise for development, testing, or debugging
purposes, and hence the process 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.
or even FSL, installed. If you are working with internal-only FSL conda
packages, you may also need a username and password to access the internal
FSL conda channel.
> **Note:** If you are building a CUDA package, you need to have `nvcc`
> installed - this cannot be installed through `conda`, so must be installed
> externally.
**Note:** If you are building a CUDA package, you need to have `nvcc` and
a CUDA Toolkit installed - the CUDA-capable FSL conda packages depend on
an externally provided CUDA development environment.
## Step 1: Clone the recipe repository
......@@ -81,40 +83,42 @@ export FSLCONDA_REVISION=master
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.
1. The FSL conda channel has the highest priority.
2. `conda-forge` Packages from conda-forge have higher priority than the
defaults channel.
3. `defaults` Packages from anaconda have lowest priority.
```bash
cd fsl-avwutils
conda build \
-c conda-forge \
-c defaults \
-c http://3.9.49.129/fslconda/production/ \
--output-folder=dist \
conda build \
-c http://18.133.213.73/public/ \
-c conda-forge \
-c defaults \
--output-folder=dist \
.
```
If you need to build against staging/development versions of your
dependencies, add the FSL conda staging channel **before** the production
channel, like so:
If your project depends on internal-only FSL packages, add the internal FSL
conda channel **before** the production channel, like so (replace
`${FSLCONDA_USERNAME}` and `${FSLCONDA_PASSWORD}` with the username/password
for the internal FSL conda channel):
```bash
cd fsl-avwutils
conda build \
-c conda-forge \
-c defaults \
-c http://3.9.49.129/fslconda/staging/ \
-c http://3.9.49.129/fslconda/production/ \
--output-folder=dist \
conda build \
-c http://${FSLCONDA_USERNAME}:${FSLCONDA_PASSWORD@18.133.213.73/internal/ \
-c http://18.133.213.73/public/ \
-c conda-forge \
-c defaults \
--output-folder=dist \
.
```
> **Note:** THe staging and production channel URLs may change in the future.
> **Note:** THe public and internal channel URLs may change in the future.
If the build succeeds, the built package will be saved to the `dist`
......@@ -123,10 +127,8 @@ sub-directories, and platform-independent (e.g. python) packages will be saved
in the `noarch` sub-directory.
> **Note:** IF you are building a CUDA package, you must define an environment
> variable called `CUDA_VER`, which contains the `major.minor` CUDA version
> that you wish to build the package against, before calling `conda
> build`. For example, `export CUDA_VER="9.2"`.
> **Note:** IF you are building a CUDA package, the `nvcc` executable must
> be on your `$PATH`.
## Building multiple FSL conda packages locally
......@@ -165,11 +167,11 @@ mkdir my_local_conda_channel
export FSLCONDA_REPOSITORY=$(pwd)/newimage
export FSLCONDA_REVISION=enh/my_local_newimage_development_branch
conda build \
-c conda-forge \
-c defaults \
-c http://3.9.49.129/fslconda/production/ \
--output-folder=./my_local_conda_channel \
conda build \
-c http://18.133.213.73/public/ \
-c conda-forge \
-c defaults \
--output-folder=./my_local_conda_channel \
./fsl-newimage
```
......@@ -184,11 +186,11 @@ channel URL, so that it takes precedence:
export FSLCONDA_REPOSITORY=$(pwd)/randomise
export FSLCONDA_REVISION=enh/my_local_randomimse_development_branch
conda build \
-c conda-forge \
-c defaults \
-c file://$(pwd)/my_local_conda_channel \
-c http://3.9.49.129/fslconda/production/ \
--output-folder=./my_local_conda_channel \
conda build \
-c file://$(pwd)/my_local_conda_channel \
-c http://18.133.213.73/public/ \
-c conda-forge \
-c defaults \
--output-folder=./my_local_conda_channel \
./fsl-randomise
```
......@@ -11,11 +11,11 @@ repository for your project (recommended), or you can create a conda recipe by
hand.
> **Note:** It is strongly recommended to use the `create_conda_recipe.py`
> script to generate your recipe, or to use an existing FSL conda recipe
> as the basis for your recipe. The automatic CI rules assume that recipes
> adhere to a particular format - if the structure of your recipe deviates
> from this, it may not be able to be automatically updated.
> **Note:** It is strongly recommended to use the `create_conda_recipe`
> command (see below) to generate your recipe, or to use an existing FSL conda
> recipe as the basis for your recipe. The automatic CI rules assume that
> recipes adhere to a particular format - if the structure of your recipe
> deviates from this, it may not be able to be automatically updated.
Conda recipes for all FSL projects, and some internally packaged/managed
......@@ -57,7 +57,7 @@ There are a small number of exceptions to the above conventions. For example,
the [`fdt`](https://git.fmrib.ox.ac.uk/fsl/fdt) project is built into two
conda packages - the [`fsl-fdt`](https://git.fmrib.ox.ac.uk/fsl/conda/fsl-fdt)
package, providing CPU-only executables, and the
[`fsl-fdt-gpu`](https://git.fmrib.ox.ac.uk/fsl/conda/fsl-fdt-gpu) package,
[`fsl-fdt-cuda`](https://git.fmrib.ox.ac.uk/fsl/conda/fsl-fdt-cuda) package,
providing GPU/CUDA-enabled executables.
......@@ -71,14 +71,14 @@ addition to providing GPU-enabled executables such as `xfibres_gpu`.
To accommodate this convention, multiple conda recipes are used for these
"hybrid" projects. For example, the `fsl/fdt` project is built from two
separate recipes:
"hybrid" projects. For example, packages for the `fsl/fdt` project are built
from two separate recipes:
- [`fsl/conda/fsl-fdt`](https://git.fmrib.ox.ac.uk/fsl/conda/fsl-fdt), which
builds the CPU-only executables - these recipes are built as `linux` and
`macos` packages.
- [`fsl/conda/fsl-fdt-gpu`](https://git.fmrib.ox.ac.uk/fsl/conda/fsl-fdt),
- [`fsl/conda/fsl-fdt-cuda`](https://git.fmrib.ox.ac.uk/fsl/conda/fsl-fdt-cuda),
which builds the GPU-enabled executables - these recipes are built as
`linux-cuda-X.Y` and `macos-cuda-X.Y` packages.
......@@ -103,18 +103,16 @@ To generate an initial version of a conda recipe for a new project:
token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html#personal-access-tokens),
which will allow you to programmatically interact with GitLab.
3. Clone the `fsl/fsl-ci-rules` repository, and configure your environment
so you can use `create_conda_recipe`:
3. Install `fsl/fsl-ci-rules` into your `$FSLDIR`:
```
git clone https://git.fmrib.ox.ac.uk/fsl/fsl-ci-rules.git
export PYTHONPATH=$(pwd)/fsl-ci-rules/utils/
$FSLDIR/bin/pip install git+https://git.fmrib.ox.ac.uk/fsl/fsl-ci-rules.git
```
4. Call the script to generate an initial version of the recipe:
```
fslpython -m create_conda_recipe -t <token> <project_path>
create_conda_recipe -t <token> <project_path>
```
where:
......@@ -132,7 +130,7 @@ example, this command command:
```
fslpython -m create_conda_recipe -t <token> paulmc/my_new_project
create_conda_recipe -t <token> paulmc/my_new_project
```
......@@ -145,8 +143,7 @@ repository at `https://git.fmrib.ox.ac.uk/fsl/conda/fsl-my_cool_project`.
The `create_conda_recipe` script has a few options allowing you to control its
behaviour (e.g. create a recipe repository locally insteaad of on GitLab,
create the recipe from a branch other than `master` from the project
repository); run `fslpython -m create_conda_recipe -h` for help on the
available options.
repository); run `create_conda_recipe -h` for help on the available options.
## Create a conda recipe for a FSL project by hand
......@@ -356,12 +353,21 @@ requirements:
Separate packages are created from `Makefile`-based CUDA projects for
different versions of CUDA. To enable this, the `meta.yaml` file for a CUDA
project needs to contain a couple of additional elements. First, when a CUDA
package is built, an environment variable called `CUDA_VER` will be set in the
environment, containing the `major.minor` CUDA version the package is being
built against. The `meta.yaml` file can read this environment variable in as
a `jinja2` variable like so:
each supported CUDA version. For example, multiple packages are built
from the [`fsl-fdt-cuda`](https://git.fmrib.ox.ac.uk/fsl/conda/fsl-fdt-cuda)
recipe - each package is called `fsl-fdt-cudaX.Y`, where `X.Y` denotes the
CUDA version that the package was built against.
To enable this, the `meta.yaml` file for a CUDA project needs to contain a
couple of additional elements. First, when a CUDA package is built, an
environment variable called `CUDA_VER` will be set in the environment,
containing the `major.minor` CUDA version the package is being built against -
this variable is set by the common FSL `Makefile` rules in the
[`fsl/base`](https://git.fmrib.ox.ac.uk/fsl/base) project.
The `meta.yaml` file can read this environment variable in as a `jinja2`
variable like so:
```
......@@ -369,33 +375,27 @@ a `jinja2` variable like so:
```
Built CUDA packages must be labelled with the version of CUDA they were built
Built CUDA packages must be named with the version of CUDA they were built
against. This is accomplished by adding the CUDA version to the package
build string, like so:
name, like so:
```
build:
number: {{ '{{ build }}' }}
string: {{ 'h{{ PKG_HASH }}_cuda{{ cuda_version }}_{{ PKG_BUILDNUM }}' }}
run_exports:
strong:
- {{ '{{ name }}' }}
{% set cuda_label = '-cuda-' + cuda_version %}
{% set name = 'fsl-fdt' + cuda_label %}
```
When a CUDA package is built, the `nvcc` compiler must be installed in the
build environment, as it cannot be installed through `conda`. However, the
CUDA toolkit *can* be installed through conda, in addition to a "shim" `nvcc`
compiler package which allows `conda` to integrate itself with the externally
installed `nvcc` compiler. A further complication is that different versions
of `nvcc` are compatible with different versions of `gcc`, so the version of
`gcc` that should be installed depends on the version of CUDA against which
the package is being built.
When a CUDA package is built, the CUDA toolkit and `nvcc` compiler must be
installed in the build environment independently of conda, but the C++
compiler should be installed via conda. One complication which needs to be
addressed is that different versions of `nvcc` are compatible with different
versions of `gcc`, so the version of `gcc` that should be installed depends on
the version of CUDA against which the package is being built.
To handle all of these complicationes, a template `requirements` section for
a CUDA project needs to look something like this:
To handle this complication, a template `requirements` section for a CUDA
project needs to look something like this:
```
......@@ -405,19 +405,16 @@ requirements:
build:
# Different versions of nvcc need
# different versions of gcc
{{ '{% if cuda_version in ("9.2", "10.0") %}' }}
- {{ '{{ compiler("cxx") }} 7.*' }} # [linux]
{{ '{% elif cuda_version in ("10.1", "10.2") %}' }}
- {{ '{{ compiler("cxx") }} 8.*' }} # [linux]
{{ '{% elif cuda_version in ("11.0", "11.1") %}' }}
- {{ '{{ compiler("cxx") }} 9.*' }} # [linux]
{{ '{% endif %}' }}
{% if cuda_version in ("9.2", "10.0") %}
- {{ compiler("cxx") }} 7.* # [linux]
{% elif cuda_version in ("10.1", "10.2") %}
- {{ compiler("cxx") }} 8.* # [linux]
{% elif cuda_version in ("11.0") %}
- {{ compiler("cxx") }} 9.* # [linux]
{% else %}
- {{ compiler("cxx") }} # [linux]
{% endif %}
- make
# The nvcc_linux-64 package is a shim
# which will use the system-provided
# nvcc, but in a manner that is
# integrated with conda.
- nvcc_linux-64 {{ '{{ cuda_version }}' }} # [linux]
```
......@@ -456,7 +453,7 @@ script is generally not required.
A critical requirement of "hybrid" FSL CUDA projects, which provide both
CPU-only and GPU-capable executables, is that the project `Makefile` must be
able to conditionally compile only the CPU component, **or** the GPU
able to conditionally compile only the CPU components, **or** the GPU
components, provided by the project.
......@@ -472,9 +469,9 @@ project, whereas `make cpu=0 gpu=1` will compile only the GPU components.
The `build.sh` scripts for the
[`fsl-fdt`](https://git.fmrib.ox.ac.uk/fsl/conda/fsl-fdt) and
[`fsl-fdt-gpu`](https://git.fmrib.ox.ac.uk/fsl/conda/fsl-fdt-gpu) take
[`fsl-fdt-cuda`](https://git.fmrib.ox.ac.uk/fsl/conda/fsl-fdt-cuda) take
advantage of this mechanism, so that the `fsl-fdt` recipe will only compile
the CPU components, and the `fsl-fdt-gpu` recipe will only compile the GPU
the CPU components, and the `fsl-fdt-cuda` recipe will only compile the GPU
components
The `build.sh` script for the `fsl-fdt` recipe therefore looks the same as the
......@@ -488,7 +485,7 @@ make cpu=1 install
```
And the `make` invocations in the `build.sh` script for the `fsl-fdt-gpu`
And the `make` invocations in the `build.sh` script for the `fsl-fdt-cuda`
recipe are as follows:
......
......@@ -33,7 +33,7 @@ developer wishes to release a new version.
> [`fsl/fdt`](https://git.fmrib.ox.ac.uk/fsl/fdt) project has two recipes -
> the [`fsl/conda/fsl-fdt`](https://git.fmrib.ox.ac.uk/fsl/conda/fsl-fdt)
> recipe provides CPU executables, and the
> [`fsl/conda/fsl-fdt-gpu`](https://git.fmrib.ox.ac.uk/fsl/conda/fsl-fdt-gpu)
> [`fsl/conda/fsl-fdt-cuda`](https://git.fmrib.ox.ac.uk/fsl/conda/fsl-fdt-cuda)
> recipe provides GPU/CUDA executables.
......@@ -136,11 +136,6 @@ developers follow a similar process for their own projects.
the MR have been made.
Whenever new commits are added to the `master` of a FSL project repository, a
conda package is built from the state of the `master` branch, and released to
an internal development channel.
## Releasing a new version of a FSL project
......@@ -150,7 +145,8 @@ above.
When a new tag is added to a FSL project repository, the corresponding recipe
repository is updated, and a new conda package built and released.
repository is updated, and a new conda package built and published to the
public FSL conda channel.
For projects which are included in FSL, but developed externally
......@@ -158,27 +154,21 @@ For projects which are included in FSL, but developed externally
manually updated on an as-needed basis.
## Development (a.k.a. *staging*) releases
Conda packages for all FSL projects are published to two conda channels:
> **Note:** Some FSL projects are not included in public FSL releases, and are
> only intended to be installed internally. The conda recipe repository for
> such a project can be configured so that both stable and development
> packages are instead published to the internal FSL conda channel - see the
> fsl/fsl-ci-rules> documentation for more details.
- The *production* channel, which contains conda packages built from the most
recently tagged version of each FSL project.
- The *staging* channel, which contains conda packages built from the most
recent state of the `master` branch on the project git repository.
## Development releases
The production channel is used for official FSL installations, and for releasing
important changes and bug fixes to end users. The staging channel is used for
internal releases.
Every time a new tag is added to a project repository, a *production* package
is built and uploaded to the production channel. Every time new commits are
added to the master branch of a project repository, a *staging* package is
built and uploaded to the staging channel.
As described above, every time a new tag is added to a project repository, a
*stable* package is built and uploaded to the public FSL conda
channel. Additionally, every time new commits are added to the master branch
of a project repository, a *development* package is built and uploaded to the
public FSL conda channel.
FSL projects are released as conda packages, and therefore must adhere to
......@@ -186,33 +176,36 @@ conda package versioning conventions, described at
https://docs.conda.io/projects/conda/en/latest/user-guide/concepts/pkg-specs.html#version-ordering.
Packages published to the production channel are versioned as described above
in the **FSL project versioning scheme** section. Packages published to the
staging channel are versioned slightly differently, to ensure a sensible
ordering of version numbers across both staging and production packages. The
version string for a staging package adheres to the following structure:
Stable FSL packages are versioned as described above in the **FSL project
versioning scheme** section. Development FSL packages are versioned slightly
differently, to ensure a sensible ordering of version numbers across both
stable and development packages. The version string for a development package
adheres to the following structure:
<last_production_tag>.post0.dev<date>[+<commit>]
<last_stable_tag>.post0.dev<date>[+<commit>]
where:
- `<last_production_tag>` is the version/tag for the most recent production
release
- `<last_stable_tag>` is the version/tag for the most recent stable release
- `<date>` is the date (`YYYYMMDD`) that the staging package was built
- `<commit>` is the first 7 characters of the git commit that the staging
package was built from. This may be omitted for externally hosted
projects.
For exmaple, if the latest production release for the `fsl/base` project is
`2106.1`, and a new commit, with hash `ac28d14`, is subsequently pushed to
the `fsl/base` master branch on 8 June 2021, the resulting staging package
For exmaple, if the latest stable release for the `fsl/base` project is
`2106.1`, and a new commit, with hash `ac28d14`, is subsequently pushed to the
`fsl/base` master branch on 8 June 2021, the resulting development package
will be assigned the version string `2106.1.post0.dev20210608+ac28d14`.
This convention ensures that, when an environment is created with the staging
channel having higher priority than the production channel, staging packages
which are built after the most recent production package will be given higher
priority, and will be installed in preference to the production package.
This convention ensures that development packages which are built after the
most recent stable package will be given higher priority, and will be
installed in preference to the stable package.
> Note: For official FSL releases, the versions of all FSL packages are pinned
> to specific stable releases, so development packages will not take priority
> in this instance.
# Setting up a local FSL development environment
*This document is written under the assumption that you have FSL 6.1.0 or
*This document is written under the assumption that you have FSL 6.0.6 or
newer, installed via the fslinstaller script. These instructions will not work
for manually managed FSL installations.*
......@@ -25,14 +25,12 @@ like so:
```bash
# Set up your environment for FSL development. The
# fsl-devel.sh script activates the $FSLDIR conda
# environment, effectively adding $FSLDIR/bin to
# your $PATH.
# Set up your environment for FSL development.
export PATH=$FSLDIR/bin:$PATH
source $FSLDIR/etc/fslconf/fsl-devel.sh
# Install the conda-forge C/C++ compiler toolchain
conda install -c conda-forge c-compiler cxx-compiler
# Install the conda-forge C/C++ compiler toolchain and GNU Make
conda install -c conda-forge c-compiler cxx-compiler make
```
Now, when you want to work on a FSL project, you can follow these steps:
......
......@@ -4,37 +4,18 @@
An official FSL installation is a self-contained directory installed on an end
user's system, containing the full collection of FSL commands. An official FSL
installation is typically located at `/usr/local/fsl/` - the FSL installation
directory is identified by the `$FSLDIR` environment variable. A
[**miniconda**](https://docs.conda.io/en/latest/miniconda.html#) environment
is used to create `$FSLDIR`, and install all FSL projects and their
dependencies into `$FSLDIR`, which is itself a conda environment<sup>*</sup>.
> <sup>*</sup> The [conda
> documentation](https://docs.conda.io/projects/conda/en/latest/user-guide/getting-started.html#managing-envs)
> recommends against installing packages into a base conda environment,
> therefore `$FSLDIR` is created as a child environment.
directory is identified by the `$FSLDIR` environment variable. The `$FSLDIR`
directory is a
[**miniconda**](https://docs.conda.io/en/latest/miniconda.html#) environment -
all FSL projects are installed directly into the base miniconda environment
at `$FSLDIR`.