Update MEX compilation section

Author: gllmflndn

docs/development/compilation/index.md

@@ -1,13 +1,21 @@
 # Compilation of SPM MEX files
 
-Pre-compiled MEX files are provided with the SPM distribution so you shouldn't need to compile the MEX files yourself. We still provide here platform-specific instructions to compile all the MEX files for your machine.
+!!! info "What are MEX files?"
+
+    MEX files are MATLAB functions implemented in C/C++. Contrary to functions implemented in pure MATLAB, they need to be compiled in order for the MATLAB interpreter to be able to call them. Once compiled, they correspond to platform-specific files `*.mex*`.
+
+## Instructions
+
+Pre-compiled MEX files are provided with the SPM distribution so you shouldn't need to compile the MEX files yourself. We still provide here platform-specific instructions to compile all the MEX files for your machine if the shipped ones were incompatible with your OS version.
 
 * [Windows](windows.md)
 * [Linux](linux.md)
 * [macOS](macos.md)
 
 ## Troubleshooting
 
+Platform-specific throubleshooting is available with the links above. We list here error messages and solutions that are common across platforms. 
+
 !!! failure "`bad image handle dimensions` error"
 
     The error "`bad image handle dimensions`" when trying to display an image is an indication that the MEX files are not compatible with your platform and should be recompiled.

docs/development/compilation/linux.md

@@ -1,5 +1,9 @@
 # Compilation of SPM on Linux
 
+This page describes the compilation of SPM MEX files on Linux. It requires the installation of a C/C++ compiler and related tools (e.g. `make`). This can be done on Debian/Ubuntu by installing the `build-essential` package (`sudo apt install build-essential`).
+
+## Instructions
+
 In a Terminal, ==from the `src` folder== of your SPM installation, type:
 
 ```
@@ -9,13 +13,15 @@ make external-distclean
 make external && make external-install
 ```
 
+This will generate `*.mexa64` MEX files.
+
 ## Troubleshooting
 
 !!! failure "`cannot find -lstdc++` error"
 
-    If you get the error message "cannot find -lstdc++", try installing the build-essential package using your package manager (i.e. sudo apt-get install build-essential on Ubuntu), or the specific libstdc++5 package (replacing 5 with the version of your system) with sudo apt-get install libstdc++5.
+    If you get the error message "`cannot find -lstdc++`", try installing the `build-essential` package using your package manager (i.e. `sudo apt install build-essential` on Ubuntu), or the specific `libstdc++5` package (replacing 5 with the version of your system) with `sudo apt-get install libstdc++5`.
 
-    If, after the install of libstdc++5, the lstdc++ error persists, just add a symbolic link with:
+    If, after the install of `libstdc++5`, the `lstdc++` error persists, just add a symbolic link with:
 
     ```
     sudo ln -s /usr/lib64/libstdc++.so.6 /usr/lib64/libstdc++.so 
@@ -25,28 +31,21 @@ make external && make external-install
 
     For old versions of Ubuntu and MATLAB, have a look at [these instructions](https://web.archive.org/web/20160307232613/http://www.lukedodd.com/compiling-gcc-4-3-4-under-ubuntu-11-10-for-matlab/).
 
-!!! failure "Other problems with lstdc++"
-
-    If you get the above error and cannot install libstdc++ (e.g. you do not have root/admin access), or if you get other problems such as "... version `GCC_4.2.0' not found (required by /usr/lib64/libstdc++.so.6", then another option is to edit your mexopts.sh config file and delete or disable the -lstdc++ compiler flags, for example simply use find-and-replace to delete all instances of -lstdc++. SPM will compile properly without this.
+!!! failure "Other problems with `lstdc++`"
 
-    It's best to edit a local copy of mexopts.sh (the original is found in the bin directory with your matlab and mex executables). If you run `mex -setup` it will interactively create a copy for you, under `~/.matlab/RELEASE`, for example:
+    If you get the above error and cannot install `libstdc++` (e.g. you do not have root/admin access), or if you get other problems such as "`... version `GCC_4.2.0' not found (required by /usr/lib64/libstdc++.so.6`", then another option is to edit your `mexopts.sh` config file and delete or disable the `-lstdc++` compiler flags, for example simply use find-and-replace to delete all instances of `-lstdc++`. SPM will compile properly without this.
 
