From b91fdcd4d4d8aef2e0e2d2b66525f3f88effb308 Mon Sep 17 00:00:00 2001 From: korbinian90 Date: Fri, 3 Jan 2025 13:46:12 +0100 Subject: [PATCH 1/5] update the installation instructions for the new release --- docs/installation/index.md | 95 +++++++++----------------------------- 1 file changed, 23 insertions(+), 72 deletions(-) diff --git a/docs/installation/index.md b/docs/installation/index.md index 020e654..e23e212 100644 --- a/docs/installation/index.md +++ b/docs/installation/index.md @@ -1,7 +1,7 @@ # 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). + The SPM software is a collection of [MATLAB](https://www.mathworks.com/products/matlab.html) functions and thus requires the MATLAB (or GNU Octave) 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. @@ -9,9 +9,9 @@ === "Windows" - 1. Download `spm12.zip` from the [SPM website](https://www.fil.ion.ucl.ac.uk/spm/software/download/). + 1. Download the spm ZIP file (not standalone) from the newest [GitHub release](https://github.com/spm/spm/releases/latest/). - 2. Unzip `spm12.zip` in a folder of your choice, such as `C:\Users\login\Documents\MATLAB\spm12`. + 2. Unzip `spm_.zip` in a folder of your choice, such as `C:\Users\login\Documents\MATLAB\spm`. 3. Start MATLAB and add SPM to your path, either using: @@ -20,73 +20,33 @@ or type the following at the MATLAB prompt: ```matlab - addpath('C:\Users\\Documents\MATLAB\spm12') + addpath('C:\Users\\Documents\MATLAB\spm') savepath % if you want to save the current MATLAB path ``` - If you are using MATLAB without its desktop, you can open the Set Path dialog box by typing `pathtool` at the MATLAB prompt. - === "macOS" - 1. Download `spm12.zip` from the [SPM website](https://www.fil.ion.ucl.ac.uk/spm/software/download/) in your home directory. - - If using Apple Silicon and Matlab 2023b or higher, download the [development version of SPM](https://github.com/spm/spm) or the [maintenance branch of SPM12](https://github.com/spm/spm12/tree/maint) from GitHub. + 1. Download the spm ZIP file (not standalone) from the newest [GitHub release](https://github.com/spm/spm/releases/latest/) in your home directory. - 2. Uncompress the archive by typing the following in a Terminal: + 2. Uncompress the archive by typing the following in a terminal: + ```bash cd /Users/ - unzip spm12.zip + unzip spm_.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...` + + `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 typing the following at the MATLAB prompt: ```matlab - addpath /Users//spm12 + addpath /Users//spm savepath % if you want to save the current MATLAB path ``` - ??? info "Using Apple Silicon with Matlab 2023b (onwards)" - - If, after installation, you get an error indicating that the MEX files for MACA64 are **missing**: - ``` - Error using spm_check_installation>check_basic - SPM uses a number of MEX files, which are compiled functions. - These need to be compiled for the various platforms on which SPM - is run. It seems that the compiled files for your computer platform - are missing or not compatible. See - https://en.wikibooks.org/wiki/SPM/Installation_on_64bit_Mac_OS_(Intel) - for information about how to compile MEX files for MACA64 - in MATLAB 23.2.0.2365128 (R2023b). - ``` - This is because you are running [native Apple silicon MATLAB (R2023b onwards)](https://uk.mathworks.com/support/requirements/apple-silicon.html) and the MEX files are not available for that platform in SPM12. Instead download and install the [development version of SPM](https://github.com/spm/spm) or the [maintenance branch of SPM12](https://github.com/spm/spm12/tree/maint) where the `*.mexmaca64` MEX files have been compiled. - - Then complete the steps detailed below if you receive a MEX file **validation error**, such as: - - ``` - "*.mexmaca64" cannot be opened because the developer cannot be verified. - macOS cannot verify that this app is free from malware - ``` - or: - ``` - Code signature not valid for use in process using Library Validation: library load disallowed by system policy - ``` - Open a Terminal, `cd` to the SPM directory and type: - - ``` - find . -name "*.mexmaca64" -exec xattr -d com.apple.quarantine {} \; - ``` - - If it doesn't work, please try this equivalent alternative, replacing `SPM_PATH` with the path of your SPM installation: - - ``` - sudo xattr -r -d com.apple.quarantine SPM_PATH - sudo find SPM_PATH -name "*.mexmaca64" -exec spctl --add {} \; - ``` - - ??? info "Using any other Mac and Matlab version combination" + ??? info "MEX file validation issues" If you have **validation issues** with MEX files with one of these errors: ``` @@ -110,46 +70,36 @@ sudo find SPM_PATH -name "*.mexmaci64" -exec spctl --add {} \; ``` - - === "Linux" - 1. Download `spm12.zip` from the [SPM website](https://www.fil.ion.ucl.ac.uk/spm/software/download/) in your home directory. + 1. Download the spm ZIP file (not standalone) from the newest [GitHub release](https://github.com/spm/spm/releases/latest/) in your home directory. 2. Uncompress the archive by typing the following in a terminal: ```bash cd /home/ - unzip spm12.zip + unzip spm_.zip ``` - 3. Start MATLAB and add SPM into your path, either using: + 3. Start MATLAB and add SPM to your path, either using: - `File` :material-arrow-right-bold: `Set Path` :material-arrow-right-bold: `Add Folder...` + `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 typing the following at the MATLAB prompt: ```matlab - addpath /home//spm12 + addpath /home//spm savepath % if you want to save the current MATLAB path ``` - !!! failure "`Crash at startup`" + ??? failure "`Crash at startup`" The following concerns a situation where MATLAB generates a segmentation fault when opening the SPM interface with errors like: ``` BadWindow (invalid Window parameter) - ``` - ``` serial 20133 error_code 3 request_code 20 minor_code 0 - ``` - ``` Pango-CRITICAL **: pango_font_description_from_string: assertion 'str != NULL' failed - ``` - ``` GLib-CRITICAL **: g_once_init_leave: assertion 'result != 0' failed - ``` - ``` GLib-GObject-CRITICAL **: g_type_register_dynamic: assertion 'parent_type > 0' failed ``` @@ -160,20 +110,21 @@ setenv('SPM_HTML_BROWSER','0') ``` +If you are using MATLAB without its desktop, you can open the Set Path dialog box by typing `pathtool` at the MATLAB prompt. !!! 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. -![](../assets/figures/matlab_setpath.png) +![Matlab Setpath Window](../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: +If you have just downloaded the `spm_.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. +1. Download the latest [`spm_.zip`](https://github.com/spm/spm/releases/latest/). +2. Replace your current SPM installation with the newer version so that newer files overwrite existing files. Alternatively, you can use the `spm_update.m` function: From 76079e7df52f7c0e34672f012171503325173042 Mon Sep 17 00:00:00 2001 From: korbinian90 Date: Fri, 3 Jan 2025 13:46:12 +0100 Subject: [PATCH 2/5] Update the standalone installation instructions --- docs/installation/standalone.md | 118 ++++++++++---------------------- 1 file changed, 36 insertions(+), 82 deletions(-) diff --git a/docs/installation/standalone.md b/docs/installation/standalone.md index 3e155ac..26fac8a 100644 --- a/docs/installation/standalone.md +++ b/docs/installation/standalone.md @@ -5,112 +5,64 @@ !!! note "What is Standalone SPM?" A standalone SPM is a version of SPM that has been compiled using the [MATLAB Compiler](https://www.mathworks.com/products/compiler.html) so that it does not require the availability of a MATLAB licence (you might want to check first [here](https://www.mathworks.com/academia/tah-support-program/eligibility.html) whether you have access to a MATLAB campus license). -A standalone version of SPM is [available for download from the SPM -website](https://www.fil.ion.ucl.ac.uk/spm/software/download/) (select -`SPM Standalone` as `SPM Version`). +- The **MATLAB Runtime**: it contains a set of libraries that enables the execution of compiled MATLAB applications. The version has to match the one that was used to compile SPM. +- The **SPM Standalone** itself containing the compiled SPM, as a ZIP file. ## Installation -Following your request, you will be given instructions to download the -following components: +1. Download the spm standalone ZIP file from the newest [GitHub release](https://github.com/spm/spm/releases/latest/) for your OS -- The **MATLAB Runtime**: it contains a set of libraries that enables - the execution of compiled MATLAB applications. You need to install the - one that corresponds to your platform (Windows, Linux or macOS) and to - the version that was used to compile SPM. The default SPM standalone - requires the MATLAB Compiler Runtime (MCR) 7.13 of MATLAB R2010a - available from the `MCR` folder from the link you will have been - given. Otherwise more recent MATLAB Runtimes are downloadable from - [here](https://www.mathworks.com/products/compiler/matlab-runtime.html). -- The **SPM Standalone** itself containing the compiled SPM, as a ZIP - file. +2. Unzip `spm_standalone__.zip` in a folder of your choice, such as `C:\Users\login\Documents\MATLAB\spm_standalone` -### Installation of the MATLAB Runtime +3. Install the MATLAB Runtime via the provided installer in the ZIP file under `runtime_installer`. It will install the minimal MATLAB Runtime that is required to run SPM (~2.5GB). This can be optionally performed without a GUI via the command line with e.g.: -You need to do this operation only once, even if you use several -versions of standalone SPM. - -Run the MCRInstaller executable you downloaded and follow the -instructions. - -Windows installation requires to have administrative privileges and you -might also have to install the Visual C++ Redistributable Package -(`vcredist_*.exe`), that can be found in the same folder as the -MCRInstaller. We also recommend you restart Windows at this point. - -If you run into problems, or want to learn more, see: - -- - -To install the MCR on Linux from the command line, type: - -``` -chmod 755 MCRInstaller.bin -./MCRInstaller.bin -P bean421.installLocation="MCR" -silent -``` - -### Installation of the SPM Standalone - -- Unzip the `spm12_rxxx.zip` archive containing the SPM Standalone in an - appropriate folder. It contains a number of small executables for each - supported platform and a large `spm12.ctf` file containing the - compiled version of SPM12 itself. + ```bash + chmod 755 runtime_installer/Runtime_R2024b_for_spm_standalone_24.11.install + runtime_installer/Runtime_R2024b_for_spm_standalone_24.11.install -agreeToLicense yes + ``` -- The first time the standalone application will be executed, the CTF - file will be unpacked in a subfolder so if you installed the CTF in a - folder that requires administrative permission for write access, you - should execute the application once under those privileges -- see - below. +### First Run -- On `macOS`, you also need to unzip the `spm12_maci64.zip` archive. +- The first time the standalone application will be executed, the CTF file will be unpacked in a subfolder so if you installed the CTF in a folder that requires administrative permission for write access, you should execute the application once under those privileges -- see below. ## Usage To start SPM graphical user interface: -- on Windows: double-click on `spm12_wxx.exe` -- on Linux, type +=== "Windows" -``` -./run_spm12.sh /usr/local/MATLAB/MATLAB_Compiler_Runtime/v713/ -``` + Double-click on `spmxx.exe` -where the argument is the path to your MCR installation. +=== "Linux/macOS" -- on macOS, type + Type in bash: -``` -./run_spm12.sh /Applications/MATLAB/MATLAB_Compiler_Runtime/v713/ -``` + ```bash + ./run_spmxx.sh /usr/local/MATLAB/MATLAB_Runtime// + ``` -where the argument is the path to your MCR installation. + where the argument is the path to your Matlab Runtime installation. On macOS this might be under `/Applications/MATLAB/MATLAB_Runtime//` -The first execution should take longer to start as the CTF file will be -unpacked. When installing SPM system-wide, you should do the first -unpacker execution as root, i.e. + The first execution should take longer to start as the CTF file will be unpacked. When installing SPM system-wide, you should do the first unpacker execution as root, i.e. -``` -./run_spm12.sh /usr/local/MATLAB/MATLAB_Compiler_Runtime/v713/ quit -``` + ```bash + ./run_spmxx.sh /usr/local/MATLAB/MATLAB_Runtime// quit + ``` -On Linux/Mac, you can edit the Shell script `run_spm12.sh` to hardcode the -location of the MCR installation, thus removing the need of providing it -on the command line. + For more conveniently running SPM, you can create an alias in `~/.bashrc` or edit the Shell script `run_spmxx.sh` to hardcode the location of the MCR installation, thus removing the need of providing it on the command line. -The other arguments that can be used are the modality (as in `spm -fmri`) or the keyword `batch` to start directly the batch system -window, e.g.: -``` -./run_spm12.sh /Applications/MATLAB/MATLAB_Compiler_Runtime/v713/ fmri -./run_spm12.sh /Applications/MATLAB/MATLAB_Compiler_Runtime/v713/ batch +When run via the command line, other arguments that can be used are the modality (as in `spm fmri`) or the keyword `batch` to start directly the batch system window, e.g.: + +```bash +./run_spmxx.sh /Applications/MATLAB/MATLAB_Runtime// fmri +./run_spmxx.sh /Applications/MATLAB/MATLAB_Runtime// batch ``` -Furthermore, `batch` followed by a batch filename (`*.mat` or -`*.m`) will start SPM, execute the batch and quit: +Furthermore, `batch` followed by a batch filename (`*.mat` or `*.m`) will start SPM, execute the batch and quit: -``` -./run_spm12.sh /Applications/MATLAB/MATLAB_Compiler_Runtime/v713/ batch mybatch.mat +```bash +./run_spmxx.sh /Applications/MATLAB/MATLAB_Compiler_Runtime// batch mybatch.mat ``` ## Troubleshooting @@ -125,7 +77,7 @@ Furthermore, `batch` followed by a batch filename (`*.mat` or !!! failure "What to do if I get the error `readlink: illegal option -- f` on a Mac?" - Change the last line of `run_spm12.sh` so that it reads: + Change the last line of `run_spmxx.sh` so that it reads: ``` dirname $0`/${MACAPP}spm12_${MWE_ARCH} $* ``` @@ -169,7 +121,7 @@ Furthermore, `batch` followed by a batch filename (`*.mat` or !!! failure "Why does standalone SPM crash when starting the GUI?" - This is discussed [here](../development/compilation/linux.md) and can be fixed by adding the following in `run_spm12.sh`: + This is discussed [here](../development/compilation/linux.md) and can be fixed by adding the following in `run_spmxx.sh`: ``` SPM_HTML_BROWSER=0 ``` @@ -190,6 +142,8 @@ Furthermore, `batch` followed by a batch filename (`*.mat` or Open MATLAB, at the command line, addpath the SPM directory (if not done already), run `spm_jobman('initcfg')`, then run `spm_make_standalone`. The compilation process takes several minutes. By default, the newly compiled standalone SPM will be saved in a `standalone` directory. + The [GitHub release action](https://github.com/spm/spm/blob/main/.github/workflows/release.yml) might also be an interesting reference. + !!! question "How to create a shortcut on your Desktop for a faster launch?" On Linux, for achieving menu entries, you can install an appropriate `.desktop` file and an icon file for SPM. For example, save the following as `spm12.desktop` (modify according to your needs/MCR version): From bc007a936365c6fbfa4021f7b399874f74b14033 Mon Sep 17 00:00:00 2001 From: korbinian90 Date: Fri, 3 Jan 2025 13:46:12 +0100 Subject: [PATCH 3/5] update container instructions --- docs/installation/containers.md | 53 +++++++++++---------------------- 1 file changed, 18 insertions(+), 35 deletions(-) diff --git a/docs/installation/containers.md b/docs/installation/containers.md index c61a497..eeacd0a 100644 --- a/docs/installation/containers.md +++ b/docs/installation/containers.md @@ -1,43 +1,28 @@ # SPM and Containers -## Docker +??? info "What is Docker?" + [Docker](https://www.docker.com/) is a container technology, performing operating-system-level virtualisation. -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/) +??? info "What is 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/) +Official SPM [`Dockerfile`](https://github.com/spm/spm-docker) (using the [Standalone SPM](standalone.md)) with the docker images hosted on the [GitHub container registry](https://github.com/spm/spm-docker/pkgs/container/spm-docker) For example, to start SPM with its graphical user interface: -``` + +```bash xhost +local:docker -docker run -ti --rm -e DISPLAY=$DISPLAY -v /tmp:/tmp -v /tmp/.X11-unix:/tmp/.X11-unix spmcentral/spm fmri +docker run -ti --rm -e DISPLAY=$DISPLAY -v /tmp:/tmp -v /tmp/.X11-unix:/tmp/.X11-unix ghcr.io/spm/spm-docker:docker-matlab-latest fmri ``` -If the container\'s root filesystem is mounted as read only -(*\--read-only* flag), you need to bind mount an extra volume: -``` +If the container\'s root filesystem is mounted as read only (*\--read-only* flag), you need to bind mount an extra volume: + +```bash -v /tmp/.matlab:/root/.matlab ``` @@ -46,14 +31,12 @@ If the container\'s root filesystem is mounted as read only [SingularityCE User Guide](https://docs.sylabs.io/guides/latest/user-guide/) -``` -sudo singularity build spm12.sif spm12-octave.def -singularity exec spm12.sif -./spm12.sif --help +```bash +singularity pull oras://ghcr.io/spm/spm-docker:singularity-matlab-latest +singularity run spm-docker_singularity-matlab-latest.sif --version ``` -([how to install singularity on -Ubuntu](https://github.com/hpcng/singularity/issues/5390#issuecomment-899111181)) +([how to install singularity on Ubuntu](https://github.com/hpcng/singularity/issues/5390#issuecomment-899111181)) ## See also From 5da12a78840f0d440be0e42e874da47aa0e23b81 Mon Sep 17 00:00:00 2001 From: korbinian90 Date: Fri, 3 Jan 2025 13:46:12 +0100 Subject: [PATCH 4/5] fix typos --- docs/development/git.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/development/git.md b/docs/development/git.md index 499cf22..048b853 100644 --- a/docs/development/git.md +++ b/docs/development/git.md @@ -4,7 +4,7 @@ We use the [Git](https://git-scm.com/) version control system for the developmen We provide here instructions to interact with the SPM repository using the [GitHub Desktop](https://desktop.github.com/). This mainly concerns Windows developers -- we also mention the command line equivalents when relevant. For Linux users, [additional steps](https://www.fil.ion.ucl.ac.uk/spm/docs/development/ssh_authentication/) are required to enable SSH authentication. -## Git Installation +## Git Installation First, please install the GitHub Desktop: @@ -27,7 +27,6 @@ During installation, you can accept most defaults. There are three options to be ![line ending conversions](../assets/figures/git_windows_eol.png){ width="45%" } ![default behavior of `git pull`](../assets/figures/git_windows_rebase.png){ width="45%" } - ## Git Configuration ### Username and commit email address @@ -81,7 +80,7 @@ To apply this setting from GitHub Desktop, you need to open the command prompt b ### Git autostash -Pull with rebase will fail if you have unstaged changes. One way around this if you're not ready to commit your changes is to stash the changed before doing a pull (`git stash`) and then restore then (`git stash pop`) afterwards. This can be automated by using the `autostash` option of `git rebase`. +Pull with rebase will fail if you have unstaged changes. One way around this if you're not ready to commit your changes is to stash the changes before doing a pull (`git stash`) and then restore them (`git stash pop`) afterwards. This can be automated by using the `autostash` option of `git rebase`. ``` git config --global rebase.autoStash true From 3b794dad4d62b25d6ea45552da2190c01549dc56 Mon Sep 17 00:00:00 2001 From: korbinian90 Date: Fri, 3 Jan 2025 15:01:39 +0100 Subject: [PATCH 5/5] don't specify python version for spell checking --- .github/workflows/spelling.yml | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/.github/workflows/spelling.yml b/.github/workflows/spelling.yml index 3a82479..218b1d5 100644 --- a/.github/workflows/spelling.yml +++ b/.github/workflows/spelling.yml @@ -11,12 +11,9 @@ jobs: spell: runs-on: ubuntu-latest steps: - - uses: actions/checkout@v3 + - uses: actions/checkout@v4 - name: Setup Python - uses: actions/setup-python@v1 - with: - python-version: '3.7' - architecture: 'x64' + uses: actions/setup-python@v5 - name: Install dependencies run: | python3 -m pip install --upgrade pip setuptools