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.
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 verson ccmake to check and set various variables. See the CMake tutorial on how to run CMake.
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.
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.
Gadgetron requires a configuration file. An example is supplied and, as a starting point, this can be copied and used as the real thing:
mv INSTALL/share/gadgetron/config/gadgetron.xml.example INSTALL/share/gadgetron/config/gadgetron.xml
replacing INSTALL with the directory you used for CMAKE_INSTALL_PREFIX.
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 the SIRF-SuperBuild are currently the SIRF tests. The tests can contain tests from most SuperBuild projects. 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
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.
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 all 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 CIL consists on a few pieces of software (CCPi-Framework, CCPi-FrameworkPlugins, CCPi-Regularisation-Toolkit, CCPi-Astra). There are 2 options:
BUILD_CILwill build CIL and ASTRA-toolbox and TomoPhantomBUILD_CIL_LITEwill build only CIL (and leave outCCPi-Astra)
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:
- 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.
-
As CMake doesn't come with FFTW3 support, it is currently necessary to have
FindFFTW3.cmakereproduced 3 times. sigh. -
This is poorely documented in FindFFTW3.cmake, which could be fixed by a PR to Gadgetron, ISMRMRD and SIRF. Similarly, we could fix
FindFFTW3.cmaketo also use the CMake variable. -
KT has tried to use
set(ENV{FFTW3_ROOT_DIR} somelocation)in ourExternal_FindFFTW.cmake. This however doesn't pass the environment variable to the CMake instances for Gadgetron etc. -
By the way, when using
USE_SYSTEM_FFTW3=OFF, CMake currently does find our own installation even if theFFTW3_ROOT_DIRenv variable (as find_library etc give precedence toMAKE_PREFIX_PATHoverHINTS). -
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.