Installing STIR with CMake

This page provides instructions on how to install STIR using CMake. You will need STIR 2.2 or later for this to work.

= Introduction = CMake is a cross-platform tool for building projects. It allows STIR to have a unique set of files that describe the libraries, tests etc, independent of the platform that you are using.

Building a project with STIR involves three steps: you first need to install some external packages, then run CMake to generate files appropriate to your build system. Then you use your build system to actually do the compilation, testing, installation etc. A build system can be your IDE (e.g. Visual Studio), make on Unix/Linux etc.

You might want to check the CMake help pages for more information. For example,


 * Information on how to run CMake
 * CMake FAQ
 * How to use a different compiler
 * Some information on using different generators for different build systems

You might find Milad Fard's installation video useful. However, it is highly recommended to read the text below.

= Step 1: Download/install pre-requisites = More detailed instructions are in the STIR User's Guide, but the following might get you going.

STIR relies on a few external libraries which you need to install first.


 * Boost, a well-respected C++ library which forms the basis for many newer C++ features.
 * python is a scripting language. STIR currently only uses it in some of the SimSET scripts.
 * The ECAT Matrix library from Merence Sibomana and Christian Michel. Only used to read/write data from old CTI PET scanners such as ECAT HR+. You might find this library at a Louvain-la-Neuve university ftp-site. It also comes with GATE.

Unix-type systems
Linux systems use a package management system. Unfortunately, there are many different versions, and the packages have slightly different names. Here is what we know:

debian/Ubuntu or others using APT
apt-get install gcc g++ make cmake-curses-gui libncurses-dev libx11-dev libboost-dev libpng-dev tcsh python (prefix with sudo for Ubuntu). If you intend to build the python interface to STIR as well, you will need to add the python-dev package to the above list, and install some other useful packages. For instance apt-get install swig apt-get install python-dev python-numpy ipython python-matplotlib mayavi2 Note: on old Ubuntu/debian systems (e.g. Ubuntu 14.x) you need to install the swig3.0 package, not swig.

If you will be compiling with MPI support, use apt-get install mpi-default-dev mpi-default-bin If you want to use ITK for extra IO capabilities (since STIR 3.0), use apt-get install libinsighttoolkit4-dev libtiff5-dev

Fedora (and others?) using yum
The following might work when your system uses yum. sudo yum install gcc gcc-c++ make cmake cmake-gui ncurses-devel libX11-devel boost boost-devel tcsh python If this fails, try to issue one "yum install" command for every package.

Arch using pacman
The following might work when your system uses pacman. $ su If this fails, try to issue one "pacman -Ss" command for every package.
 * 1) pacman -Sy gcc make cmake cmake-gui ncurses  libx11 boost boost-libs tcsh python

Mac OS X
You need the development environment. You would need for instance It's probably a good idea to install MacPorts. Then you should be able to use the following: sudo port install boost cmake Alternatively, you could install extra software manually. See Installing_STIR_with_CMake.
 * XCode https://developer.apple.com/xcode

cygwin on Windows
Use cygwin's setup to install gcc, g++, make, cmake, libncurses-devel, libX11-devel, libboost-devel, tcsh, python.

Other systems or manual download
You can use these also if you don't have super-user permission.


 * Download CMake from http://www.cmake.org and install.
 * Download Boost from http://www.boost.org. Currently, STIR only uses the include files from Boost so you do not need to build the boost libraries, only untar/unzip the boost package. You can put this anywhere you like, as long as you set the BOOST_ROOT flag accordingly (See below).
 * Download SWIG http://www.swig.org if you want to use SWIG to build an interface between STIR and Python. Clearly, you would need Python then as well. For an interface between STIR and MATLAB, you need to compile another version of SWIG for which you can find the details at Installing the MATLAB interface to STIR.

= Step 2: Run cmake =

Setting your environment
You might need to set your environment correctly first such that CMake finds the correct libraries etc. Examples are
 * Python virtual environments (e.g. via conda activate or similar)
 * The CERN ROOT library for GATE simulations comes with a thisroot.sh (or.csh) script that needs to be sourced.

This step is not strictly necessary, as it is also possible to set the location of any libraries/include files in the CMake Configuration step, but this tends to be harder work.

Using the CMake GUI
If you have Windows or MacOSX, CMake comes as an application with a nice GUI. For Unix/linux users, you get that by installing cmake-gui.

