------------------------------------------------
 The Virtual Monte Carlo examples
 Copyright (C) 2007 - 2014 Ivana Hrivnacova
 All rights reserved.

 For the licensing terms see geant4_vmc/LICENSE.
 Contact: root-vmc@cern.ch
-------------------------------------------------

 Building examples
 ==================

 Since version 3.00, VMC examples are installed with CMake.
 The VMC examples libraries require ROOT installation, the VMC examples programs
 are built against Geant3 with VMC or Geant4 VMC libraries.

 To install all examples:

 1. First get the Geant4 VMC source from the Download page, as the examples are
    provided within this package. We will assume that the Geant4 VMC package
    sits in a subdirectory
    /mypath/geant4_vmc

 2. Create build directory alongside our source directory for installation with
    Geant4:
    $ cd /mypath
    $ mkdir examples_build_g4
    $ ls
    geant4_vmc examples_build_g4

    and/or for installation with Geant3:
    $ cd /mypath
    $ mkdir examples_build_g3
    $ ls
    geant4_vmc examples_build_g3

 3. To configure the build, change into the build directory and run CMake with
    either -DVMC_WITH_Geant4
    $ cd /mypath/example_build_g4
    $ cmake -DCMAKE_INSTALL_PREFIX=/mypath/examples_install_g4 \
        -DVMC_WITH_Geant4=ON \
        -DGeant4VMC_DIR=/mypath/geant4_vmc_install/lib64/Geant4VMC-3.0.0 \
        /mypath/geant4_vmc/examples

    or -DVMC_WITH_Geant3.
    $ cd /mypath/example_build_g3
    $ cmake -DCMAKE_INSTALL_PREFIX=/mypath/examples_install_g3 \
        -DVMC_WITH_Geant3=ON \
        -DGeant3_DIR=/mypath/geant3_install/lib64/Geant3-2.0.0 \
        /mypath/geant4_vmc/examples

    If ROOT and Geant4 environment was defined using thisroot.[c]sh and
    geant4.[c]sh scripts, there is no need to provide path to their installations.
    Otherwise, they can be provided using -DROOT_DIR and -DGeant4_DIR cmake options.

 4. After the configuration has run, CMake will have generated Unix Makefiles for building
    examples. To run the build, simply execute make in the build directory:
    $ make -jN

    where N is the number of parallel jobs you require (e.g. if your machine has a dual
    core processor, you could set N to 2).

    If you need more output to help resolve issues or simply for information, run make as
    $ make -jN VERBOSE=1

 5. Once the build has completed, you can install examples to the directory you specified
    earlier in CMAKE_INSTALL_PREFIX by running
    $ make install

    This will install examples libraries in lib[64] and executables in bin directory in
    CMAKE_INSTALL_PREFIX directory.

 VMC Examples Build Options
 ===========================

 Overview of available options and their default values:

 VMC_WITH_Geant4    Build with Geant4   OFF
 VMC_WITH_Geant3    Build with Geant3   OFF

 Geant4 VMC build options are automatically exported in Geant4VMCConfig.cmake. If Geant4 VMC
 was built with VGM, the VGM installation path has to be provided via -DVGM_DIR option.

 Running examples
 =================

 First, make sure that you have included all libraries paths in your shared library path.

 For all MCs:
 /your_path/root/lib
 /your_path/vmc_install/lib[64]

 For Geant3 only:
 path to Pythia6 library
 /your_path/geant3_install/lib[64]
 /your_path/examples_install_g3/lib[64]

 For Geant4 only:
 /your_path/geant4_install/lib[64]
 /your_path/geant4_vmc_install/lib[64]
 /your_path/examples_install_g4/lib[64]

 Running examples from Root session
 -----------------------------------

 The example can be run by calling the provided macros from Root session:
 $ cd geant4_vmc/examples/E01
 $ root
 root[0] .x run_g4.C    # run with Geant4
 or
 root[0] .x run_g3.C    # run with Geant3

 Running examples application programs
 --------------------------------------

 The examples can be also run by calling the executable from the examples
 installation directory:
 $ cd geant4_vmc/examples/E01
 $ /mypath/g4vmc_exampleE01    # run with Geant4
 $ /mypath/g3vmc_exampleE01    # run with Geant3

 For keeping maximum simplicity of the code, a fixed configuration is defined
 in the examples main() function. More flexible version of the main() function
 is provided in the test programs which default configuration options can be
 changed by running the program with selected command line options, eg.

 $ testE01
   [-g4g,  --g4-geometry]         Geant4 VMC geometry option
   [-g4pl, --g4-physics-list]     Geant4 physics list selection
   [-g4sp, --g4-special-physics]  Geant4 special physics selection
   [-g4m,  --g4-macro]            Geant4 macro
   [-g4vm, --g4-vis-macro]        Geant4 visualization macro
   [-g3g,  --g3-geometry]         Geant3 geometry option

 Note that the g4* and g3* options are available only when the program was built
 with the corresponding VMC_WITH_Geant4 or VMC_WITH_Geant3 option. Root macro with
 arguments has to be passed in a single string, eg.:
   --root-macro 'test_E01.C("",kFALSE)'
