official_fsl_installations.md 3.52 KB
Newer Older
1
2
# Official / full FSL installations

Paul McCarthy's avatar
Paul McCarthy committed
3

4
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>.
5
6
7
8
9


> <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.


10
11
12
13
An official (`fslinstaller`-installed) FSL installation can be distinguished from a manually installed/managed FSL installation by the presence of a file called `$FSLDIR/share/fsl/base_environment`. This file is created by the `fslinstaller` script, and is a plain-text file which contains the location of the base miniconda environment.


By default, the base miniconda environment is installed into `$FSLDIR/../.fslconda/` (i.e. `/usr/local/.fslconda/`, if the default setting of `FSLDIR=/usr/local/fsl/` is used), but this can be overridden by the user<sup>*</sup>.
14
15
16
17
18
19
20


> <sup>*</sup> The only possible options for the base/child environment locations are either to have them in separate directories, or to have the child environment directory located within the base environment directory. The former option was chosen, as the latter option would require a system of links to be created from `$FSLDIR/*` into `$FSLDIR/<child-environment>/*`.


Because `$FSLDIR` is a conda environment into which all FSL projects and their dependencies are installed, `$FSLDIR/bin/` will contain executable files provided by both FSL, and by its dependencies. This can give rise to a problem whereby executables in `$FSLDIR/bin/` can mask other executables of the same name which are also installed in the user's environment, but come after `$FSLDIR/bin/` on the user's `$PATH` (e.g. `python`, `conda`, etc).

Paul McCarthy's avatar
Paul McCarthy committed
21

Paul McCarthy's avatar
Paul McCarthy committed
22
To work around this problem, and to isolate all of the FSL executables from the other executables installed into the same environment, the conda packages for all FSL projects use [`post-link.sh` and `pre-unlink.sh`](https://docs.conda.io/projects/conda-build/en/latest/resources/link-scripts.html) scripts to create _wrapper scripts_ within `$FSLDIR/share/fsl/bin/`<sup>*</sup>. These wrapper scripts are created by the [`$FSLDIR/share/fsl/sbin/createFSLWrapper`](https://git.fmrib.ox.ac.uk/fsl/base/-/blob/master/share/fsl/sbin/createFSLWrapper) script, which is installed as part of the [`fsl-base`](https://git.fmrib.ox.ac.uk/fsl/base/) package.
23

Paul McCarthy's avatar
Paul McCarthy committed
24

25
26
> <sup>*</sup> More details on FSL project conda recipes are outlined in [`fsl_conda_recipes.md`](fsl_conda_recipes.md).

Paul McCarthy's avatar
Paul McCarthy committed
27
28
29
30
31
32
33
34
35
36
37

Users can then add the `$FSLDIR/share/fsl/bin/` directory to their `$PATH`, with the effect that only FSL executables will be made available in their environment. This mechanism also has the advantage that all existing FSL and third-party scripts which refer to `$FSLDIR/bin/<command>` will continue to work without modification.


Once an official FSL release has installed onto a user's system, they can configure their environment to use FSL as follows (for a `bash`-compatible shell):

```
export FSLDIR=/usr/local/fsl/
export PATH=$FSLDIR/share/fsl/bin/:$PATH 
source $FSLDIR/etc/fslconf/fsl.sh
```