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.
- Dependencies
- Generic instructions
- OS specific information
- Advanced installation
- Optional libraries
- use a different compiler than the system default
- Compiling against your own packages
- Python and MATLAB installation locations
- 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
- Notes
The SuperBuild depends on CMake >= 3.10.
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:
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 ~/develIf 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.
cd ~/devel
git clone https://github.com/SyneRBI/SIRF-SuperBuild.gitCreate 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-SuperBuildYou 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 -jNwhere 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 ReleaseNote that there is no separate install step.
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 -j3The 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.
Gadgetron requires a configuration file. An example is supplied and copied by the installation procedure (unless one exists).
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.shYou probably want to add a similar line to your .bashrc/.profile.
Or for csh
source ~/devel/INSTALL/bin/env_sirf.cshYou 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.
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.
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 --verboseTypical 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
cd builds/SIRF/build
ctest --verboseIf you see failures, you might not have followed the above steps correctly, or have some missing Python modules.
We distribute examples for both Python and MATLAB. You can find them as follows:
cd $SIRF_PATH
cd examples
lsSee our related Wiki page for more information.
They can be found here
They can be found here
They can be found here
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 supportUSE_SYSTEM_ITK(defaultsOFF): ifUSE_ITK=ONandUSE_SYSTEM_ITK=ON, do not build ITK, but let CMake find it on your system. If it cannot, you can setITK_DIRto the path whereITKConfig.cmakewas 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.
WARNINGS:
- 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.
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
CC=gcc8
CXX=g++8
export CC CXX
ccmake normal-optionsThis needs to be done the very first time you run CMake for that build.
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.
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.
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_EXECUTABLESdefaults toOFFSTIR_BUILD_SWIG_PYTHONdefaults toOFF, 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_MATRIXdefaults toON, you might want to set this toOFFif you have GATE and use its output to ECAT sinograms (although this is not recommended).STIR_ENABLE_EXPERIMENTALdefaults toOFF
ITK_MINIMAL_LIBSdefaults toON. For the list of modules (concentrated on IO) built, check External_ITK.cmake.ITK_USE_SYSTEM_HDF5defaults toON, 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 variablesOFFif ITK has problems with HDF5.
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*_URLThe -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.
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 ../SIRF-SuperBuild -DDISABLE_GIT_CHECKOUT_SIRF=ON -DSIRF_SOURCE_DIR=~/wherever/SIRFGadgetron and Armadillo can make use of Intel's Math Kernel Library.
- Install Intel MKL following the instructions at their website. For debian based linux follow this link. The latter will install MKL in
opt/intel - Gadgetron's FindMKL.cmake will try to look for MKL libraries in
/opt/intelon Unix/Apple and inC:/Program Files (x86)/Intel/Composer XEin Windows. Make sure that this is the location of the library or pass the vatiableMKLROOT_PATH(Unix/Apple) or set the environment variableMKLROOT_PATHon Windows. - 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.
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 buildCILand all the following plugins:CCPi-RegularisationandTomoPhantom; defaultOFF- Optional
IPP_LIBRARY=<location of IPP shared libraries>andIPP_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. DefaultOFF
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
- NIFTYREG
- NiftyPET
- CCPi-Regularisation-Toolkit
- TomoPhantom
As an example, the following changes some Gadgetron and NiftyReg flags
cmake ../SIRF-SuperBuild -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"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
https://cmake.org/cmake/help/latest/variable/CMAKE_CUDA_HOST_COMPILER.html.
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 ).
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.