Skip to content

Latest commit

 

History

History
270 lines (203 loc) · 13.5 KB

README.md

File metadata and controls

270 lines (203 loc) · 13.5 KB
Raw

SIRF-SuperBuild

CI-badge style-badge docker-badge install-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. There is still a small number of libraries that are not installed by the SuperBuild, see below for more info for your operating system.

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. Compiling against your own packages
    2. Python and MATLAB installation locations
    3. Building with specific versions of dependencies

Dependencies

The SuperBuild depends on CMake >= 3.7.

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 >= 3.7

If you do not have CMake >= 3.7 install it first (download link). On Ubuntu Linux, you can issue the following commands

wget https://cmake.org/files/v3.7/cmake-3.7.2-Linux-x86_64.sh
sudo mkdir /opt/cmake
sudo bash cmake-3.7.2-Linux-x86_64.sh --prefix=/opt/cmake
export PATH=/opt/cmake/bin:$PATH

During installation 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=/opt/cmake/cmake-3.7.2-Linux-x86_64/bin:$PATH

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

set path = ( /opt/cmake/bin $path )

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

Clone the SIRF-SuperBuild project 

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

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.

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

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

make -jN

where N are the number of cores you want to use for the compilation. For Eclipse/XCode/Visual Studio, you could open the project, or try something like

cmake --build . --config Release

Note that there is no separate install step.

Example Gadgetron configuration file

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

Set Environment variables

Source a script with the environment variables appropriate for your shell

For instance, for sh/bash/ksh etc

cd ~/devel/build
source INSTALL/bin/env_ccppetmr.sh

You probably want to add a similar line (with absolute path) to your .bashrc/.profile.

Or for csh

cd ~/devel/build
source INSTALL/bin/env_ccppetmr.csh

You probably want to add a similar line (with absolute path) to your .cshrc.

Open a terminal and start Gadgetron

To be able to use Gadgetron, a Gadgetron client must already be open in another terminal window. To do this, open 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_ccpetmr.* again in this terminal first.

Testing

Tests for the SIRF-SuperBuild are currently the SIRF tests. The tests can contain tests from all SuperBuild projects. 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
cd SIRF-prefix/src/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 $SIRF_PATH
cd examples
ls

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

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.

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.

This is done at the configuration stage that happens when you run cmake.

There is a DEVEL_BUILD tag that allows to build the upstream/master versions of all packages (DEVEL_BUILD=ON). In the following table are listed example versions (hashes) of dependencies that are built by the SuperBuild. The current default values can be found in version_config.cmake.

TAG DEVEL_BUILD=OFF (default) DEVEL_BUILD=ON
SIRF_TAG v1.0.0 origin/master
STIR_URL https://github.com/UCL/STIR https://github.com/UCL/STIR
STIR_TAG 41651b3a2007c58cbf1f7706bb2e269a21e870b1 origin/master
Gadgetron_URL https://github.com/gadgetron/gadgetron https://github.com/gadgetron/gadgetron
Gadgetron_TAG e7eb430673eb3272e8a821b51750c0a2a96dafed origin/master
ISMRMRD_URL https://github.com/ismrmrd/ismrmrd https://github.com/ismrmrd/ismrmrd
ISMRMRD_TAG 42d93137cc16c270c8ba065edd2496483161bd21 origin/master

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

cd ~/devel/build
cmake ../SIRF-SuperBuild -DDEVEL_BUILD=ON

Additionally one may want to use only a specific version of a package. This is achieved by adding the right tag to the command line (see the table above for available tags):

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

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

Warning: All these variables are cached. This means that once set, you have to change them one by one. Setting DEVEL_BUILD=ON will therefore not work as expected on an existing build. You will need to delete the cached variables first. You could do

cmake -DDEVEL_BUILD=ON -USIRF_URL -USIRF_TAG -USTIR_URL -USTIR_TAG -UGadgetron_URL -UGadgetron_TAG -UISMRMRD_URL -UISMRMRD_TAG .