Please note that if you launch CMake from your desktop environment, you will have to make sure that any configuration from the previous section is available to such applications (which usually isn't the case). It might be best to launch cmake-gui from the command line.

After launching it, you first select the source directory (STIR, not STIR/src) and then a build directory. It's recommended to build one level up from STIR. Call it anything you like, e.g. STIR-bin.

On Unix/Linux you will probably be using make to build things. When using make, you want different build directories for every type of build (Debug or Release) you want to make. For systems using an IDE (e.g. Windows with Visual Studio or MacOS with XCode, Linux with eclipse), you can build different versions from one CMake build directory.

From a terminal window
On Unix/linux, cygwin or MacOSX, you can also launch CMake from a terminal window. In that case, you will have to use a slightly more basic user interface. You would launch this as follows. cd /wherever/it/is/STIR cd .. mkdir STIR-bin cd STIR-bin mkdir Release cd Release ccmake ../../STIR If you want to use a non-default compiler, please check the CMake FAQ on how to use a different compiler.

Special cases for Windows
In some very special cases, you will need to let CMake find non-standard libraries or executables. Most people will not need this, but if you do, please check Using CMake on Windows with special requirements.

Configuring the STIR build
Once CMake has started, you have to press the 'Configure' button (or c key). CMake might ask you for the "generator" to use. This will determine which compiler you will use for building STIR. Normally the default choice is fine, but you could for instance select Eclipse from here if you have it. On Windows with Visual Studio, you can use this to select if you are going to build STIR with the 32-bit of 64-bit compilers. (Normally both options are fine, unless you want to use specific external libraries).

Then CMake will try to find out as much as it can about your set-up. For instance, it will check if your C++ compiler works properly, if you have X windows (and the curses library installed), if you have the boost C++ library etc. You might get a "help" screen with some information, which you'll need to close (after reading the information of course). For example, if some required libraries are missing, it will tell you. e.g. saying that FindBoost.cmake cannot find boost and that you need to set the BOOST_ROOT variable. You then get back to a screen with the configuration variables, where you can adjust things. For example, if you installed boost somewhere where CMake didn't find it, you can edit its location there (set BOOST_ROOT to where you extracted boost. If you don't see the BOOST_ROOT variable, toggle Advanced Mode on).

Most of the variables should be fine, except possibly for the following:


 * When you don't use an IDE such as Visual Studio/Eclipse/XCode, you will probably want to set CMAKE_BUILD_TYPE to Release (otherwise STIR will be very slow).


 * By default, CMake will tell your build system to install STIR in a location for system-wide access (e.g. /usr/local or c:\Program Files). If you don't have administrator permissions, you should change this location by adjusting CMAKE_INSTALL_PREFIX.

If you change one of the variables, you will have to configure again. For example, on my Linux system, the variables end up to something like this (where the CURSES variables where set by CMake) AVW_ROOT_DIR BOOST_ROOT BUILD_DOCUMENTATION             OFF BUILD_SHARED_LIBS               OFF BUILD_SWIG_PYTHON               OFF BUILD_SWIG_MATLAB               OFF BUILD_TESTING                   ON                                            CCACHE_PROGRAM                   /usr/bin/ccache CERN_ROOT_CONFIG                /usr/bin/root-config CERN_ROOT_MultiProc_LIBRARY     CERN_ROOT_MultiProc_LIBRARY-NOTFOUND CERN_ROOT_Physics_LIBRARY       CERN_ROOT_Physics_LIBRARY-NOTFOUND CERN_ROOT_Postscript_LIBRARY    CERN_ROOT_Postscript_LIBRARY-NOTFOUND CMAKE_BUILD_TYPE                Release CMAKE_INSTALL_PREFIX            /home/kris/ CURSES_CURSES_H_PATH            /usr/include CURSES_FORM_LIBRARY             /usr/lib/libform.so                           CURSES_HAVE_CURSES_H             /usr/include/curses.h                         DISABLE_AVW                      OFF DISABLE_CERN_ROOT               OFF DISABLE_HDF5                    OFF DISABLE_HDF5_SUPPORT            OFF DISABLE_ITK                     OFF DISABLE_LLN_MATRIX              OFF DISABLE_RDF                     OFF DISABLE_STIR_LOCAL              OFF GRAPHICS                        X                                             HDF5_CXX_LIBRARY_dl              /usr/lib/x86_64-linux-gnu/libdl.so            HDF5_CXX_LIBRARY_hdf5            /usr/lib/x86_64-linux-gnu/hdf5/serial/libhdf5 HDF5_CXX_LIBRARY_hdf5_cpp       /usr/lib/x86_64-linux-gnu/hdf5/serial/libhdf5 HDF5_CXX_LIBRARY_m              /usr/lib/x86_64-linux-gnu/libm.so             HDF5_CXX_LIBRARY_pthread         /usr/lib/x86_64-linux-gnu/libpthread.so       HDF5_CXX_LIBRARY_sz              /usr/lib/x86_64-linux-gnu/libsz.so            HDF5_CXX_LIBRARY_z               /usr/lib/x86_64-linux-gnu/libz.so     ITK_DIR                          /home/sirfuser/devel/build/SIRF-SuperBuild/INSTALL/lib/cmake/ITK-4.13 LLN_INCLUDE_DIRS                /home/kris/devel/lln/ecat LLN_LIBRARIES                   /home/kris/devel/lln/ecat/debuggcc_64/libecat.a RDF_INCLUDE_DIRS                 RDF_INCLUDE_DIRS-NOTFOUND RDF_LIBRARIES                   RDF_LIBRARIES-NOTFOUND STIR_ENABLE_EXPERIMENTAL        OFF STIR_LOCAL                      /home/kris/devel/STIR/local STIR_MPI                        OFF STIR_OPENMP                     ON                                    A lot of these were set by CMake itself. Each variable has a one-line help message (which you can see by hovering over it in the CMake GUI, or by moving the cursor to the line with the variable in ccmake). See the next section for some info on STIR specific variables.

The LLN* variables refer to the ECAT LLN library. The AVW_ROOT_DIR variable refers to the location of the AnalyzeAVW commercial library. From STIR 3.0 you will also see ITK_DIR to use the ITK library. CERN_ROOT* variables point to the ROOT libraries etc. If you have any of these, setting these variables appropriately gives you some extra IO capabilities in STIR, but this is optional. See also.

The RDF* variables refer to a proprietary GE library for eading GE RDF files. However, this libary is currently not available so leave these variables as they are.

Once you are happy, you have to press generate. After this, you can quit CMake.

Configuration flags

 * BUILD_SHARED_LIBS can be used to enable shared libraries. However, this curently does *not* work on many systems. See https://github.com/UCL/STIR/issues/6.


 * BUILD_SWIG_PYTHON and BUILD_SWIG_MATLAB can be set to ON to enable the Python or MATLAB interfaces to STIR. You will need to have SWIG installed (and of course Python or MATLAB). For Python, any relatively recent version of SWIG should work (although the more recent, the better). For MATLAB, you currently need to build your own version of SWIG based on a fork. See Installing the MATLAB interface to STIR.


 * The DISABLE_* variables allow you to disable some features, even if you have the necessary libraries.


 * GRAPHICS can be set to specify the type of graphics output. See the STIR User's Guide.


 * STIR_MPI switches on the use of the MPI library for reconstruction. This will then look for MPI libraries on your system. See the STIR User's guide for how to run executables compiled with MPI.


 * STIR_OPENMP switches on the use of OPENMP reconstruction. This will then look for OPENMP libraries on your system if necessary. This is not yet recommended for STIR 3.0 or earlier.


 * STIR_LOCAL can be used to extend STIR with your own files. This is described in the STIR developer's guide.

experimental/CMakeLists.txt etc.
 * STIR_ENABLE_EXPERIMENTAL allows building some experimental features. You will likely want to check

Changing optimisation flags
You might want to change the compiler flags for optimal performance. For example, with GCC, it is probably a good idea to enable the -Ofast (from gcc 4.6) and -march=native flags. Intel C++ should benefit from the -fast flag. You can do this by changing the CMAKE_CXX_FLAGS_RELEASE</tt> setting. To do this, you will have to toggle Advanced Mode on.

= Stage 3: actual compilation = The previous step used CMake to generate files for the build system appropriate for your OS. Now, you need to use the build system to compile STIR. We list the most common ones:

Unix-type systems: make
CMake will have created a series of directories in STIR-bin with a series of Makefiles. To build STIR, you just type make

If there are compilation problems, you might want to see the compilation commands: make VERBOSE=1

Run the tests (see also next section). make test

You would normally finish with make install

Potential problems
On Linux, you might see an error like /usr/bin/ld: /home/user/ecat/lib/libecat.a(matrix_extra.o): relocation R_X86_64_32 against `.rodata.str1.1' can not be used when making a shared object; recompile with -fPIC This can happen when you enable shared libraries in STIR, or when you build the Python or MATLAB support. The reason for this error is that Python/MATLAB modules are shared libraries and on Linux this sadly means that all code needs to be compiled with -fPIC. The same error would occur with other external libraries such as ITK. Unfortunately the only solution is to recompile all dependent libraries with the appropriate flag, or disable them in STIR of course.

For the ecat library, this can be done as follows cd ecat # or wherever the source is make -f Makefile.unix CC="gcc -fPIC" For libraries built with CMake, use something like cmake -DBUILD_POSITION_DEPENDENT_CODE=ON ...

Visual Studio/XCode and other systems with an IDE for compilation
CMake will have created a series of directories in the build directory with the necessary projects files. For example, for Visual studio, there will be a STIR.sln with targets ALL_BUILD, INSTALL, RUN_TESTS (and projects for every for every library and executable). You would open the STIR solution, and build the relevant target. Remember to set the type of build (Release or Debug) first from your GUI.

Windows using msbuild
If you have chosen Visual Studio output, you can build via the IDE as above. However, you can also use MSBuild. This would for instance be a good choice if you want to use the Windows SDK compilers (as opposed to normal Visual Studio). This could go as follows MSBuild ALL_BUILD.vcxproj /p:Configuration=Debug MSBuild RUN_TESTS.vcxproj /p:Configuration=Debug MSBuild INSTALL.vcxproj /p:Configuration=Release
 * open a command prompt with the path set for your build environment
 * cd to the location where you instructed CMake to generate the build files
 * you can build a single project or the whole solution, e.g.
 * build all targets in Debug mode
 * run the tests in Debug mode (see also next section)
 * install all targets (compiled in Release mode)

Build from command line using CMake
Independent of what generator you used, variations on the following should work from a command prompt cmake --build. --target ALL_BUILD --config Release

= Stage 4: testing via the build system = The previous step used CMake to generate files for the build system appropriate for your OS. As already indicated there, you should use the build system to test STIR. We list the 2 most common (?) cases:

Unix-type systems: make
Still in the build directory, you type make test (Note that the Makefiles generated by cmake have test</tt> as an independent target, not depending on all</tt>. Therefore, if you change the source code, you need to make</tt> first, before doing make test</tt>.)

If one of the tests fails, you can normally find a log in Testing/Temporary/LastTest.log</tt>. You should check this out, and if you're stuck, post it to the stir-users mailing list.

If you want to run only a single test, you can do that as follows ctest -R name You can use regular expressions to match the names of any test you want to run. Further options and more details can be found at.

Windows and other systems with an IDE for compilation
As in the previous section, there should be a RUN_TESTS target available via your GUI. You should build that one. (Or you can build and run any of the test_* targets if you want to run only a single test).

You can also open a command prompt on your system, change directory to where you built STIR and use for instance

ctest -C Debug -R test_Array

if you have built the Debug version of STIR and want to execute the test_Array test only. Note that this will only work if  is in your path, otherwise you have to specify its location.

= Stage 5: Using the recon_test_pack = Don't forget to download the recon_test_pack</tt> from the STIR web-site, unpack it, and read its README.txt</tt>. Note that running these tests will be easier if you first install STIR. You can then pass the installation directory as an argument to the test scripts (or batch files).

= Optional: install STIR+MATLAB interface = These are instructions on how to install the STIR+MATLAB interface tested on a unix system with ubuntu 14.04. It relies on CmakeGui (as usual) and an extension of SWIG that has to be installed first.

Install SWIG
First, prepare your system with some packages sudo apt-get install libtool automake autoconf autogen bison Get the edited version of SWIG mkdir swig cd swig git clone https://github.com/KrisThielemans/swig.git swig_git and checkout the right branch cd swig_git git checkout KTFIX SWIG can now be installed ./autogen.sh cd .. mkdir build cd build ../swig_git/configure make sudo make install Note that the install might fail at the end if it can't find yodl2man, but we don't care. Check with that we now have the right version (should say 3.0.3) swig -version

Install STIR
Follow the instructions on this page up to the point where you started cmake-gui. check that CMake found the correct SWIG file (not the system one). If it did, replace the SWIG variable and "configure" again Then either install STIR as usual make sudo make install or you could build only the STIR+MATLAB first (just to see if it fails or not) make stirMATLAB Add path in MATLAB. E.g. addpath /usr/local/matlab
 * press configure
 * press ok
 * set CMAKE_BUILD_TYPE to Release
 * enable BUILD_SWIG_MATLAB
 * enable STIR_OPENMP
 * press configure
 * generate
 * close cmake-gui

Testing
There are a few tests in UCL-STIR/src/swig/test/matlab. Just execute these adding the directory where you installed it to your matlab path (e.g. if you choose /usr/local as your CMAKE_INSTALL_PREFIX, in MATLAB do "addpath /usr/local/matlab")

= Content license = All content on this wiki uses the Creative Commons Attribution-ShareAlike 3.0 Unported License