#------------------------------------------------------------------------------ # INSTALL.g4cmake # # 29th October Ben Morgan # # $Id: INSTALL.g4cmake,v 1.2 2010-11-18 14:34:04 gcosmo Exp $ # # Install guide for the Geant4 CMake Buildsystem # 1. Introduction to Building, Installing and Using Geant4 with CMake =================================================================== 1.1 Prerequisites ----------------- You need to have CMake version 2.6.4 or higher installed on your system. You need to have gcc and GNU Make on Linux You need to have Xcode 3 on Mac OS X (Xcode 4 has not been tested) You need to have Visual Studio on Windows (VS2010 Express has been tested) On Linux, it is recommended that you use CMake as provided by your distribution's package management system, unless this does not satisfy the version requirement above. In that case, you should install the latest Linux binary for CMake provided by Kitware available from: http://www.cmake.org/cmake/resources/software.html On Mac OS X and Windows you should install the latest CMake binary for those platforms (also available from the above link). Whilst this guide will take you through the basics of using CMake to build and install Geant4 using CMake, further detailed documentation on CMake is available from: http://www.cmake.org/cmake/help/help.html and http://www.cmake.org/cmake/help/documentation.html Whilst this guide attempts to provide a minimal guide to getting up an running, it is strongly recommended that you keep the CMake documentation to hand in case of initial problems or queries. In addition to CMake the standard list of Geant4 prerequisites are needed if you wish to build optional components of the toolkit: CLHEP (Optional, Geant4 now uses an internal CLHEP by default) Xerces-C (Optional, needed for GDML support) OpenGL (Optional, needed for OpenGL visualization support) X11 (Optional, needed for OpenGL visualization on Unices). Qt4 (Optional, needed for Qt based GUI with OpenGL visualization) Motif-X11 (Optional, needed for Motif based GUI with OpenGL visualization) It is strongly recommended that on Linux you use the system provided installs of these packages (you require both runtime AND development, -dev, packages!). On Windows and Mac OS X, we recommend using exe/msi/dmg/pkg installers provided by the package distributors (Note that Visual Studio will provide you with OpenGL). 1.2 Currently Supported Platforms --------------------------------- The CMake system will be supported on the current list of Geant4 supported platforms with CMake 2.6.4 or 2.8.x. Whilst CMake can generate buildscripts for many different tools, the Geant4 system has only been tested on: UNIX Makefiles (Linux, Mac OS X) Visual Studio (Windows 7, VS2010 Express) You are welcome to try the system with other tools such as Eclipse and Xcode, but full functionality cannot be guaranteed with these tools. We welcome user feedback and/or bug reports on these tools, and all other aspects of the CMake build system of Geant4, via the Geant4 HyperNews Forum http://hypernews.slac.stanford.edu/HyperNews/geant4/get/installconfig.html or our Bugzilla: http://bugzilla-geant4.kek.jp/ *IMPORTANT CAVEATS* - Windows Builds The Windows build is still experimental and whilst the Geant4 libraries should build without error, it has only been checked to do so on: Windows 7 Visual Studio 2010 Express You may however experience issues with building user applications aganist these libraries. Further details on this are provided in Section 3. We welcome feedback and/or bug reports on the Windows build, and these should be posted/reported to the Geant4 HyperNews or Bugzilla listed above. - Debian/Ubuntu Multiarch We do not expect the Geant4 CMake system to work completely on the latest Debian and Ubuntu (plus other Debian family Linux distribuions) due to their use of multiarch library directories: http://wiki.debian.org/Multiarch/ This is a known issue and likely to be fixed in CMake 2.8.5: http://www.cmake.org/Bug/view.php?id=12037 though even here some Geant4 custom CMake modules may need fixes. Whilst these distributions are not officially supported, we welcome feedback and/or patches to the Geant4 CMake system by Debian/Ubuntu users/developers. - Windows/Mac GUI Toolkits It is recommended that Windows and Mac users prefer the Geant4 Qt4 GUI. Note also that on Mac you can only pick Qt4 OR X11/Motif interfaces. This is due to incompatibilities between Apple's native OpenGL Framework and the OpenGL supplied with X11 on this platform. 1.3 What is Built, What is Not Built ------------------------------------ Currently supported in Geant4 CMake build: Global or granular library build (only one can be chosen however). Dynamic and optionally archive libraries. GDML support (optional, requires XercesC) TCSH Terminal UI (UNIX only) WIN32 Terminal UI (WIN32 only) Qt4 UI/Visualization (optional, requires Qt4, OpenGL) Xm UI/Visualization (optional, UNIX Only, requires X11, Motif, OpenGL) X11 RayTracer (optional, UNIX Only, requires X11) X11 OpenGL (optional, UNIX Only, requires X11, OpenGL) WIN32 OpenGL (optional, WIN32 Only, requires OpenGL) Network DAWN (optional, UNIX only) Network VRML (optional, UNIX only) Not Currently Built or Supported: Geant4Py (optional, requires Python, Boost.Python) OpenInventor (optional, requires Open Inventor implementation) Data Libraries (optional, requires network connection or local repository) Deprecated: Xaw UI/Visualization 2. Building and Installing Geant4 with the CMake system ======================================================== To get going as quickly as possible, read section 2.1 to build and install a minimal version of Geant4. If you see errors, or for more detailed usage on enabling other options like visualization drivers or tuning installation paths, consult Section 2.2. Using a build/install of Geant4 to build simulation applications is described in Section 3. 2.1 QuickStart -------------- 1) Ensure all the required prequisites listed above are installed. 2) Download the Geant4 source package from http://geant4.cern.ch 3) Unpack the source package to a location of your choice. As an illustration, this guide will assume it's been unpacked to /path/to/geant4.9.6.2 4) IF YOU ARE ON LINUX OR MAC OS X ('UNIX'): 4.1) Create a directory alongside the source directory in which to perform the build, e.g. using our directory from above $ cd /path/to $ mkdir geant4.9.6.2-build $ ls geant4.9.6.2 geant4.9.6.2-build 4.2) Change to this build directory and run cmake, pointing it to the location of the unpacked sources, e.g. carrying on from above $ cd geant4.9.6.2-build $ cmake ../geant4.9.6.2 CMake will then run to configure and generate standard Makefiles, and on Linux you should see output similar to $ cmake ../geant4.9.6.2 -- The C compiler identification is GNU -- The CXX compiler identification is GNU -- Check for working C compiler: /usr/bin/gcc -- Check for working C compiler: /usr/bin/gcc -- works -- Detecting C compiler ABI info -- Detecting C compiler ABI info - done -- setting default compiler flags for CXX -- Check for working CXX compiler: /usr/bin/c++ -- Check for working CXX compiler: /usr/bin/c++ -- works -- Detecting CXX compiler ABI info -- Detecting CXX compiler ABI info - done -- The following Geant4 features are enabled: GEANT4_USE_SYSTEM_EXPAT: Using system install of EXPAT -- Configuring done -- Generating done -- Build files have been written to: /path/to/geant4.9.6.2 On Mac OS X this output will be slightly different! 4.3) The above step generates Makefiles for building Geant4, so make can now be run: $ make -jN Where N is the number of parallel jobs you require (e.g. if you have a dual core processor, you could set N to 2). The build will now run and you should see output indicating the progress of the build and what's currently being built. 4.4) Once the build has completed, you can install Geant4 (ASSUMING you have write permission to /usr/local) with $ make install If you don't have write permission to /usr/local, you can still use your build of Geant4, without installing, see Section 3.1 for instructions. Alternately, see Section 2.2 for instructions on how to set the installation prefix. You can also use the DESTDIR standard to perform an install to a staging directory for packaging or other reasons. 5) IF YOU ARE ON WINDOWS (VISUAL STUDIO 2010 EXPRESS) 5.1) Start the CMake GUI (cmake-gui, available from a Desktop shortcut or from the CMake entry under the Start Menu). 5.2) Use the 'Browse Source' button at the top of the GUI to browse to and set the entry to the unpacked Geant4 source directory. 5.3) Use the 'Browse Build' button below the 'Browse Source' button to set the build directory. As above, we recommend that you create this alongside your unpacked source tree. The directory does not need to exist (CMake will ask later if you wish to create it), but it should be located somewhere you have write permission to. 5.4) Click on the 'Configure' button in the bottom left hand corner of the GUI window. Click 'Yes' in the pop-up window which will appear if your chosen build directory doesn't exist. 5.5) A pop up window will appear asking you to select a generator. If you have Visual Studio installed, the drop-down box should already be selected with this. If not, select the Visual Studio you have installed, and double check that the 'Use default native compilers' radio box is checked. Then click on the 'Finish' button. The configuration will now run, and you will see output in the Text Window at the bottom of the GUI window. You may see the (highlighted in red) warnings: i) From InstallRequiredSystemLibraries.cmake regarding 'system runtime library does not exist' This can safely be ignored because it only affects the generation of binary installers for Geant4. 5.6) Click on the 'Generate' button in the bottom left hand corner of the GUI window to create the Visual Studio Solution file. 5.7) Start Visual Studio and open the 'Geant4.sln' file located in the build directory you created in 5.3 above. 5.8) In the Solution Explorer, right click on the 'ALL_BUILD' target, and select 'Build' in the popup menu. The project will now start building. Note that by default, you will get a Debug build. Given the caveats on the Geant4 Windows build, we strongly recommend that you use this default. 5.9) In the Solution Explorer, right click on the 'INSTALL' target. You will need write permission to C:\Program Files\Geant4 for this step to work. If you do not, then you can still use your build of Geant4, see Section 3, or you can modify the installation prefix as described in Section 2.2. 2.2 Additional Build Options ---------------------------- Section 2.1 gives the minimal proceedure to build and install Geant4. Many additional options can be passed to CMake to adjust the way the Geant4 libraries are built, enable optional modules and tune installation paths. On the command line, these options may be set by passing them to cmake via -D flags: $ cmake -D= /path/to/source For example, if we want to change the installation prefix on Linux from /usr/local to /usr, we could do $ cmake -DCMAKE_INSTALL_PREFIX=/usr /path/to/source However, it is often easier to use the ccmake Curses interface or the cmake-gui GUI interface so set these options. Here, options may be set by selecting/clicking the entry for the option and entering information directly or via GUI tools as needed. Please see the CMake documentation for more information on ccmake and cmake-gui, although both are generally intuitive to use out of the box. Options are divided into 'Standard' options, which anybody can set directly, and 'Advanced' options, which should not be touched unless you know what you are doing or need very fine control over the build. Some options enable parts of Geant4 which require Third Party packages, and consequently these packages are searched for. Hence there are also options which control where CMake should look for these packages. It should also be noted that some options are also platform dependent. SPECIAL NOTE FOR MAC OS X: You can only select Qt4 OR X11/Xm visualization. Qt4 will take precedence if you try and choose both. We enforce this choice because Qt4 uses Apple's Framework based installation of OpenGL, whereas the X11 based OpenGL drivers require the X11 version of OpenGL, and both cannot be reconciled in the current G4OpenGL driver. = Standard Options = Note that we list these options here in logical order. In ccmake and cmake-gui, they will be listed alphabetically. * CMAKE_BUILD_TYPE : (DEFAULT : Release) Controls the type of build, at present only the additional flags passed to the compiler. It defaults to 'Release' which gives an optimized build with no debugging symbols. The most useful values are Release : Optimized build, no debugging symbols Debug : Debugging symbols RelWithDebInfo : Optimized build with debugging symbols Note that if you use a build system which supports multiconfiguration builds (e.g. Xcode, Visual Studio), this variable has no effect (You choose the build type through the IDE interface!). * CMAKE_INSTALL_PREFIX : Controls the installation prefix for Geant4. Equivalent to --prefix in Autotools. Its default is platform dependent: UNIX : /usr/local WINDOWS : C:\Program Files\Geant4 It should be supplied as an absolute path, otherwise CMake will interpret it relative to your build directory. The resulting install structure is described in Section 3 below. See also the CMAKE_INSTALL_XXX Advanced Options. * GEANT4_USE_SYSTEM_CLHEP : (DEFAULT : OFF | ON if CLHEP_ROOT_DIR set) If set to ON, build Geant4 with an external install of CLHEP. You SHOULD NOT set this unless your usage of Geant4 mandates a specific external CLHEP (e.g. if your experiment's software uses CLHEP in other tools and requires consistent use of the same CLHEP across the software). If the CLHEP_ROOT_DIR option is not set, CLHEP will be searched for under standard system paths. REQUIRES : CLHEP installation. * CLHEP_ROOT_DIR : If you wish GEANT4 to use a specific installation of CLHEP, set this variable to point to the root install directory of the CLHEP installation you wish to use. This directory should contain the include and lib subdirectories containing the CLHEP headers and libraries respectively. If these are not sufficient to locate CLHEP, see the Advanced CLHEP_XXX options. * GEANT4_USE_G3TOG4 : (DEFAULT : OFF) If set to ON, build the rztog4 converter application. REQUIRES : Fortran compiler, CERNLIB * GEANT4_USE_GDML : (DEFAULT : OFF | ON if XERCESC_ROOT_DIR is set) If set to ON, build the G4persistency library with GDML support. REQUIRES : Xerces-C installation (see XERCESC_ROOT_DIR option). * XERCESC_ROOT_DIR : If your Xerces-C installation is in a non-standard location, set this variable to the root directory of the installation (i.e. the directory containing the include and lib subdirectories for Xerces-C). If this is not sufficient to locate Xerces-C, see the Advanced XERCESC_XXX options. If you have a system install of Xerces-C, you SHOULD NOT need to set this variable. * GEANT4_USE_QT : (DEFAULT : OFF) If set to ON, build Qt4 based UI and Visualization Interface to Geant4. REQUIRES : Qt4 and OpenGL installation (See QT_QMAKE_EXECUTABLE option) * QT_QMAKE_EXECUTABLE : If your Qt4 installation is in a non-standard location, set this variable to point to the qmake executable of the Qt4 installation you wish to use. If you have a system install on Linux or the binary SDK install from Nokia on other platforms, you SHOULD NOT need to set this variable. * GEANT4_USE_XM : (DEFAULT : OFF & UNIX only) If set to ON, build Xm (X11-Motif) based UI and Visualization Interface to Geant4. REQUIRES : Xm and OpenGL installation. * GEANT4_USE_OPENGL_X11 : (DEFAULT : OFF & UNIX only) If set to ON, build the G4OpenGL library with basic X11 support. REQUIRES : X11, OpenGL installation. * GEANT4_USE_RAYTRACER_X11 : (DEFAULT : OFF & UNIX only) If set to ON, build the G4RayTracer library with X11 support. REQUIRES : X11 installation. * GEANT4_INSTALL_EXAMPLES : (DEFAULT : OFF) If set to ON, the Geant4 example application source code will be installed to the DATADIR selected for Geant4 (See Section 3). * GEANT4_INSTALL_DATA : (DEFAULT : ALWAYS OFF) If set to ON, options to install the Geant4 data libraries will be provided. NOT IMPLEMENTED YET. = Advanced Options = In general you should never need to touch the Advanced options. We note the Geant4 specific options here for completeness and for advanced users and developers only. They are to be used at your own risk as changing them may cause the build to fail or to produce unusable libraries. Advanced options are not displayed by default in the ccmake and cmake-gui interfaces, but can be toggled on and off (press 't' in ccmake, click the 'advanced' check box in cmake-gui). Note that displaying advanced options will also display the large number of advanced options for tuning CMake and the locations of Third Party packages. If you do need to edit the advanced options, it is only those listed below you should ever need to handle, UNLESS the platform you are working on has trouble building Geant4. * CMAKE_INSTALL_BINDIR : (DEFAULT : bin) Installation directory for user executables. It can be supplied as a path relative to CMAKE_INSTALL_PREFIX, or an absolute path. * CMAKE_INSTALL_INCLUDEDIR : (DEFAULT : include) Installation directory for C/C++ headers. It can be supplied as a path relative to CMAKE_INSTALL_PREFIX, or an absolute path. * CMAKE_INSTALL_LIBDIR : (DEFAULT : lib(+?SUFFIX)) Installation directory for object code libraries It can be supplied as a path relative to CMAKE_INSTALL_PREFIX, or an absolute path. The default should *generally* pick the correct arch specific library directory SUFFIX by default. * CMAKE_INSTALL_DATAROOTDIR : (DEFAULT : share) Installation directory for read-only architecture-independent data files. It can be supplied as a path relative to CMAKE_INSTALL_PREFIX, or an absolute path. * BUILD_SHARED_LIBS : (DEFAULT : ON) If set to ON, build Geant4 shared libraries. * BUILD_STATIC_LIBS : (DEFAULT : OFF) If set to ON, build Geant4 static libraries. * GEANT4_BUILD_GRANULAR_LIBRARIES : (DEFAULT : OFF) If set to ON, build Geant4 libraries in granular mode. WARNING : THIS OPTION IS FOR DEVELOPERS ONLY. NO SUPPORT IS, OR WILL BE, PROVIDED FOR USER APPLICATIONS BUILT WITH GRANULAR LIBS!! * GEANT4_BUILD_STORE_TRAJECTORY : (DEFAULT : ON) If set to ON, store trajectories in event processing. It can be switched OFF to give a degree of performance improvement, but you will NOT be able to visualize events. * GEANT4_BUILD_VERBOSE_CODE : (DEFAULT : ON) If set to ON, build Geant4 libraries with extra verbosity. It can be switched OFF to give a degree of performance improvement, but you will not have as much information should you run into problems or need to debug. * GEANT4_USE_NETWORKDAWN : (DEFAULT : OFF & UNIX Only) If set to ON, build network/server/client for DAWN visualization driver. * GEANT4_USE_NETWORKVRML : (DEFAULT : OFF & UNIX Only) If set to ON, build network/server/client for VRML visualization driver. In addition to these advanced options, there are others which can be tuned should you have trouble locating Third Party packages. These are generally paths to the libraries or header paths of these packages. We only document those for modules supplied by Geant4. For all CMake supplied modules, you should consult the CMake documentation. * CLHEP_INCLUDE_DIR : Should point to the include path for CLHEP headers. In other words, it should be the directory that contains CLHEP/Units/defs.h (e.g. if you have /usr/local/include/CLHEP/Units/defs.h, then CLHEP_INCLUDE_DIR is /usr/local/include) * CLHEP_LIBRARY : Should point to the full path to the CLHEP library, e.g /usr/lib/libCLHEP.so * XERCESC_INCLUDE_DIR : Should point to the include path for Xerces-C headers. In other words, it should be the directory that contains xercesc/util/XercesVersion.hpp (c.f. how CLHEP_INCLUDE_DIR is set) * XERCESC_LIBRARY : Should point to the full path to the Xerces-C library, e.g. /usr/lib/libxerces-c.so 2.3 Advanced Build Topics ------------------------- This section is generally for Geant4 developers only, but these techniques are also applicable if you plan to use CMake to develop your Geant4 applications (NB they are a property of CMake, NOT Geant4 or its use of CMake). The build structure of having a build directory pointing to a source tree permits a very useful development pattern. You can have multiple build directories, each with its own configuration, e.g. 'Release-Qt4' 'Debug-Qt4', but only need to edit one source tree. This is especially powerful when combined with incremental builds, because there is no need to do a clean and rebuild everytime you want to change the configuration (e.g. Release -> Debug). Naturally, this comes at the cost of some disk space, but can be an enormous time saver for development - configure once, build multiple times. Each Geant4 library is a target in CMake, and so each can be built individually. These targets appear in your IDE interface, or with Makefiles you can simply type 'make help' to print a list of available targets. Each library is linked to its dependents, so rebuilds following updates from svn will automatically pick up any changes in the dependencies of your library and rebuild accordingly. In fact even *changes to the build system* will be picked up, so you do not (always!) need to reconfigure when updating from svn. 3 Using a Build/Install of Geant4 ================================= Geant4 provides three main toolchains for building Geant4 user applications against the CMake build of Geant4. These are, in order of recommendation: 1. CMake via the find_package mechanism of CMake 2. Geant4 GNU Make toolchain. 3. geant4-config script (UNIX only) The first option is new and allows you to use CMake to build applications using the Geant4 toolkit. The tools for this are still under development, but we recommend that you familiarize yourself with this toolchain as it is already very usable and provides you with all the nice features of CMake. The second option is essentially reproduces the GNUmakefile system used to build many user applications and will therefore be the most familiar. If your applications already use the Geant4 supplied GNU Make fragment system (e.g. binmake.gmk), then these can continue to use this system whilst taking advantage of CMake to just build Geant4. The final option provides a Bourne shell script which can be queried using standard arguments such as '--prefix', '--cflags' to discover relevant information on the Geant4 build such as header paths and libraries to link to. This is most useful if you neither wish to use CMake or the Geant4 GNU Make system to build application using Geant4. However, please not that geant4-config is still under development and is not yet totally feature complete. We welcome the contribution of scripts and plugins for the use of Geant4 with other build tools. 3.1 Build Caveats ----------------- Geant4 no longer supply tools to set the environment variables needed to locate the Geant4 Data Libraries such as G4NDL and G4EMLOW. Work is in progress to install these as part of the CMake build, but until then you should install these by hand as needed by your application (your physics list may well not need them). The environment variables that require setting for each library and the library they correspond to are as follows: G4LEDATA -> Unpacked location of G4EMLOW..tar.gz G4LEVELGAMMADATA -> Unpacked location of G4PhotonEvaporation..tar.gz G4NEUTRONHPDATA -> Unpacked location of G4NDL..tar.gz G4RADIOACTIVEDATA -> Unpacked location of G4RadioactiveDecay..tar.gz G4ABLADATA -> Unpacked location of G4ABLA..tar.gz G4REALSURFACEDATA -> Unpacked location of G4RealSurface..tar.gz G4NEUTRONXSDATA -> Unpacked location of G4NEUTRONXSDATA..tar.gz G4PIIDATA -> Unpacked location of G4PII..tar.gz Where corresponds to the latest distribution of each library set, which are available from http://geant4.web.cern.ch/geant4/support/download.shtml 3.2 Build and Install Tree Structure ------------------------------------ As mentioned earlier, you do not need to install Geant4 to build applications against it. All three toolchains can be used either from the Geant4 'Build Tree', i.e. the directory in which you ran CMake, or, if you installed Geant4, from its 'Install Tree', i.e. the directory(ies) you installed it to. The toolchains provide CMake/shell scripts in the Build and Install trees specially configured to point to the Geant4 headers and libraries appropriate for that tree. The build tree where you ran CMake has the following structure and toolchain files (N.B. some parts omitted for clarity). +- CMAKE_BINARY_DIR +- CMakeCache.txt +- CMakeFiles/ +- geant4-config +- geant4-environment-setup.sh +- geant4-environment-setup.csh +- Geant4Config.cmake +- Geant4ConfigVersion.cmake +- Geant4LibraryDepends.cmake +- UseGeant4.cmake Where CMAKE_BINARY_DIR is CMake's name for where you ran it. Here, the toolchain files are 1 - CMake build : Geant4Config.cmake, UseGeant4.cmake 2 - GNU make build : geant4-environment-setup.(c)sh 3 - geant4-config build : geant4-config (will only be present on UNIX) If you choose the default installation paths, then the install tree will have the following structure, relative to CMAKE_INSTALL_PREFIX: +- CMAKE_INSTALL_PREFIX +- bin/ | +- geant4-config (UNIX ONLY!!!!) | +- G4global.dll (WINDOWS ONLY!!!!) +- include/ | +- Geant4/ | | +- G4global.hh | | +- ... | | +- CLHEP/ (ONLY IF YOU BUILD THE INTERNAL CLHEP!!) +- lib/ (THE NAME OF THIS DIRECTORY IS ARCH/PLATFORM DEPENDENT) | +- libG4global.so (AND/OR .a, OR G4Global.lib on WINDOWS!!) | +- ... | +- Geant4-/ | +- Geant4Config.cmake | +- Geant4ConfigVersion.cmake | +- Geant4LibraryDepends.cmake | +- Geant4LibraryDepends-.cmake | +- UseGeant4.cmake | +- - (SOFTLINK -> ..) +- share +- Geant4- +- geant4-environment-setup.sh +- geant4-environment-setup.csh +- config/ +- binmake.gmk +- ... Here, the files of interest are, relative to CMAKE_INSTALL_PREFIX: 1 - CMake build : lib/Geant4-/Geant4Config.cmake, lib/Geant4-/UseGeant4.cmake 2 - GNU make build : share/geant4-environment-setup.(c)sh 3 - geant4-config build : bin/geant4-config 3.3 Building a Geant4 Application with CMake (ALL PLATFORMS) ------------------------------------------------------------ To build a Geant4 application using CMake, you need to write a CMake script to find Geant4, set it up, build you application and then link it to the geant4 libraries. Whilst this sounds compilicated, you can actually get up and running quite quickly. For the purposes of illustration, we'll show how the most basic Geant4 application, exampleN01 can be built using CMake. This has the typical structure of a Geant4 application (full path is for illustration only): +- /home/geant4/exampleN01 +- exampleN01.cc +- include/ | +- ExN01DetectorConstruction.hh | +- ExN01PrimaryGeneratorAction.hh | +- ExN01PhysicsList.hh +- src/ +- ExN01DetectorConstruction.cc +- ExN01PrimaryGeneratorAction.cc +- ExN01PhysicsList.cc To build with CMake, we add the standard CMake script, CMakeLists.txt at the top level: +- /home/geant4/exampleN01 +- CMakeLists.txt +- exampleN01.cc +- include/ | +- ExN01DetectorConstruction.hh | +- ExN01PrimaryGeneratorAction.hh | +- ExN01PhysicsList.hh +- src/ +- ExN01DetectorConstruction.cc +- ExN01PrimaryGeneratorAction.cc +- ExN01PhysicsList.cc This test file tells CMake how to build our application and in this case is very simple. We'll write it all out, show how we can then build the app, and then return to see what the commands mean: # - CMakeLists.txt for Geant4 exampleN01 cmake_minimum_required(VERSION 2.6.4 FATAL_ERROR) project(exampleN01) find_package(Geant4 REQUIRED) include(${Geant4_USE_FILE}) GEANT4_COLLATE_APPLICATION_SOURCES(EXAMPLEN01_SOURCES) add_executable(exampleN01 ${EXAMPLEN01_SOURCES) target_link_libraries(exampleN01 ${Geant4_LIBRARIES}) # End of CMakeLists.txt With that file in place, we can then build much as we did for Geant4 earlier. We do however need to tell CMake where to find Geant4. We do this by passing CMake the location of the 'Geant4Config.cmake' file we saw above in the build and install trees - and we can choose either (hence again, you don't have to install Geant4 to be able to use it). So, let's assume we built Geant4 in +- /home/geant4/build +- Geant4Config.cmake and installed it to +- /usr/local +- lib/ +- Geant4-9.6.2 +- Geant4Config.cmake where we've illustrated the location of the Geant4Config files in the two trees. So to build and run our exampleN01 application against the Geant4 build tree, we do: $ cd /home/geant4/exampleN01 $ mkdir build-N01 $ cd build-N01 $ cmake -DGeant4_DIR=/home/geant4/build .. $ make -jN $ ./exampleN01 Here, the Geant4_DIR option is passed with the location of Geant4Config.cmake in our example Build Tree. If you're running on Windows, you can pass Geant4_DIR in through the cmake-gui by clicking on the 'Add Entry' button to add a variable to the cache CMake keeps and naming this 'Geant4_DIR' with type 'PATH' and using the browser to set the value to the location of your Geant4 Build Tree. Equally, we could build and run our exampleN01 application against the Geant4 install tree, instead doing: $ cd /home/geant4/exampleN01 $ mkdir build-N01 $ cd build-N01 $ cmake -DGeant4_DIR=/usr/local/lib/geant4-9.6.2 .. $ make -jN $ ./exampleN01 So you choose either to build with, or even both (just create two build directories for exampleN01!). Returning to the CMakeLists.txt file we wrote for exampleN01, what does each bit do? We'll briefly note them here, but you should refer to the CMake manual for further details. -> Comments in CMake scripts always begin with '#' # - CMakeLists.txt for Geant4 exampleN01 -> This requires that the CMake used to run this script must be version 2.6.4 or higher cmake_minimum_required(VERSION 2.6.4 FATAL_ERROR) -> This declares the name of the CMake project we're building, by default will enable support for C and C++ languages. project(exampleN01) -> Find the package named 'Geant4'. The REQUIRED argument means CMake will fail if geant4 cannot be located. find_package(Geant4 REQUIRED) -> Include the file listed in the Geant4_USE_FILE variable, this variable is set when Geant4 is found. It's actually set in the Geant4Config.cmake file and Geant4_USE_FILE will actually point to the UseGeant4.cmake file we saw earlier. This will setup things like compiler definitions and include paths for Geant4 so we don't have to. include(${Geant4_USE_FILE}) -> This is a macro supplied by the UseGeant4.cmake file. It collates all the sources and headers in and below the current directory, and sets the variable EXAMPLEN01_SOURCES to hold the paths to these files. GEANT4_COLLATE_APPLICATION_SOURCES(EXAMPLEN01_SOURCES) -> Declare an executable target named exampleN01 and build it from the files listed in the EXAMPLEN01_SOURCES variable add_executable(exampleN01 ${EXAMPLEN01_SOURCES) -> Link the target named exampleN01 to the library targets listed in the Geant4_LIBRARIES variable. That is set eariler in the Geant4Config.cmake file. target_link_libraries(exampleN01 ${Geant4_LIBRARIES}) # End of CMakeLists.txt More advanced usage of the find_package command is possible. For instance, if you wanted to build an application that could use the Qt4 GUI interface to Geant4, you could call find_package with find_package(Geant4 REQUIRED COMPONENTS qt) include(${geant4_USE_FILE}) CMake would then fail if it found Geant4, but the build/install tree found was not built with Qt support. If Qt support was available, your application would then be compiled with the appropriate flags to enable it. You can also pass version numbers to select a minimum version of Geant4: find_package(Geant4 9.6.2 REQUIRED) or even an exact version find_package(Geant4 9.6.2 EXACT REQUIRED) There are many other things you can do with find_package and CMake to build, install and package geant4 based applications. You should consult the Geant4Config.cmake and UseGeant4.cmake files for further information, and of course the CMake documentation (links earlier). 3.3.1 IMPORTANT NOTE FOR WINDOWS USERS -------------------------------------- Whilst using CMake to build your applications as outlined above will generally give a functioning *build*, there is a known issue, and one potential gotcha, with application builds which has not been completely resolved as of the 9.5 beta release. 1) CMAKE_CXX_FLAGS. As described above, the inclusion of the UseGeant4.cmake file will append the recommended Geant4 CXX flags to the already existing CMAKE_CXX_FLAGS. CMake's defaults for these flags on Windows currently cause a conflict with the flags used to build Geant4, and you may therefore see low level exceptions being emitted when debugging your application. We therefore recommend that when you configure your Geant4 application with CMake that you use the UseGeant4.cmake file and: i) Tick the 'Advanced' tick box in the top section of the cmake-gui window. ii) In the Variable 'Name : Value' listings, open the 'CMAKE' section by clicking on the right arrow on the left of 'CMAKE'. iii) Locate the entries for: CMAKE_CXX_FLAGS CMAKE_CXX_FLAGS_DEBUG CMAKE_CXX_FLAGS_MINSIZEREL CMAKE_CXX_FLAGS_RELEASE CMAKE_CXX_FLAGS_RELWITHDEBINFO and clear the values in each one (i.e. they should end up as blank strings). iv) Press the 'Configure' button to reconfigure, and then 'Generate'. This should result in a project which is built with the same flags as the Geant4 libraries. 2) If you built Geant4 dynamic libraries, you will need to add the path to the DLLs to your system PATH variable, or tweak the PATHs used by the project in Visual Studio. We apologize for these issues, and are working on resolutions for the 2011 release. As noted above we welcome feedback and suggestions for improvement via our HyperNews forum or Bugzilla reporting system. 3.4 Building a Geant4 Application Using Geant4 GNU Make (UNIX ONLY) ------------------------------------------------------------------- To use the backward compatible Geant4 GNU Make toolchain, you need to setup environment variables used by this toolchain. To do this, you need to source one the geant4-environment-setup script we saw earlier in the Build and Install Trees for your shell. So, let's assume we built Geant4 in +- /home/geant4/build +- geant4-environment-setup.(c)sh and installed it to +- /usr/local +- share/ +- Geant4-9.6.2 +- geant4-environment-setup.(c)sh where we've illustrated the location of the geant4-environment-setup.(c)sh files in the two trees. If you want to build your application using the Build Tree of Geant4, simply source the relevant script in the Build Tree, e.g. $ source /home/geant4/build/geant4-environment-setup.(c)sh Or, if you want to build your application using the Install Tree of Geant4, simply source the script in the Install Tree, e.g. $ source /usr/local/share/Geant4-9.6.2/geant4-environment-setup.(c)sh Your environment will then be configured to build applications using the Geant4 GNU Makefile system as described in the Application Developers Guide: http://geant4.web.cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/ If you have existing Geant4 Applications using this Makefile system, they should work directly. Whilst every attempt has been made to keep backward compatibility, it cannot be completely guaranteed. In case of issues, you can run a Geant4 GNU Make based makefile using $ make CPPVERBOSE=1 to see the exact sequence of commands used. This can be of use in identifying any issues with this toolchain. 3.4 Building a Geant4 Application on UNIX using geant4-config (UNIX ONLY) ------------------------------------------------------------------------- In many cases, you many not want to use CMake or the Geant4 GNU Make toolchain to build your user applications. For these cases on UNIX only, we provide the geant4-config script. Again, let's assume we built Geant4 in +- /home/geant4/build +- geant4-config and installed it to +- /usr/local +- bin/ +- geant4-config where we've illustrated the location of the geant4-config script in the two trees. The script may be used either directly from a Geant4 Build Tree, e.g. $ sh /home/geant4/build/geant4-config (On CMake 2.8 and higher, it is also directly executable) Or from the install of Geant4: $ /usr/local/bin/geant4-config It provides the following interface: # - Usage: geant4-config [OPTION...] --prefix output installation prefix of Geant4 --version output version for Geant4 --libs output all linker flags --cflags output all preprocessor and compiler flags --libs-without-gui output linker flags without GUI components --cflags-without-gui output preprocessor and compiler flags without GUI components --has-feature FEATURE output yes if FEATURE is supported, or no if not supported Known Features: clhep[yes|no] expat[yes|no] gdml[yes|no] qt[yes|no] motif[yes|no] raytracer-x11[yes|no] opengl-x11[yes|no] Help options -?, --help show this help message --usage display brief usage message # - It can be then be used in your own UNIX based toolchain as you see fit. 4. KNOWN ISSUES/TO DO LIST ========================== Whilst the Geant4 CMake system is almost feature complete, there are still a few known issues with the structure and interface, and items to be improved or added. 4.1 Interlibrary dependencies * Libraries are currently overlinked - proper modularization of the libraries is being worked on. On Mac OS X this does mean that you will see warnings like ld: warning: duplicate dylib /usr/local/lib/libG4FR.dylib though the Darwin linker seems to resolve any linking issues and create usable apps. 4.2 OpenInventor Support * OpenInventor visualization is not currently built. There is no technical limit here other than time pressures, and the implementation of a FindInventor.cmake module that can account for all Inventor implementations. 4.3 Geant4Py Support * The Geant4 Python wrapping is not currently built. No technical limitation other than time. 4.2 Windows Builds * The development of the Geant4 CMake buildsystem has focussed on using Visual Studio as the build tool. Inconsistencies or errors may therefore arise when using other tools on Windows. 4.3 Windows DLLs * These are provided as is and we cannot guarantee full functionality on all Windows Systems and Visual Studio versions. Whilst Geant4 builds without error on Windows 7 + VS2010 Express, a full test suite has not been run. User applications on this system also build, but may not run with complete success. 4.4 Windows Application Builds * As noted in Section 3, there are some known issues/gotchas with building user applications on Windows. 4.4 Binary Packaging * A rudimentary CPack based system is in place, but this is only really intended to generate source packages. Work is underway to use CPack to create binary NSIS, PackageMaker, rpm and deb installers for Geant4. We welcome feedback, suggestions for improvement and bug reports on the CMake system via our HyperNews Forum or Bugzilla system!