Standalone installation on Linux

Wiki
,
1

In some cases, users need to install MRtrix3 on systems running older distributions, over which they have little or no control, for example centrally-managed HPC clusters. In such cases, there genuinely is no way to install the dependencies required to compile and run MRtrix3. There are several ways to address this problem: static executables, and the standalone packager. With both approaches, you can compile MRtrix3 on a modern distro (within a virtual machine for example), package it up, and install it on any Linux system without worrying about dependencies.

Alternatively, you can also install all the dependencies from source – see this post for specific instructions.

Note: this is not the recommended way to install MRtrix3, and may not work for your system. These instructions are provided on a best-effort basis, as a convenience for users who genuinely have no alternative.

Limitations

  • OpenGL support: these approaches cannot magically make your system run mrview if it doesn’t already support OpenGL 3.3 and above. This is a hardware driver issue, and can only be addressed by upgrading the drivers for your system – something that may or may not be possible.

  • GUI support: while these approaches may include all the X11 dependencies that are needed to launch the program (if not disabled with -nogui), it is likely that these will then dynamically attempt to load further libraries that reside on your system. Unfortunately, this can introduce binary compatibility issues, and cause the GUI components to abort. This might happen even if your system does have OpenGL 3.3 support. There is unfortunately no simple solution to this.

  • Installation on remote systems: bear in mind that running the GUI components over a remote X11 connection is not possible, since the GLX protocol does not support OpenGL 3 and above (see the relevant Wiki entry of the MRtrix3 community forum for details). You may be able to use an OpenGL-capable VNC connection, but if that is not possible, there is little point in installing the GUI components on the remote server. The recommendation would be to configure with the -nogui option to skip the GUI components. You should also be able to access your data over the network (e.g. using SAMBA or SSHFS), in which case you would be able to display the images by running mrview locally and loading the images over the shared network drives.

Static build

The simplest approach to this problem is to build so-called static executables, which have no run-time dependencies. This can be accomplished by generating a static configuration before building the software, as follows.

First, obtain the code and extract or clone it on a modern distribution (Arch, Ubuntu 16.04, Mint 18, …, potentially with a virtual machine if required). Then, from the main MRtrix3 folder::

./build clean
git pull
./configure -static [-nogui]
./build

Note that this requires the availability of static versions of the required libraries. This is generally not a problem, most distributions will provide those by default, with the exception of Qt. If you require a static build of MRView, you will most likely need to build a static version of Qt beforehand. Use the -nogui option to skip installation of GUI
components, which rely on Qt.

You can then deploy the software onto target systems, as described in the main documentation.

Standalone packager

In the rare cases where the static build procedure above doesn’t work for you, MRtrix3 now includes the package_mrtrix script, which is designed to package an existing and fully-functional installation from one system, so that it can be installed as a self-contained standalone package on another system. What this means is that you can now compile MRtrix3 on a modern distro (within a virtual machine for example), package it up, and install it on any Linux system without worrying about dependencies.

The package_mrtrix script is included in the top-level folder of the MRtrix3 package (if you don’t have it, use git pull to update). In essence, all it does is collate all the dynamic libraries necessary for runtime operation into a single folder, which you can then copy over and extract onto target systems. For a truly standalone installation, you need to add the -standalone option, which will also include any system libraries required for runtime operation from your current system, making them available on any target system.

To use this approach, first obtain the code and extract or clone it on a modern distribution (Arch, Ubuntu 14.04, Mint 17, …, potentially with a virtual machine if required). Then, from the main MRtrix3 folder:

./build clean
git pull
./configure [-nogui]
./build
./package_mrtrix -standalone

Then copy the resulting _package/mrtrix3 folder to the desired location on the target system (maybe your own home folder). To make the MRtrix3 command available on the command-line, the bin/ folder needs to be added to your PATH (note this assumes that you’re running the BASH shell):

export PATH="$(pwd)/bin:$PATH"

Note that the above command will only add MRtrix3 to the PATH for the current session. You would need to add the equivalent line to your users’ startup scripts, using whichever mechanism is appropriate for your system.