SIRF-SuperBuild

The SIRF-SuperBuild can download/build/install SIRF and its dependencies (including Gadgetron and other packages useful for PET/MR data processing).

The SuperBuild can:

• build & run docker containers: the easiest way
• build & run a VirtualBox VM: used to build SIRF VM
• launch cloud instances on Azure via TerraForm: probably outdated
• build & run manually using CMake: see instructions below

Contents

• Running SIRF with Docker
• Running SIRF with VirtualBox
• Building and Running SIRF manually
  • Dependencies
  • Create the SuperBuild directory
  • Install CMake
  • Clone the SIRF-SuperBuild project
  • Build and Install
  • Set Environment variables
  • Open a terminal and start Gadgetron
  • Testing
  • Running examples
• OS specific information
  • Installation instructions for Ubuntu
  • Installation instructions for Mac OS
• Advanced installation
  • Optional libraries
  • use a different compiler than the system default
  • Compiling against your own packages
  • Python installation location
  • Building with specific versions of dependencies
  • Building from your own source
  • Building with Intel Math Kernel Library
  • Building CCPi CIL
  • Passing CMAKE arguments to specific projects
  • Building with CUDA
• FAQs

Running SIRF with Docker

Tip

The easiest way to run SIRF & all its dependencies is to use Docker.

For running (or even building) docker containers, see docker/README.md.

Running SIRF with VirtualBox

See VirtualBox/README.md.

Building and Running SIRF manually

Dependencies

The SuperBuild depends on CMake >= 3.16.2 on Linux and 3.20 on Windows.

Note

A few dependencies are not installed by the SuperBuild; see operating system information.

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

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.16.2 on Linux and 3.20 on Windows, install it first. We suggest to follow the official CMake instructions.

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 on Linux you should use

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

Change /usr/local/ to your chosen installation path (if different).

Tip

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

Warning

export statements won't work if you are running csh. The equivalent would be:

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

Clone the SIRF-SuperBuild project

cd ~/devel
git clone https://github.com/SyneRBI/SIRF-SuperBuild

Build and Install

Create a build directory and configure the software.

cmake -S ./SIRF-SuperBuild -B ./build

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.

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

cmake --build ./build --parallel N
# alternatively: sudo cmake --build ./build --parallel N

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 ./build --config Release

Note that there is no separate install step.

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/env_sirf.sh

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 env_sirf.sh with the name env_ccppetmr.sh 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:

gadgetron

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.

Testing

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:
1: 100% tests passed, 0 tests failed out of 3
1:
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/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

Examples are installed in $SIRF_PATH/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

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.

Warning

• 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 gcc-11, use

CC=gcc-11
CXX=g++-11
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 installation location

By default, Python executables and libraries are installed under CMAKE_INSTALL_PREFIX/python. If you wish for them to be installed elsewhere, you can set the PYTHON_DEST CMake variable.

Alternatively, you simply cut and paste these folders to their desired locations. In this case, you would then need to ensure that PYTHONPATH is updated accordingly. This is because the sourced env_sirf.* 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

• STIR_BUILD_EXECUTABLES defaults to OFF
• STIR_BUILD_SWIG_PYTHON defaults to ON, meaning that the STIR Python interface will be built, i.e. you can use STIR's Python interface as well as 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).
• STIR_ENABLE_EXPERIMENTAL defaults to OFF

ITK

• 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:

cmake -S ./SIRF-SuperBuild -B ./build -DSIRF_TAG=<a valid hash>

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

cmake -S ./SIRF-SuperBuild -B ./build -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)

cmake -S ./SIRF-SuperBuild -B ./build -DDISABLE_GIT_CHECKOUT_SIRF=ON -DSIRF_SOURCE_DIR=~/wherever/SIRF

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 variable 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 -S ./SIRF-SuperBuild -B ./build -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
• NIFTYREG
• NiftyPET
• CCPi-Regularisation-Toolkit
• TomoPhantom

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

cmake -S ./SIRF-SuperBuild -B ./build -DGadgetron_EXTRA_CMAKE_ARGS:STRING="-DBUILD_PYTHON_SUPPORT:BOOL=ON;" -DNIFTYREG_EXTRA_CMAKE_ARGS:STRING="-DCUDA_FAST_MATH:BOOL=OFF;-DCMAKE_VERBOSE_MAKEFILE:BOOL=OFF"

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 CMAKE_CUDA_HOST_COMPILER.

FAQs

MATLAB support

Previous versions of SIRF had a MATLAB interface. This is now outdated and probably broken. If you want to try it anyway, check our SIRF and MATLAB page.

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 poorly documented in FindFFTW3.cmake, which could be fixed by a PR to Gadgetron, ISMRMRD and SIRF. (Note that @KrisThielemans has tried to use set(ENV{FFTW3_ROOT_DIR} some/location) 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 CMAKE_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.