Expand installation options

Author: gllmflndn

docs/assets/figures/matlab_setpath.png

@@ -0,0 +1,73 @@
+# SPM and Containers
+
+## Docker
+
+Docker is a container technology, performing operating-system-level
+virtualisation.
+
+[`https://www.docker.com/`](https://www.docker.com/)
+
+## Singularity
+
+Singularity is another container technology that performs
+operating-system-level virtualization. One of the main uses of
+Singularity is to bring containers and reproducibility to scientific
+computing and HPC.
+
+[`https://sylabs.io/singularity/`](https://sylabs.io/singularity/)  
+[`https://apptainer.org/`](https://apptainer.org/)
+
+## SPM Containers
+
+Official SPM12 `Dockerfile` and `singularity.def` (using the [Standalone
+SPM](standalone.md)):
+
+[`https://github.com/spm/spm-docker`](https://github.com/spm/spm-docker)  
+  
+[`https://github.com/spm/spm-docker/pkgs/container/spm-docker`](https://github.com/spm/spm-docker/pkgs/container/spm-docker)  
+[`https://hub.docker.com/r/spmcentral/spm/`](https://hub.docker.com/r/spmcentral/spm/)
+
+For example, to start SPM with its graphical user interface:
+```
+xhost +local:docker
+docker run -ti --rm -e DISPLAY=$DISPLAY -v /tmp:/tmp -v /tmp/.X11-unix:/tmp/.X11-unix spmcentral/spm fmri
+```
+
+If the container\'s root filesystem is mounted as read only
+(*\--read-only* flag), you need to bind mount an extra volume:
+```
+-v /tmp/.matlab:/root/.matlab
+```
+
+## See also
+
+### Neurodesk
+
+[`https://www.neurodesk.org/`](https://www.neurodesk.org/)
+
+### Neurodocker
+
+[`https://github.com/ReproNim/neurodocker`](https://github.com/ReproNim/neurodocker)  
+[`https://hub.docker.com/r/kaczmarj/neurodocker/`](https://hub.docker.com/r/kaczmarj/neurodocker/)
+
+### SPM BIDS-App
+
+[`https://github.com/BIDS-Apps/SPM`](https://github.com/BIDS-Apps/SPM)  
+[`https://hub.docker.com/r/bids/spm/`](https://hub.docker.com/r/bids/spm/)
+
+### MATLAB Dockerfile
+
+[`https://github.com/mathworks-ref-arch/matlab-dockerfile`](https://github.com/mathworks-ref-arch/matlab-dockerfile)
+
+### Singularity
+
+[SingularityCE User Guide](https://sylabs.io/guides/3.8/user-guide/)
+
+```
+sudo singularity build spm12.sif spm12-octave.def
+singularity exec spm12.sif
+./spm12.sif --help
+```
+
+([how to install singularity on
+Ubuntu](https://github.com/hpcng/singularity/issues/5390#issuecomment-899111181))

docs/installation/containers.md

@@ -1,74 +1,53 @@
-# Installation
+# SPM Installation with MATLAB
 
 !!! info "Prerequisites"
     The SPM software is a collection of [MATLAB](https://www.mathworks.com/products/matlab.html) functions and thus requires the MATLAB software to be installed on your computer in order to run. SPM requires only core MATLAB to run (no special toolboxes are required - unless stated otherwise).
 
     Each SPM version was written for a particular MATLAB version and will not work with earlier versions. MATLAB versions released after SPM can have some peculiarities but SPM developers try to provide compatibility fixes in the updates.
 
-=== "Windows"
+## Installation
 
-    ## Installation
+=== "Windows"
 
     1. Download `spm12.zip` from the [SPM website](https://www.fil.ion.ucl.ac.uk/spm/software/download/).
-    2. Unzip spm12.zip in a folder of your choice, such as `C:\Users\login\Documents\MATLAB\spm12`.
-    3. Start MATLAB and add SPM into your path, either using:
+
+    2. Unzip `spm12.zip` in a folder of your choice, such as `C:\Users\login\Documents\MATLAB\spm12`.
+
+    3. Start MATLAB and add SPM to your path, either using:
 
         `Home` :material-arrow-right-bold: `Set Path` :material-arrow-right-bold: `Add Folder...`: select the directory containing your SPM installation then click on `Save` and `Close`.
 
         or type the following at the MATLAB prompt:
 
         ```matlab
         addpath('C:\Users\login\Documents\MATLAB\spm12')
+        savepath % if you want to save the current MATLAB path
         ```
 
-    !!! danger
-        If using the graphical interface, make sure to use the `Add Folder...` button and not `Add with Subfolders...`. SPM will automatically add the appropriate subfolders to the MATLAB path.
-
-    You can then launch SPM by typing `spm` at the MATLAB prompt.
-
-    ## Update
-
-    If you have just downloaded the `spm12.zip` archive, it already contains the latest set of updates. To update SPM when a new version is released:
+        If you are using MATLAB without its desktop, you can open the Set Path dialog box by typing `pathtool` at the MATLAB prompt.
 
-    1. [Download `spm12_updates_rxxxx.zip`](https://www.fil.ion.ucl.ac.uk/spm/software/download/).
-    2. Uncompress `spm12_updates_rxxxx.zip` on top of the folder containing your SPM installation so that newer files overwrite existing files.
-
-    Alternatively, you can use the `spm_update.m` function:
-
-    ```
-    spm_update
-    ```
-
-    If a new version is available, it can be applied to your local installation by typing:
-
-    ```
-    spm_update update
-    ```
-
-=== "Mac"
-    ## Installation
+    !!! danger
+        If using the graphical interface, make sure to use the `Add Folder...` button and not `Add with Subfolders...`. SPM will automatically add the appropriate subfolders to the MATLAB path at runtime.
 
-    Mac Intel with 64bit MATLAB is a supported SPM platform. Precompiled MEX files (`*.mexmaci64`) are included in the SPM distribution.
+=== "macOS"
 
-    1. [Download `spm12.zip`](https://www.fil.ion.ucl.ac.uk/spm/software/download/) in your home directory.
+    1. [Download  `spm12.zip` from the [SPM website](https://www.fil.ion.ucl.ac.uk/spm/software/download/) in your home directory.
 
-    2. Uncompress the archive by typing the following in a terminal:
-        ```
-        cd /Users/login
+    2. Uncompress the archive by typing the following in a Terminal:
+        ```bash
+        cd /Users/<login>
         unzip spm12.zip
         ```
 
     3. Start MATLAB and add SPM to your path, either using: 
         `File` :material-arrow-right-bold: `Set Path` :material-arrow-right-bold: `Add Folder...` 
         
-        or typing:
+        or typing the following at the MATLAB prompt:
 
-        ```
+        ```matlab
         addpath /Users/login/spm12
-        savepath
+        savepath % if you want to save the current MATLAB path
         ```
-        
-        in MATLAB's workspace. 
 
     ??? failure "Troubleshooting"
         **macOS Catalina**
@@ -83,7 +62,7 @@
         
         Open a terminal, `cd` to the SPM directory and type:
         
-        ```
+        ```bash
         find . -name "*.mexmaci64" -exec xattr -d com.apple.quarantine {} \;
         ```
         
@@ -99,7 +78,7 @@
         
         Open a terminal, and type the following whilst replacing `SPM_PATH` with the path of your spm installation:
 
-        ```
+        ```bash
         sudo xattr -r -d com.apple.quarantine SPM_PATH
         sudo find SPM_PATH -name "*.mexmaci64" -exec spctl --add {} \;
         ```
@@ -112,35 +91,33 @@
 
         If you get an error message such as:
 
-        ```
+        ```bash
         mex -O -c spm_vol_utils.c -DSPM_UNSIGNED_CHAR 
-        mex: unrecognized option `-O'
-        mex: unrecognized option `-c'
+        mex: unrecognized option '-O'
+        mex: unrecognized option '-c'
         This is pdfTeX, Version 3.1415926-2.3-1.40.12 (TeX Live 2011)
         restricted \write18 enabled.
         entering extended mode
         (./spm_vol_utils.c
         This is MeX  Version 1.05  18 XII 1993  (B. Jackowski & M. Ry\'cko)
-        ! You can't use `macro parameter character #' in vertical mode.
+        ! You can't use 'macro parameter character #' in vertical mode.
         ```
         
         This is due to a conflict between MATLAB mex and a LaTeX command with the same name. Edit `src/Makefile.var` and mention the full path when referring to MEXBIN.
         
-        ```
+        ```bash
         MEXBIN = /Applications/MATLAB_R2012a.app/bin/mex
         ```
         
         or change PATH accordingly. 
 
 === "Linux"
 
-    ## Installation
-
-    1. [Download `spm12.zip`](https://www.fil.ion.ucl.ac.uk/spm/software/download/) in your home directory.
+    1. Download `spm12.zip` from the [SPM website](https://www.fil.ion.ucl.ac.uk/spm/software/download/) in your home directory.
 
     2. Uncompress the archive by typing the following in a terminal:
 
-        ```
+        ```bash
         cd /home/login
         unzip spm12.zip
         ```
@@ -149,10 +126,32 @@
 
         `File` :material-arrow-right-bold: `Set Path` :material-arrow-right-bold: `Add Folder...` 
         
-        or typing:
+        or typing the following at the MATLAB prompt:
 
-        ```
+        ```matlab
         addpath /home/login/spm12
+        savepath % if you want to save the current MATLAB path
         ```
 
-        in MATLAB's workspace.
+![](../../../assets/figures/matlab_setpath.png)
+
+You can then launch SPM by typing `spm` at the MATLAB prompt.
+
+## Update
+
+If you have just downloaded the `spm12.zip` archive, it already contains the latest set of updates. To update SPM when a new version is released:
+
+1. [Download `spm12_updates_rxxxx.zip`](https://www.fil.ion.ucl.ac.uk/spm/download/spm12_updates/).
+2. Uncompress `spm12_updates_rxxxx.zip` on top of the folder containing your SPM installation so that newer files overwrite existing files.
+
+Alternatively, you can use the `spm_update.m` function:
+
+```matlab
+spm_update
+```
+
+If a new version is available, it can be applied to your local installation by typing:
+
+```matlab
+spm_update update
+```