Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


gh-action-badge CI-badge style-badge docker-badge install-badge zenodo-badge

The SIRF-SuperBuild allows the user to download and compile most of the software needed to compile SIRF and Gadgetron, and automatically build SIRF and Gadgetron, and other packages useful for PET/MR data processing.

Note that there is still a small number of libraries that are not installed by the SuperBuild, see below for more info for your operating system.

In addition, this repository also contains the files for creating docker images, a VirtualBox VM as well as (probably outdated) files for creating cloud instances on Azure via TerraForm. See their respective READMEs. The rest of this README describes how to build via CMake.

Table of Contents

  1. Dependencies
  2. Generic instructions
    1. Create the SuperBuild directory
    2. Install CMake
    3. Clone the SIRF-SuperBuild project
    4. Build and Install
    5. Example Gadgetron configuration file
    6. Set Environment variables
    7. Open a terminal and start Gadgetron
    8. Testing
    9. Running examples
  3. OS specific information
    1. Installation instructions for Ubuntu
    2. Installation instructions for Mac OS
    3. Installation instructions for Docker
  4. Advanced installation
    1. Optional libraries
    2. use a different compiler than the system default
    3. Compiling against your own packages
    4. Python and MATLAB installation locations
    5. Building with specific versions of dependencies
    6. Building from your own source
    7. Building with Intel Math Kernel Library
    8. Building CCPi CIL
    9. Passing CMAKE arguments to specific projects
    10. Building with CUDA
  5. Notes


The SuperBuild depends on CMake >= 3.10.

If you are building Gadgetron there are a series of additional dependencies, which must be met.

Generic instructions

To compile and install SIRF with the SuperBuild follow these steps:

Create the SuperBuild directory