-    ```
-    ~/.matlab/R14SP3/mexopts.sh
-    ~/.matlab/R2008b/mexopts.sh
-    ```
+    It's best to edit a local copy of `mexopts.sh` (the original is found in the `bin` directory with the `matlab` and `mex` executables). If you run `mex -setup` it will interactively create a copy for you, under `~/.matlab/RELEASE`, for example:
 
-    or similar, and you may then further edit that copy if required. If you match the release, mex will find your copy of `mexopts.sh`. Note that MATLAB 
-    
     ```
-    version
+    ~/.matlab/R2020a/mexopts.sh
     ```
 
-    should show you the release, but with parentheses around it, e.g. `"(R14SP3)"`.
+    or similar, and you may then further edit that copy if required. If you match the release, `mex` will find your copy of `mexopts.sh`.
 
 !!! failure "`mex: command not found` error"
 
-    If you get the error "mex: command not found" check that mex is in your path. Either add the MATLAB binary directory (usually `/usr/local/matlab/bin`) to your path or create a link to mex somewhere already in the path (usually `/usr/local/bin)`.
+    If you get the error "`mex: command not found`" check that `mex` is in your path. Either add the MATLAB binary directory (usually `/usr/local/matlab/bin`) to your path or create a link to `mex` somewhere already in the path (usually `/usr/local/bin)`.
 
     Adding the path:
     ```
@@ -59,10 +58,10 @@ make external && make external-install
     ln -s /usr/local/matlab/bin/mex
     ```
 
-    Another solution is to edit the Makefile (`spm8/src/Makefile.var` for SPM8 or `spm5/src/Makefile` for SPM5) and mention the full path when referring to MEXBIN:
+    Another solution is to provide the full path to the `mex` executable in an environment variable called `MEXBIN`. It will be used by the `Makefile` instead of the default one.
 
     ```
-    MEXBIN = /usr/local/matlab/mex
+    MEXBIN=/usr/local/matlab/bin/mex make
     ```
 
 !!! failure "`This is pdfTeX, Version ... (TeX Live 2011)` error"
@@ -74,28 +73,30 @@ make external && make external-install
     This is pdfTeX, Version ... (TeX Live 2011)
     ```
 
-    This is due to a conflict between MATLAB mex and a LaTeX command (from the texlive package) with the same name. Change `PATH` or `MEXBIN` as described in the previous solution.
+    This is due to a conflict between MATLAB `mex` and a LaTeX command (from the texlive package) with the same name. Change `PATH` or `MEXBIN` as described in the previous solution to make sure that the MATLAB `mex` executable is called first.
 
 !!! failure "Missing files"
 
     If you get build errors such as "`math.h` does not exist" when trying to execute the command `make && make install`, then you probably need to install the `build-essentials` package. 
 
-    At the command line type:
+    At the command line in a Terminal, type:
     ```
     sudo apt install build-essential
     ```
 
+    or similar command to install a C/C++ compilation environment if you are not using a Debian-based Linux distribution.
+
 !!! failure "`plugin needed to handle lto object` error"
 
-    Edit `spm12/src/Makefile.var` at the line defining `AR` so that it reads:
+    Edit `spm/src/Makefile.var` at the line defining `AR` so that it reads:
 
     ```
     AR           = gcc-ar rcs
     ```
 
 !!! failure "`Crash at startup`"
 
-    The following concerns a situation where MATLAB segfaults when opening the SPM interface with errors like:
+    The following concerns a situation where MATLAB generates a segmentation fault when opening the SPM interface with errors like:
     ```
     BadWindow (invalid Window parameter)
     ``` 

docs/development/compilation/macos.md

@@ -1,103 +1,101 @@
 # Compilation of SPM on macOS
 
+This page describes the compilation of SPM MEX files on macOS.
+
 !!! tip
-    If you are using macOS Catalina, Big Sur, Monterey or Ventura, check the [Troubleshooting section](#troubleshooting) first as you should not need to recompile the MEX files.
+    If you are using macOS Catalina, Big Sur, Monterey or Ventura and have apparent problems with the MEX files provided with SPM, check the [Troubleshooting section](#troubleshooting) first as it is very likely you do not need to recompile the MEX files.
 
-Should you want to compile SPM MEX files, you need to have Apple's
-development environment [Xcode](http://developer.apple.com/tools/xcode/)
-installed.
+To compile SPM MEX files, you need to have Apple's development environment [Xcode](http://developer.apple.com/tools/xcode/) installed.
 
-You also need to have the *mex* executable in your system path. To do
+You also need to have the `mex` executable in your system path. To do
 so, type the following in a Terminal:
 ```
-export PATH=/Applications/MATLAB_R2017a.app/bin:\$PATH
+export PATH=/Applications/MATLAB_R2017a.app/bin:$PATH
 ```
 with the appropriate path where MATLAB is installed
 
-Then, in a Terminal, from the *src* folder of your SPM12 installation,
+If you get errors such as `Bad : modifier in $ (/)`, this is because
+the instructions are given for a `bash` Terminal while you are using a
+`tcsh` Terminal. The equivalent commands are:
+```
+setenv PATH /Applications/MATLAB_R2017a.app/bin:${PATH}
+```
+
+## Instructions
+
+In a Terminal, from the *src* folder of your SPM installation,
 type:
 ```
-cd /Users/login/spm12/src
+cd /Users/login/spm/src
 make distclean
 make && make install
 make external-distclean
 make external && make external-install
 ```
 
-If you get errors such as `Bad : modifier in \$ (/)`, this is because
-the instructions are given for a bash` Terminal while you are using a
-`tcsh` Terminal. The equivalent commands are:
-```
-setenv PATH /Applications/MATLAB_R2017a.app/bin:\${PATH}
-```
-
-If you get errors such as `xcrun: error: SDK "macosx10.14.1" cannot be
-located` while compiling, execute the following:
-```
-sudo xcode-select --switch /Applications/Xcode.app/
-```
+This will generate `*.mexmaci64` or `*.mexmaca64` MEX files.
 
 ## Troubleshooting
 
-### macOS Catalina, Big Sur, Monterey, Ventura
-
-If you have issues with MEX files on macOS with one of these errors:
+!!! failure "macOS Catalina, Big Sur, Monterey, Ventura"
 
-```
-"*.mexmaci64" cannot be opened because the developer cannot be verified.
-macOS cannot verify that this app is free from malware
-```
-```
-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:
+    If you have issues with MEX files on macOS with one of these errors:
 
-```
-find . -name "*.mexmaci64" -exec xattr -d com.apple.quarantine {} \;
-```
+    ```
+    "*.mexmaci64" cannot be opened because the developer cannot be verified.
+    macOS cannot verify that this app is free from malware
+    ```
+    ```
+    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:
 
-If it doesn't work, please try this equivalent alternative, replacing
-`SPM_PATH` with the path of your SPM installation:
+    ```
+    find . -name "*.mexmaci64" -exec xattr -d com.apple.quarantine {} \;
+    ```
 
-```
-sudo xattr -r -d com.apple.quarantine SPM_PATH
-sudo find SPM_PATH -name "*.mexmaci64" -exec spctl --add {} \;
-```
-
-### Java Exception and abrupt exit on Mac OS X version 10.10 Yosemite
+    If it doesn't work, please try this equivalent alternative, replacing `SPM_PATH` with the path of your SPM installation:
 
-If you get MATLAB issues with Yosemite, see the following bug report for
-a patch:
+    ```
+    sudo xattr -r -d com.apple.quarantine SPM_PATH
+    sudo find SPM_PATH -name "*.mexmaci64" -exec spctl --add {} \;
+    ```
 
-[`http://www.mathworks.com/support/bugreports/1098655`](http://www.mathworks.com/support/bugreports/1098655)
+!!! failure "`xcrun: error: SDK "macosx10.14.1" cannot be located` error"
 
-### "`This is pdfTeX, Version ...`" error
+    If you get errors such as `xcrun: error: SDK "macosx10.14.1" cannot be located` while compiling, execute the following before compilation:
+    ```
+    sudo xcode-select --switch /Applications/Xcode.app/
+    ```
 
-If you get an error message such as:
+!!! failure "Java Exception and abrupt exit on Mac OS X version 10.10 Yosemite"
 
-```
-mex -O -c spm_vol_utils.c -DSPM_UNSIGNED_CHAR
-  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.
-```
+    If you get MATLAB issues with Yosemite, see the following bug report for a patch:
 
-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
+    [`http://www.mathworks.com/support/bugreports/1098655`](http://www.mathworks.com/support/bugreports/1098655)
 
-```
-MEXBIN = /Applications/MATLAB_R2012a.app/bin/mex
-```
+!!! failure "`This is pdfTeX, Version ...` error"
 
-or change PATH accordingly.
+    If you get an error message such as:
+    ```
+    mex -O -c spm_vol_utils.c -DSPM_UNSIGNED_CHAR
+      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.
+    ```
+    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
+    ```
+    MEXBIN = /Applications/MATLAB_R2012a.app/bin/mex
+    ```
+    or change PATH accordingly.
 
-### Slowdown when using graphical inputs
+!!! failure "Slowdown when using graphical inputs"
 
-This seems to happen when a window manager for macOS is installed ([Magnet](https://magnet.crowdcafe.com/) or [Tiles](https://freemacsoft.net/tiles/)), see also
-[this](https://www.mathworks.com/matlabcentral/answers/475682).
+    This seems to happen when a window manager for macOS is installed ([Magnet](https://magnet.crowdcafe.com/) or [Tiles](https://freemacsoft.net/tiles/)), see also [this](https://www.mathworks.com/matlabcentral/answers/475682).

docs/development/compilation/windows.md

@@ -1,7 +1,7 @@
 # Compilation of SPM on Windows
 
-This page describes the compilation of SPM12 MEX files on **Windows 10**
-with **MATLAB R2018b (9.5)** and **MSYS2 MinGW-w64 GCC**. It also provides instructions to compile SPM for the Octave package of MSYS2.
+This page describes the compilation of SPM MEX files on **Windows 10**
+with **MATLAB R2018b (9.5)** and **MSYS2 MinGW-w64 GCC**; identical or very similar instructions should work with newer versions of Windows, MATLAB and MSYS2 MinGW. It also provides instructions to compile SPM for the Octave package of MSYS2.
 
 !!! tip
     If you use other versions of MATLAB and/or compiler, make sure that they are compatible by checking the list of [supported compilers](https://www.mathworks.com/support/requirements/previous-releases.html) and adjust the MATLAB path accordingly in the commands below.
@@ -28,18 +28,20 @@ mex -setup
 % MEX configured to use 'MinGW64 Compiler (C)' for C language compilation.
 ```
 
-Do not worry if there is a warning:
+Do not worry if this warning is displayed:
 
 ```
 Warning: The MATLAB C and Fortran API has changed to support MATLAB
+	 variables with more than 2^32-1 elements. You will be required
+	 to update your code to utilize the new API.
 ```
 
 ## Compilation
 
-In MSYS2, move to the SPM12 source directory with
+In MSYS2, move to the SPM source directory (`./src/`) with
 
 ```
-cd  /c/Documents and Settings/`*`login`*`/Documents/MATLAB/spm12/src
+cd  /c/Documents and Settings/<login>/Documents/MATLAB/spm/src
 ```
 
 then set the PATH appropriately
@@ -59,6 +61,8 @@ make external-distclean
 make external && make external-install
 ```
 
+This will generate `*.mexw64` MEX files.
+
 ## Notes for compilation with MSYS2 for Octave
 
 Install
@@ -77,9 +81,11 @@ then start Octave with:
 and compile with:
 
 ```bash
-cd('/c/Documents and Settings/<login>/Documents/MATLAB/spm12/src');
+cd('/c/Documents and Settings/<login>/Documents/MATLAB/spm/src');
 system('make distclean PLATFORM=octave');
 system('make PLATFORM=octave && make install PLATFORM=octave');
 system('make external-distclean PLATFORM=octave');
 system('make external PLATFORM=octave && make external-install PLATFORM=octave');
 ```
+
+This will generate `*.mex` MEX files.

mkdocs.yml

@@ -128,6 +128,7 @@ nav:
     - 'Git':          'development/git.md'
     - 'Guidelines':   'development/guidelines.md'
     - 'Testing':      'development/testing.md'
+    - 'Compilation':  'development/compilation/index.md'
 
 markdown_extensions:
   - abbr