lars/geant4
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
b1eb5424d2e561eed732e8a9b976b16e7f281856
geant4/cmake/INSTALL.g4cmake
T
Gabriele Cosmo b1eb5424d2 Import Geant4 9.5.0 source tree
2016-06-09 16:46:55 +02:00

1064 lines
44 KiB
Plaintext
Raw Blame History

#------------------------------------------------------------------------------
# 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!
Reference in New Issue View Git Blame Copy Permalink