We will assume in these instructions that you want to install the software in `~/devel'. You can of course decide to put it elsewhere. Let's create it first.

mkdir ~/devel

Install CMake

If you do not have CMake >= 3.10, install it first. You can probably use a package manager on your OS. Alternatively, you can do that either by following the official instructions (download link) or running your own shell sript to do so (see an example here).

If you use a CMake installer, you will be asked to read and accept CMake's license. If you answered the last question during the CMake installation with yes, then you should use

export PATH=/usr/local/cmake/bin:$PATH

Note that the above PATH statements won't work if you are running csh. The equivalent would be for instance

set path = ( /usr/local/cmake/bin $path )

NOTE: change /usr/local/ to your chosen installation path, if different.

You might want to add the PATH line to your start-up file e.g. .profile, .bashrc or .cshrc.

Clone the SIRF-SuperBuild project

cd ~/devel
git clone

Build and Install

Create a build directory and configure the software.

Note that if you want to use MATLAB, you need to use (and specify) a compiler supported by MATLAB and might have to tell CMake where MATLAB is located. Please check our SIRF and MATLAB page.

mkdir ~/devel/build
cd ~/devel/build
cmake ../SIRF-SuperBuild

You can of course use the GUI version of CMake (called cmake-gui on Linux/OSX), or the terminal version ccmake to check and set various variables. See the CMake tutorial on how to run CMake.

By default, this will select stable configurations of the various projects. See the advanced installation section.

Important: it is currently not recommended to build both MATLAB and Python support, see below.

Then use your build environment to build and install the project. On Linux/OSX etc, you would normally use

[sudo] make -jN

where N are the number of cores you want to use for the compilation. You will only need the sudo command if you set CMAKE_INSTALL_PREFIX to a system folder (e.g., /usr/local). Note that the default location is <your-build>/INSTALL.

For Eclipse/XCode/Visual Studio, you could open the project, or build from the command line

cmake --build . --config Release

Note that there is no separate install step.

MATLAB and Python conflicts

We have encountered problems with either running or building SIRF on systems that have both Python and MATLAB installed due to problems with different versions of the HDF5 libraries (see e.g. #208). If you do have both MATLAB and Python, it might therefore be best to build twice. For instance

mkdir ~/devel/build_Python
cd ~/devel/build_Python
cmake -DDISABLE_Matlab:BOOL=ON <other-args> ../SIRF-SuperBuild
make -j3
cd ../
mkdir build_Matlab
cd build_Matlab
export CC=gcc7 # or whatever the appropriate compiler is for MATLAB
export CXX=g++7
cmake -DDISABLE_PYTHON:BOOL=ON  <other-args> ../SIRF-SuperBuild
make -j3

Gadgetron include patch

The installed Gadgetron include files contain some spurious .. which prevent correct compilation of code with it. For this reason we patch the include file after it's installed. To patch we use Python as it is probably the most portable tool.

The include has been fixed in more recent versions of Gadgetron and our patch should not do anything in such case.

Example Gadgetron configuration file

Gadgetron requires a configuration file. An example is supplied and copied by the installation procedure (unless one exists).

Set Environment variables

Source a script with the environment variables appropriate for your shell

For instance, assuming that you set CMAKE_INSTALL_PREFIX=~/devel/INSTALL,for sh/bash/ksh etc

source ~/devel/INSTALL/bin/

You probably want to add a similar line to your .bashrc/.profile.

Or for csh

source ~/devel/INSTALL/bin/env_sirf.csh

You probably want to add a similar line to your .cshrc.

Notice that for backwards compatibility a symbolic link to with the name will be created, and similarly for the csh.

Open a terminal and start Gadgetron

To be able to use Gadgetron, a Gadgetron server must be running. You can do this by opening a new terminal window and enter:


N.B.: If you didn't add any of the above statements to your .bashrc or .cshrc, you will have to source env_sirf.* again in this terminal first.


Tests for most SuperBuild projects can be en/disabled projects when configuring the build. After setting the environment variables and starting Gadgetron, you can run tests as:

cd ~/devel/build
ctest --verbose

Typical output will be something like

test 1
    Start 1: SIRF_TESTS

1: Test command: /usr/local/bin/ctest "test"
1: Test timeout computed to be: 9.99988e+06
1: Test project /home/sirfuser/devel/SIRF-SuperBuild/SIRF-prefix/src/SIRF-build
1:     Start 1: PET_TEST1
1: 1/3 Test #1: PET_TEST1 ........................   Passed    2.94 sec
1:     Start 2: MR_FULLY_SAMPLED
1: 2/3 Test #2: MR_FULLY_SAMPLED .................   Passed    3.83 sec
1:     Start 3: MR_UNDER_SAMPLED
1: 3/3 Test #3: MR_UNDER_SAMPLED .................   Passed    2.93 sec
1: 100% tests passed, 0 tests failed out of 3
1: Total Test time (real) =   9.70 sec
1/1 Test #1: SIRF_TESTS .......................   Passed    9.70 sec

100% tests passed, 0 tests failed out of 1

Total Test time (real) =   9.70 sec

The user may also run the SIRF tests independently of the SuperBuild. Just enter the SIRF build directory and launch ctest:

cd ~/devel/build
cd builds/SIRF/build
ctest --verbose

If you see failures, you might not have followed the above steps correctly, or have some missing Python modules.

Running examples

We distribute examples for both Python and MATLAB. You can find them as follows:

cd examples

See our related Wiki page for more information.

OS specific information

Installation instructions for Ubuntu

They can be found here

Installation instructions for Mac OS

They can be found here

Installation instructions for Docker

They can be found here

Advanced installation

Optional libraries

STIR can use other libraries to add extra IO capabilities. At present, the SuperBuild supports the following:

  • ITK: the Insight Toolkit. STIR will use this to read in images in file formats supported by ITK, including DICOM, Nifty, MetaIO, NRRD.
  • ROOT: the CERN framework for data handling. STIR will use this to read ROOT files produced by Open GATE, the Monte Carlo simulator.

Each of these has 2 CMake variables. For example, for ITK:

  • USE_ITK: enable ITK support
  • USE_SYSTEM_ITK (defaults OFF): if USE_ITK=ON and USE_SYSTEM_ITK=ON, do not build ITK, but let CMake find it on your system. If it cannot, you can set ITK_DIR to the path where ITKConfig.cmake was installed. See also this section.

Currently, USE_ITK defaults to ON and USE_ROOT defaults to OFF.

Each of these projects has many CMake variables when you build it directly. In this SuperBuild, we set them to build a minimal (?) set of libraries sufficient for STIR support. You can enable more features by using other CMake variables (e.g. ROOT_X11 defaults to OFF), but see also this section.


  • ROOT insert its own error handler for when a program crashes, which at first sight claims that there is a problem with ROOT. More than likely however, the problem is elsewhere. The stack trace printed on the console might help.
  • Building these libraries takes quite a long time. You could try to install them in other ways, but might encounter problems then. Let us know if that is the case.

Use a different compiler than the system default

You can tell CMake to use a different compiler than what it finds by default. You will need to specify both C and C++ compilers. For instance, to use gcc8, use

export CC CXX
ccmake normal-options

This needs to be done the very first time you run CMake for that build.

Compiling against your own packages

SIRF depends on many packages. By default, these packages are installed by the Superbuild. However, the user can decide to compile SIRF against their own versions of certain packages. This can be done via the USE_SYSTEM_* options in CMake. For example, if you wish to compile SIRF against a version of Boost that is already on your machine, you could set USE_SYSTEM_BOOST to ON.

This USE_SYSTEM_* function can be used for as many or as few packages as desired. Advantages to building against your own version of certain packages are decreased compilation times and the potential to use newer versions of these packages.

However, we have only tested SIRF with the versions of the required dependencies that are built by default in the Superbuild. If you decide to compile SIRF using system versions of the dependencies, you run a greater risk of something going wrong.

For this reason, we advise new SIRF users to compile with all the USE_SYSTEM_* options disabled. If you decide to use system versions of certain packages, we would be interested to hear about it any compatibility issues that you may run into.

Python and MATLAB installation locations

By default, Python and MATLAB executables and libraries are installed under CMAKE_INSTALL_PREFIX/python and CMAKE_INSTALL_PREFIX/matlab, respectively. If you wish for them to be installed elsewhere, you can simply cut and paste these folders to their desired locations.

In this case, you would then need to ensure that PYTHONPATH and MATLABPATH are updated accordingly. This is because the sourced env_ccppetmr will point to the original (old) location.

Package specific information

For default versions built, see version_config.cmake and below on how to change them.

The SuperBuild allows building many packages and sets dependencies correctly. However, the emphasis is on building SIRF. Its dependent packages are therefore by default built in a minimal configuration. We provide some CMake variables to change that behaviour, and also set some main options of some packages. Most of these are "advanced" CMake options so as not to confuse the new user. Naming of these options is generally the same as in the original package but prefixed. We list main examples here, but you can check with CMake (or the External*.cmake files). (See below for information on how to set other options).


  • STIR_BUILD_SWIG_PYTHON defaults to OFF, meaning that the STIR Python interface will not be built, i.e. you have to use the SIRF Python interface to STIR.
  • STIR_DISABLE_LLN_MATRIX defaults to ON, you might want to set this to OFF if you have GATE and use its output to ECAT sinograms (although this is not recommended).


  • ITK_MINIMAL_LIBS defaults to ON. For the list of modules (concentrated on IO) built, check External_ITK.cmake.
  • ITK_USE_SYSTEM_HDF5 defaults to ON, i.e. tell ITK to use same HDF5 library as other software built here. Note that this would normally be the HDF5 version built by the SuperBuild. Set this variables OFF if ITK has problems with HDF5.

Building with specific versions of dependencies

By default, the SuperBuild will build the latest stable release of SIRF and associated versions of the dependencies. However, the SuperBuild allows the user to change the versions of the projects it's building. The current default values can be found in version_config.cmake.

There is a DEVEL_BUILD tag that allows to build the upstream/master versions of most packages (DEVEL_BUILD=ON).

One may want to use only a specific version of a package. This is achieved by adding the right tag to the command line:

cd ~/devel/build
cmake ../SIRF-SuperBuild -DSIRF_TAG=<a valid hash>

To use the DEVEL_BUILD option one may (on the terminal)

cd ~/devel/build
cmake ../SIRF-SuperBuild -DDEVEL_BUILD=ON -U*_TAG -U*_URL

The -U flags will make sure that cached CMake variables are removed such that DEVEL_BUILD=ON will set them to the desired versions.

Note that the CMake *_TAG and *URL options are Advanced Options. When running the CMake GUI (or ccmake) they will therefore only be visible when you toggle those on.

Building from your own source

When developing, you might have a project already checked-out and let the SuperBuild use that. In this case, you probably also want to disable any git processing. You can achieve this by (using SIRF as an example)


Building with Intel Math Kernel Library

Gadgetron and Armadillo can make use of Intel's Math Kernel Library.

  1. Install Intel MKL following the instructions at their website. For debian based linux follow this link. The latter will install MKL in opt/intel
  2. Gadgetron's FindMKL.cmake will try to look for MKL libraries in /opt/intel on Unix/Apple and in C:/Program Files (x86)/Intel/Composer XE in Windows. Make sure that this is the location of the library or pass the vatiable MKLROOT_PATH (Unix/Apple) or set the environment variable MKLROOT_PATH on Windows.
  3. Configure the SuperBuild to pass Gadgetron_USE_MKL=ON.

Notice that other packages may look for a blas implementation issuing CMake's find_package(BLAS). This will look for MKL taking hint directories from the environment variable LD_LIBRARY_PATH, DYLD_LIBRARY_PATH and LIB, on Unix, Apple and Windows respectively.

Building CCPi CIL

It is possible to build the CCPi Core Imaging Library CIL as part of the SuperBuild. The functionality of CIL can be expanded by plugins. Currently available: CCPi-Regularisation, TomoPhantom ASTRA-toolbox and TIGRE).

There is one mandatory flag and 2 optional:

  • BUILD_CIL=ON, will build CIL and all the following plugins: CCPi-Regularisation and TomoPhantom; default OFF
  • Optional IPP_LIBRARY=<location of IPP shared libraries> and IPP_INCLUDE=<location of IPP includes> if you want to build CIL with IPP support for optimised FBP/FDK .
  • Optional BUILD_ASTRA=ON, if you want to use CIL for CT reconstruction with the ASTRA-toolbox engine. Default OFF

Passing CMAKE arguments to specific projects

You may want to change the CMAKE arguments used to build some of the projects. You can pass those flags directly to the SuperBuild CMAKE with a semicolon-separated list, using the following notation:

cmake ../SIRF-SuperBuild -D${proj}_EXTRA_CMAKE_ARGS:STRING="-Dflag1:BOOL=ON;-Dflag2:STRING=\"your_string\""

All the flags from the following projects can be set using this technique:

  • ITK
  • ROOT
  • STIR
  • Gadgetron
  • SIRF
  • NiftyPET
  • CCPi-Regularisation-Toolkit
  • TomoPhantom

As an example, the following changes some Gadgetron and NiftyReg flags


Building with CUDA

Some dependencies like Gadgetron, NiftyPET and Parallelproj require building parts of their code base with CUDA. It has been found that version 10.1 update 1 works, but following updates of 10.1 and 10.2 do not build Gadgetron. It is reported that version CUDA toolkit version 11 works. We have not tested lower versions of the toolkit yet.

Note that if you want to use the clang compiler and CUDA, you likely will have to set the CUDAHOSTCXX environment variable (before calling CMake), see also


FFTW3 issues

As CMake doesn't come with FFTW3 support, it is currently necessary to have FindFFTW3.cmake reproduced 3 times. sigh.

If you want to use your own FFTW3 library but it is not in a standard location, you have to set an environment variable FFTW3_ROOT_DIR before running CMake. This is poorely documented in FindFFTW3.cmake, which could be fixed by a PR to Gadgetron, ISMRMRD and SIRF. (Note that KT has tried to use set(ENV{FFTW3_ROOT_DIR} somelocation) in our External_FindFFTW.cmake. This however doesn't pass the environment variable to the CMake instances for Gadgetron etc.)

By the way, if you build with USE_SYSTEM_FFTW3=OFF (the default except on Windows), the FFTW3_ROOT_DIR env variable is ignored (as find_library etc give precedence to MAKE_PREFIX_PATH over HINTS ).

Armadillo issues

CMake does come with FindArmadillo.cmake but it currently (at least up to CMake 3.12) has no variable to specify its location at all. This implies that when using USE_SYSTEM_ARMADILLO=On, you have to install armadillo in a system location, unless some extra work is done. See this post on stackoverflow for some suggestions, which we haven't tried.