.. _build_from_source: Building *MRtrix3* from source ============================== The instructions below describe the process of compiling and installing *MRtrix3* from source. Please consult the `MRtrix3 forum `__ if you encounter any issues. .. WARNING:: These instructions are for more advanced users who wish to install very specific versions of *MRtrix3*, or make their own modifications. Most users will find it much easier to install one of the `pre-compiled packages available for their platform from the main MRtrix3 website `__. ---- Install Dependencies -------------------- To install *MRtrix3*, you will need to have a number of dependencies available on your system, listed below. These can be installed in a number of ways, depending on your specific platform. We provide specific instructions for doing so for GNU/Linux, macOS and Microsoft Windows in the subsequent sections. Required dependencies: - a `C++11 `__ compliant compiler (GCC version >= 5, clang); - `Python `__ version >= 3.3; - The `zlib `__ compression library; - `Eigen `__ version >= 3.2 (>= 3.3 recommended); - `Qt `__ version >= 5.5 (but *not* Qt 6) *[GUI components only]*; and optionally: - `libTIFF `__ version >= 4.0 (for TIFF support); - `FFTW `__ version >= 3.0 (for improved performance in certain applications, currently only ``mrdegibbs``); - `libpng `__ (for PNG support). The instructions below list the most common ways to install these dependencies on Linux, macOS, and Windows platforms. .. WARNING:: To run the GUI components of *MRtrix3* (``mrview`` & ``shview``), you will also need an `OpenGL `__ 3.3 compliant graphics card and corresponding software driver. Note that this implies you *cannot run the GUI components over a remote X11 connection*, since it can't support OpenGL 3.3+ rendering. The most up-to-date recommendations in this context can be found in the `relevant Wiki entry `__ on the `MRtrix3 community forum `__. Linux ^^^^^ The installation procedure will depend on your system. Package names may changes between distributions, and between different releases of the same distribution. We provide commands to install the required dependencies on some of the most common Linux distributions below. .. WARNING:: The commands below are **suggestions** based on what has been reported to work in the past, but may need to be tailored for your specific distribution. See below for hints on how to proceed in this case. - Ubuntu Linux (and derivatives, e.g. Linux Mint):: sudo apt-get install git g++ python3 libeigen3-dev zlib1g-dev libqt5opengl5-dev libqt5svg5-dev libgl1-mesa-dev libfftw3-dev libtiff5-dev libpng-dev - RPM-based distros (Fedora, CentOS):: sudo yum install git g++ python3 eigen3-devel zlib-devel libqt5-devel libgl1-mesa-dev fftw-devel libtiff-devel libpng-devel On Fedora 24, this is reported to work:: sudo yum install git gcc-c++ python3 eigen3-devel zlib-devel qt-devel mesa-libGL-devel fftw-devel libtiff-devel libpng-devel - Arch Linux:: sudo pacman -Syu git python gcc zlib eigen qt5-svg fftw libtiff libpng You may find that your package installer is unable to find the packages listed, or that the subsequent steps fail due to missing dependencies (particularly the ``./configure`` command). In this case, you will need to search the package database and find the correct names for these packages: - ``git``; - an appropriate C++ compiler (e.g. GCC 5 or above, or clang); - Python version >= 3.3; - the ``zlib`` compression library and its corresponding development header/include files; - the Eigen template library (only consists of development header/include files); - Qt version >= 5.5, its corresponding development header/include files, and the executables required to compile the code. Note that this can be broken up into several packages, depending on how your distribution has chosen to distribute this. You will need to get those that provide these Qt modules: Core, GUI, OpenGL, SVG, and the ``qmake``, ``rcc`` & ``moc`` executables (note these will probably be included in one of the other packages); - *[optional]* the TIFF library and utilities version >= 4.0, and its corresponding development header/include files; - *[optional]* the FFTW library version >= 3.0, and its corresponding development header/include files; - *[optional]* the PNG library and its corresponding development header/include files. .. WARNING:: Compilers included in older distributions, e.g. Ubuntu 12.04, may not be capable of compiling *MRtrix3*, as it requires C++11 support. A solution is to install a newer compiler as provided by an optional addon package repository, e.g. the `Ubuntu toolchain PPA `__. Once the relevant repository has been added to the distribution's package manager, you'll need to update the local list of available packages (e.g. ``sudo apt-get update``), followed by explicit installation of the newer version of the compiler (e.g. ``sudo apt-get install g++-7``). .. NOTE:: In many instances where *MRtrix3* dependencies are installed in some non-standard fashion, the *MRtrix3* ``configure`` script will not be able to automatically identify the location and/or appropriate configuration of those dependencies. In such cases, the *MRtrix3* ``configure`` script provides a range of environment variables that can be set by the user in order to provide this information. Executing ``configure -help`` provides a list of such environment variables; in addition, if the script is unable to detect or utilise a particular dependency properly, it will also provide a suggestion of which environment variable may need to be set in a manner tailored for your particular system in order to provide it with the information it needs to locate that dependency. .. SEEALSO:: If for whatever reasons you need to install *MRtrix3* on a system with older dependencies, and you are unable to update the software (e.g. you want to run *MRtrix3* on a centrally-managed HPC cluster), you can as a last resort use the `procedures described in this community forum post `__. macOS ^^^^^ 1. Update macOS to version 10.10 (Yosemite) or higher (OpenGL 3.3 will typically not work on older versions); 2. Install XCode from the `App Store `__; 3. Install Eigen3 and Qt5. There are several alternative ways to do this, depending on your current system setup. The most convenient is probably to use your favorite package manager (`Homebrew `__ or `MacPorts `__), or install one of these if you haven't already. If you find your first attempt doesn't work, *please* resist the temptation to try one of the other options: in our experience, this only leads to further conflicts, which won't help installing MRtrix3 *and* will make things more difficult to fix later. Once you pick one of these options, we strongly recommend you stick with it, and consult the `community forum `__ if needed for advice and troubleshooting. - With `Homebrew `__: - Install Eigen3: ``brew install eigen`` - Install Qt5: ``brew install qt5`` - Install pkg-config: ``brew install pkg-config`` - Add Qt's binaries to your path: ``export PATH=`brew --prefix`/opt/qt5/bin:$PATH`` - With `MacPorts `__: - Install Eigen3: ``port install eigen3`` - Install Qt5: ``port install qt5`` - Install pkg-config: ``port install pkgconfig`` - Add Qt's binaries to your path: ``export PATH=/opt/local/libexec/qt5/bin:$PATH`` - As a last resort, you can manually install Eigen3 and Qt5: You can use this procedure if you have good reasons to avoid the other options, or if for some reason you cannot get either `Homebrew `__ or `MacPorts `__ to work. - Install Eigen3: download and extract the source code from `eigen.tuxfamily.org `__ - Install Qt5: download and install the latest version from ``__ You need to select the file labelled ``qt-opensource-mac-x64-clang-5.X.X.dmg``. You can choose to install it system-wide or just in your home folder, whichever suits; just remember where you installed it. - Make sure Qt5 tools are in your PATH (edit as appropriate): ``export PATH=/path/to/Qt5/5.X.X/clang_64/bin:$PATH`` - Set the CFLAG variable for Eigen (edit as appropriate): ``export EIGEN_CFLAGS="-isystem /where/you/extracted/eigen"`` Make sure *not* to include the final ``/Eigen`` folder in the path name: use the folder in which it resides instead! 4. Install TIFF, FFTW and PNG libraries. - With `Homebrew `__: - Install TIFF: ``brew install libtiff`` - Install FFTW: ``brew install fftw`` - Install PNG: ``brew install libpng`` - With `MacPorts `__: - Install TIFF: ``port install tiff`` - Install FFTW: ``port install fftw-3`` - Install PNG: ``port install libpng`` Windows ^^^^^^^ All of these dependencies are installed below by the MSYS2 package manager. .. WARNING:: When following the instructions below, use the **'MinGW-w64 Win64 shell'**; 'MSYS2 shell' and 'MinGW-w64 Win32 shell' *must* be avoided, as they will yield erroneous behaviour that is difficult to diagnose if used accidentally. .. WARNING:: At time of writing, this MSYS2 system update will give a number of instructions, including: terminating the terminal when the update is completed, and modifying the shortcuts for executing the shell(s). Although these instructions are not as prominent as they could be, it is *vital* that they are followed correctly! 1. Download and install the most recent 64-bit MSYS2 installer from http://msys2.github.io/ (msys2-x86\_64-\*.exe), and following the installation instructions from the `MSYS2 wiki `__. 2. Run the program **'MinGW-w64 Win64 Shell'** from the start menu. 3. Update the system packages, `as per the instructions `__:: pacman -Syuu Close the terminal, start a new **'MinGW-w64 Win64 Shell'**, and repeat as necessary until no further packages are updated. 4. From the **'MinGW-w64 Win64 Shell'** run:: pacman -S git python3 pkg-config mingw-w64-x86_64-gcc mingw-w64-x86_64-eigen3 mingw-w64-x86_64-qt5 mingw-w64-x86_64-fftw mingw-w64-x86_64-libtiff mingw-w64-x86_64-libpng Sometimes ``pacman`` may fail to find a particular package from any of the available mirrors. If this occurs, you can download the relevant package from `SourceForge `__: place both the package file and corresponding .sig file into the ``/var/cache/pacman/pkg`` directory, and repeat the ``pacman`` call above. Sometimes ``pacman`` may refuse to install a particular package, claiming e.g.:: error: failed to commit transaction (conflicting files) mingw-w64-x86_64-eigen3: /mingw64 exists in filesystem Errors occurred, no packages were upgraded. Firstly, if the offending existing target is something trivial that can be deleted, this is all that should be required. Otherwise, it is possible that MSYS2 may mistake a *file* existing on the filesystem as a pre-existing *directory*; a good example is that quoted above, where ``pacman`` claims that directory ``/mingw64`` exists, but it is in fact the two files ``/mingw64.exe`` and ``/mingw64.ini`` that cause the issue. Temporarily renaming these two files, then changing their names back after ``pacman`` has completed the installation, should solve the problem. ---- Git setup --------- If you intend to contribute to the development of *MRtrix3*, set up your git environment as per the `Git instructions page `__ ---- .. _build_mrtrix3: Build *MRtrix3* --------------- 1. Clone the *MRtrix3* repository:: git clone https://github.com/MRtrix3/mrtrix3.git or if you have set up your SSH keys (for contributors):: git clone git@github.com:MRtrix3/mrtrix3.git 2. Configure the *MRtrix3* install:: cd mrtrix3 ./configure If this does not work, examine the 'configure.log' file that is generated by this step, it may give clues as to what went wrong. 3. Build the binaries:: ./build ---- Set up *MRtrix3* ---------------- 1. Update the shell startup file, so that the locations of *MRtrix3* commands and scripts will be added to your ``PATH`` envionment variable. If you are not familiar or comfortable with modification of shell files, *MRtrix3* now provides a convenience script that will perform this setup for you (assuming that you are using ``bash`` or equivalent interpreter). From the top level *MRtrix3* directory, run the following:: ./set_path 2. Close the terminal and start another one to ensure the startup file is read (or just type 'bash') 3. Type ``mrview`` to check that everything works 4. You may also want to have a look through the :ref:`config_file_options` and set anything you think might be required on your system. .. NOTE:: The above assumes that your shell will read the ``~/.bashrc`` file at startup time. This is not always guaranteed, depending on how your system is configured. If you find that the above doesn't work (e.g. typing ``mrview`` returns a 'command not found' error), try changing step 1 to instruct the ``set_path`` script to update ``PATH`` within a different file, for example ``~/.bash_profile`` or ``~/.profile``, e.g. as follows:: ./set_path ~/.bash_profile ---- Keeping *MRtrix3* up to date ---------------------------- 1. You can update your installation at any time by opening a terminal in the *MRtrix3* folder, and typing:: git pull ./build 2. If this doesn't work immediately, it may be that you need to re-run the configure script:: ./configure and re-run step 1 again.