Editing Installing STIR with CMake (section)

= Step 2: Run cmake =
== Launching CMake==
=== Setting your environment ===
You might need to set your environment correctly first such that CMake finds the correct libraries etc. Examples are
* [https://docs.python.org/3/tutorial/venv.html Python virtual environments] (e.g. via <tt>conda activate</tt> or similar)
* The CERN ROOT library for GATE simulations comes with a [https://github.com/root-project/root/blob/master/config/thisroot.sh 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'', <b>not</b> ''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.
<pre>
cd /wherever/it/is/STIR
cd ..
mkdir STIR-bin
cd STIR-bin
mkdir Release
cd Release
ccmake ../../STIR
</pre>
If you want to use a non-default compiler,
please check [http://www.cmake.org/Wiki/CMake_FAQ%23How_do_I_use_a_different_compiler.3F 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, <b>you will probably want to set ''CMAKE_BUILD_TYPE'' to ''Release''</b> (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)
<pre>
 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                                    
</pre>
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 [[#Setting your environment]].

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 [http://swig.org 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.

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

=== 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 <tt>-Ofast</tt> (from gcc 4.6) and <tt>-march=native</tt> flags. Intel C++ should benefit from the <tt>-fast</tt> flag. You can do this by changing the <tt>CMAKE_CXX_FLAGS_RELEASE</tt> setting. To do this, you will have to toggle ''Advanced Mode'' on.