MacOS X installation¶
We outline the steps for installing MRtrix3 on MacOS X. Please consult Troubleshooting if you encounter any issues with the configure, build or runtime operations of MRtrix3.
Check requirements¶
To install MRtrix3 , you will need the following:
- a C++11 compliant compiler (e.g. clang in Xcode)
- Python version >= 2.6 (already included in MacOS X)
- The zlib compression library (already included in MacOS X)
- Eigen version 3
- Qt version >= 5.1 [GUI components only] - important: versions prior to this will not work
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 - thankfully OpenGL 3.3 is supported across the entire MacOS X range with OS versions >= 10.9.
Install Dependencies¶
Update MacOS X to version 10.9 (Mavericks) or higher - OpenGL 3.3 will typically not work on older versions
Install XCode from the Apple Store
Install Eigen3 and Qt5.
There are several alternatives 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
- Add Qt’s binaries to your path:
export PATH=`brew --prefix`/opt/qt5/bin:$PATH
- Install Eigen3:
- With MacPorts:
- Install Eigen3:
port install eigen3
- Install Qt5:
port install qt5
- Add Qt’s binaries to your path:
export PATH=/opt/local/libexec/qt5/bin:$PATH
- Install Eigen3:
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 http://download.qt.io/official_releases/qt/
- You need to select the file labelled
qt-opensource-mac-x64-clang-5.X.X.dmg
. Note that you need to use at least Qt 5.1, since earlier versions don’t support OpenGL 3.3. We advise you to use the latest version (5.5.0 as of the last update). 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!
Git setup¶
Set up your git environment as per the Git instructions page
Build MRtrix3¶
Clone the MRtrix3 repository:
git clone https://github.com/MRtrix3/mrtrix3.git
or if you have set up your SSH keys (for collaborators):
git clone git@github.com:MRtrix3/mrtrix3.git
Configure the MRtrix 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.
Build the binaries:
./build
Set up MRtrix3¶
Set your PATH in the shell startup file:
echo PATH=$(pwd)/release/bin:$(pwd)/scripts:\$PATH >> ~/.bashrc
Close the terminal and start another one to ensure the startup file is read (or just type ‘bash’)
type
mrview
to check that everything worksYou may also want to have a look through the List of configuration file options and set anything you think might be required on your system.
Keeping MRtrix3 up to date¶
You can update your installation at any time by opening a Git Bash terminal in the MRtrix3 folder, and typing:
git pull ./build
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.
Troubleshooting¶
Below is a list of problems that you may encounter during installation or running of MRtrix3, along with suggested solutions.
Attention
This section is incomplete
Conflicts with previous versions of Qt¶
If previous versions of Qt were already installed on the system, they can sometimes conflict with the installation of MRtrix3. This can manifest in many ways, but the two most obvious one are:
./configure
reports using the older version, but./build
completes without errors. However, MRView crashes, complaining about OpenGL version not being sufficient../configure
reports the correct version of Qt, but./build
fails with various error messages (typically related to refined macros, with previous definitions elsewhere in the code).