GEANT4.9.5 Install with CMAKE

#------------------------------------------------------------------------------

# 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.5.0

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.5.0-build

$ ls

geant4.9.5.0 geant4.9.5.0-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.5.0-build

$ cmake ../geant4.9.5.0

CMake will then run to configure and generate standard Makefiles,

and on Linux you should see output similar to

$ cmake ../geant4.9.5.0

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

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<G4OPTION>=<G4OPTIONVALUE> /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.<VERSION>.tar.gz

G4LEVELGAMMADATA -> Unpacked location of G4PhotonEvaporation.<VERSION>.tar.gz

G4NEUTRONHPDATA -> Unpacked location of G4NDL.<VERSION>.tar.gz

G4RADIOACTIVEDATA -> Unpacked location of G4RadioactiveDecay.<VERSION>.tar.gz

G4ABLADATA -> Unpacked location of G4ABLA.<VERSION>.tar.gz

G4REALSURFACEDATA -> Unpacked location of G4RealSurface.<VERSION>.tar.gz

G4NEUTRONXSDATA -> Unpacked location of G4NEUTRONXSDATA.<VERSION>.tar.gz

G4PIIDATA -> Unpacked location of G4PII.<VERSION>.tar.gz

Where <VERSION> 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-<VERSION>/

| +- Geant4Config.cmake

| +- Geant4ConfigVersion.cmake

| +- Geant4LibraryDepends.cmake

| +- Geant4LibraryDepends-<MODE>.cmake

| +- UseGeant4.cmake

| +- <G4SYSTEM>-<G4COMPILER> (SOFTLINK -> ..)

+- share

+- Geant4-<VERSION>

+- 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-<VERSION>/Geant4Config.cmake,

lib/Geant4-<Version>/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.5.0

+- 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.5.0 ..

$ 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.5.0 REQUIRED)

or even an exact version

find_package(Geant4 9.5.0 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.5.0

+- 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.5.0/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!