Installing STIR with CMake

This page is under construction

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 two steps: you first 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

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 libncurses-dev libX11-dev libboost-dev tcsh python

(prefix with \texttt{sudo} for Ubuntu).

Mac OS X

You need the development environment. It's probably a good idea to install MacPorts. Then you should be able to use the following:

sudo port install boost cmake

cygwin on Windows

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

Other systems or alternatives

You can use these also if you don't have super-user permission.

• Download CMake from [1] and install.
• Download Boost from [2]. 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.

Step 2: Run cmake

Launching CMake

If you have Windows or MacOSX, CMake comes as an application with a nice GUI. After launching it, you first select the source directory (STIR) 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/MacOSX you will probably be using make to build things. In that case, you want different build directories for every type of build (Debug or Release) you want to make. On Windows when using Visual Studio, you can build different versions from one CMake configuration).

On Unix/linux (or MacOSX from a terminal window), you have to use a slightly more basic user interface. You would launch this as follows.

mkdir STIR-bin
cd STIR-bin
mkdir Release
cd Release
ccmake ../../STIR

Configuring the STIR build

Once CMake has started, you have to press the 'Configure' button (or c key). In this step, CMake will try to find out as much as it can about your set-up. For instance, it will check what your default compiler is, where the C++ include files are located, 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). Similarly, for the ECAT LLN library you can specify the location of its include files and the library you want to link with.

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.

 AVW_ROOT_DIR                                                                  
 BOOST_ROOT                                                                    
 BUILD_SHARED_LIBS                OFF                                          
 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_LLN_MATRIX               OFF                                          
 DISABLE_RDF                      OFF                         
 DISABLE_STIR_LOCAL               OFF                          
 GRAPHICS                         X                                            
 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_LOCAL                       /home/kris/devel/STIR/local        
 STIR_MPI                         OFF                                           
 STIR_OPENMP                      OFF                                          

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.

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

Configuration flags

• 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 fo OPENMP reconstruction. This will then look for OPENMP libraries on your system if necessary.

• 'STIR_LOCAL' can be used to extend STIR with your own files. The needs further documentation.

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 -march-native flag. You can do this by changing the CMAKE_CXX_FLAGS_RELEASE setting. To do this, you wil have to toggle Advanced Mode on.

Stage 2: 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 just list the 2 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 using

make test

(Note that the Makefiles generated by cmake have test as an independent target, not depending on all. Therefore, if you change the source code, you need to make first, before doing make test.)

You would normally finish with

make install

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