Building from source

Requirements

• CMake (>= 3.16)
• A compiler that supports C++17
• Qt >=5.9 (base and OpenGL components)
• Eigen 3
• FFTW
• Ninja (Optional)
• ccache or sccache (Optional)

NOTE: If your OS doesn't provide a recent enough version of CMake, you can install it using pip:

    $ pip install cmake

Then you can add CMake's installation directory to your PATH environment variable (you can check where installed CMake by pip show cmake). For example, on Ubuntu, you can add the following line to your ~/.bashrc:

    $ export PATH=~/.local/bin:$PATH

Build instructions

1. Clone the repo: git clone https://github.com/mrtrix3/mrtrix3 -b cmake

2. Create a build directory and configure cmake:

    $ mkdir build
    $ cmake -B build mrtrix3
   

   If all the required dependencies are installed, CMake should correctly configure the project. It's highly recommended that you use Ninja and ccache (or sccache) to configure the project, to do this run cmake -G Ninja -B build mrtrix3 instead of second step above (the script will automatically detect and use ccache if installed). You can install Ninja and ccache using your system's package manager (e.g. brew install ninja ccache or apt install ninja ccache). The project will automatically detect if ccache (or sccache) is installed on your system. You can also specify your own custom compiler caching tool by setting the CACHE_OPTION variable (by specifying -DCACHE_OPTION=custom_cache_tool).

   If you wish, we provide some default CMake presets that automatically configure the project using predefined settings. You can view the list of available presets in CMakePresets.json or run cmake --list-presets in the source directory. To configure the project using a given preset run

    $ cmake --preset name_of_configure_preset
   

   in the source directory.

3. Run the build:

    $ cmake --build build
   

   CMake will build all commands inside your build directory (the executables will be inside bin). If you'd like to build just a single command, you can do so by specifying --target name_of_command.

Configure options

You can enable/disable the following options (passing -D MYOPTION=ON/OFF to CMake at the configure stage).

• MRTRIX_USE_QT6 to enable building the project using Qt 6.

• MRTRIX_BUILD_GUI to choose whether you'd like to build the gui commands (e.g. mrview).

• MRTRIX_WARNINGS_AS_ERRORS for compilation to fail when a compiler warning is generated.

• MRTRIX_BUILD_TESTS to build tests.

Testing

To run the tests, you need to build the project as described above and ensure that you -DMRTRIX_BUILD_TESTS=ON in the CMake configuration phase. Then, from the build directory, run ctest.

Each test is prefixed by its category, so binary test names start with bin_ and unit test names start with unit_.

In order to run a specific set of tests, ctest allows you to make use of regex expressions, for example:

    $ ctest -R unit # Runs all unit tests
    $ ctest -R bin # Runs all binary tests
    $ ctest -R bin_5tt2gmwmi # Runs the binary test for the 5tt2gmwmi command
    $ ctest -E unit # Runs all tests, except unit tests

You can also choose to rerun tests have failed by specifying the --rerun-failed option.

See official documentation for using CTest.

Known issues

Compilation failure due to not using system compiler.

MRtrix may fail to compile if you're not using your system's provided compiler. This is likely caused by your PATH pointing to a folder which contains other compiler executables. A common source of this issue is the installation of other packages (e.g. FSL), which ship a compiler in their installation directory. To deal with this problem, we recommend removing the offending compiler from your PATH. You can do this temporarily in your current terminal session; for example, to remove all FSL directories from your PATH, you can use the following command:

    $ export PATH=`echo $PATH | tr ":" "\n" | grep -v "fsl" | tr "\n" ":"`

For a more permanent solution, you can modify your ~/.bashrc file.

Can't find the right compiler

If for some reason, CMake cannot find the right compiler you want to use, you can pass -DCMAKE_CXX_COMPILER=/path/to/mycompiler during the configuration stage of CMake.

Multiple Qt versions installed on macOS

If you're on macOS and have installed Qt via brew, you may need to link the correct version of Qt you intend to use to build MRtrix3. So if, for example, you want to use Qt 5, and you have both Qt 5 and Qt 6 installed via brew, you will need to run brew unlink qt && brew link qt5.