<!-- ******************************************************** -->
<!--                                                          -->
<!--  [History]                                               -->
<!--    Converted to DocBook: Katsuya Amako, Aug-2006         -->
<!--                                                          -->
<!-- ******************************************************** -->


<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.MkflEnvVar">
<title>
Makefiles and Environment Variables
</title>

<para>
This section describes how the GNUmake infrastructure is
implemented in Geant4 and provides a quick reference guide for the
user/installer about the most important environment variables
defined.
</para>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.MkflEnvVar.GNUG4">
<title>
The GNUmake system in Geant4
</title>

<para>
As described in <xref linkend="sect.HowToDefMain" /> of the 
Installation Guide, the GNUmake process in
Geant4 is mainly controlled by the following GNUmake script files
(<literal>*.gmk</literal> scripts are placed in
<literal>$G4INSTALL/config</literal>):

<itemizedlist spacing="compact">
  <listitem><para>
    <literal>architecture.gmk</literal>: defining all the architecture
    specific settings and paths. System settings are stored in
    <literal>$G4INSTALL/config/sys</literal> in separate files.
  </para></listitem>
  <listitem><para>
    <literal>common.gmk</literal>: defining all general GNUmake rules for
    building objects and libraries.
  </para></listitem>
  <listitem><para>
    <literal>globlib.gmk</literal>: defining all general GNUmake rules for
    building compound libraries.
  </para></listitem>
  <listitem><para>
    <literal>binmake.gmk</literal>: defining the general GNUmake rules for
    building executables.
  </para></listitem>
  <listitem><para>
    <literal>GNUmake</literal> scripts: placed inside each directory in the
    G4 distribution and defining directives specific to build a library
    (or a set of sub-libraries) or and executable.
  </para></listitem>
</itemizedlist>
</para>

<para>
To build a single library (or a set of sub-libraries) or an
executable, you must explicitly change your current directory to
the one you're interested in and invoke the "<literal>make</literal>"
command from there ("<literal>make global</literal>" for building a
compound library). Here is a list of the basic commands or GNUmake
"targets" one can invoke to build libraries and/or executables:

<itemizedlist spacing="compact">
  <listitem><para>
    <literal>make</literal>
    <para>
    starts the compilation process for building a kernel library or a
    library associated with an example. Kernel libraries are built with
    maximum granularity, i.e. if a category is a compound, this command  
    will build all the related sub-libraries, 
    <emphasis role="bold">not</emphasis> the compound one. 
    The top level <literal>GNUmakefile</literal> in
    <literal>$G4INSTALL/source</literal> will also build in this case a
    dependency map <literal>libname.map</literal> of each library to establish
    the linking order automatically at the <literal>bin</literal> step. The map
    will be placed in <literal>$G4LIB/$G4SYSTEM</literal>.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>make global</literal>
    <para>
    starts the compilation process to build a single compound kernel
    library per category. If issued after "make", both 'granular' and
    'compound' libraries will be available (NOTE: this will
    consistently increase the disk space required. Compound libraries
    will then be selected by default at link time, unless
    G4LIB_USE_GRANULAR is specified).
    </para>
  </para></listitem>
  <listitem><para>
    <literal>make bin</literal> or <literal>make</literal> (only for
    examples/)
    <para>
    starts the compilation process to build an executable. This command
    will build implicitly the library associated with the example and
    link the final application. It assumes <emphasis role="bold">all</emphasis> 
    kernel libraries are already generated and placed in the correct
    <literal>$G4INSTALL</literal> path defined for them.
    </para>

    <para>
    The linking order is controlled automatically in case libraries
    have been built with maximum granularity, and the link list is
    generated on the fly.
    </para>
  </para></listitem>
  <listitem><para>
    <literal>make dll</literal>
    <para>
    On Windows systems this will start the compilation process to build
    single compound kernel library per category and generate Dynamic
    Link Libraries (DLLs). Once the libraries are generated, the
    process will imply also the deletion of all temporary files
    generated during the compilation.
    </para>
  </para></listitem>
</itemizedlist>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
<literal>lib/ bin/</literal> and <literal>tmp/</literal> directories
</bridgehead>

<para>
The <literal>$G4INSTALL</literal> environment variable specifies where
the installation of the Geant4 toolkit should take place, therefore
kernel libraries will be placed in <literal>$G4INSTALL/lib</literal>. The
<literal>$G4WORKDIR</literal> environment variable is set by the user and
specifies the path to the user working directory; temporary files
(object-files and data products of the installation process of
Geant4) will be placed in <literal>$G4WORKDIR/tmp</literal>, according to
the system architecture used. Binaries will be placed in
<literal>$G4WORKDIR/bin</literal>, according to the system architecture
used. The path to <literal>$G4WORKDIR/bin/$G4SYSTEM</literal> should be
added to <literal>$PATH</literal> in the user environment.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.MkflEnvVar.EnvVar">
<title>
Environment variables
</title>

<para>
Here is a list of the most important environment variables defined
within the Geant4 <literal>GNUmake</literal> infrastructure, with a short
explanation of their use.
</para>

<para>
<emphasis role="bold">We recommend that those environment variables listed here and
marked with (*) NOT be overriden or set (explicitly or by
accident). They are already set and used internally in the default
setup !</emphasis>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
System configuration
</bridgehead>

<para>
<variablelist>
  <varlistentry>
    <term>
      $CLHEP_BASE_DIR
    </term>
    <listitem>
      Specifies the path where the CLHEP package is installed in your system.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4SYSTEM
    </term>
    <listitem>
      <para> 
      Defines the architecture and compiler currently used.
      </para>
      <para> 
      <emphasis role="bold">NOTE</emphasis>: This variable is set automatically 
      if the <literal>Configure</literal> script is adopted for the
      installation. This will result in the proper settings also for
      configuring the environment with the generated shell scripts
      <literal>env.[c]sh</literal>.
      </para>
    </listitem>
  </varlistentry>
</variablelist>
</para>



<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Installation paths
</bridgehead>

<para>
<variablelist>
  <varlistentry>
    <term>
      $G4INSTALL
    </term>
    <listitem>
      Defines the path where the Geant4 toolkit is located. It
      should be set by the system installer. By default, it sets to
      <literal>$HOME/geant4</literal>, assuming the Geant4 distribution 
      is placed in <literal>$HOME</literal>.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4BASE <emphasis role="bold">(*)</emphasis>
    </term>
    <listitem>
      Defines the path to the source code. Internally used to define
      <literal>$CPPFLAGS</literal> and <literal>$LDFLAGS</literal> for 
      -I and -L directives. It has to be set to 
      <literal>$G4INSTALL/src</literal>.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4WORKDIR
    </term>
    <listitem>
      Defines the path for the user's workdir for Geant4. It is set by
      default to <literal>$HOME/geant4</literal>, assuming the user's 
      working directory for Geant4 is placed in <literal>$HOME</literal>.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4INCLUDE
    </term>
    <listitem>
      Defines the path where source header files may be mirrored at
      installation by issuing <literal>gmake includes</literal> (default 
      is set to <literal>$G4INSTALL/include</literal>)
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4BIN, $G4BINDIR <emphasis role="bold">(*)</emphasis>
    </term>
    <listitem>
      Used by the system to specify the place where to store executables.
      By default they're set to <literal>$G4WORKDIR/bin</literal> and
      <literal>$G4BIN/$G4SYSTEM</literal> respectively. The path to
      <literal>$G4WORKDIR/bin/$G4SYSTEM</literal> should be added to 
      <literal>$PATH</literal> in the user environment. 
      <literal>$G4BIN</literal> can be overridden.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4TMP, $G4TMPDIR <emphasis role="bold">(*)</emphasis>
    </term>
    <listitem>
      Used by the system to specify the place where to store temporary
      files products of the compilation/build of a user application or
      test. By default they're set to <literal>$G4WORKDIR/tmp</literal> 
      and <literal>$G4TMP/$G4SYSTEM</literal> respectively. 
      <literal>$G4TMP</literal> can be overridden.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4LIB, $G4LIBDIR <emphasis role="bold">(*)</emphasis>
    </term>
    <listitem>
      Used by the system to specify the place where to install libraries.
      By default they're set to <literal>$G4INSTALL/lib</literal> and
      <literal>$G4LIB/$G4SYSTEM</literal> respectively. 
      <literal>$G4LIB</literal> can be overridden.
    </listitem>
  </varlistentry>
</variablelist>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Build specific
</bridgehead>

<para>
<variablelist>
  <varlistentry>
    <term>
      $G4TARGET
    </term>
    <listitem>
      Specifies the target (name of the source file defining the main())
      of the application/example to be built. This variable is set
      automatically for the examples and tests placed in
      <literal>$G4INSTALL/examples</literal>.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4DEBUG
    </term>
    <listitem>
      Specifies to compile the code (libraries or examples) including
      symbolic information in the object code for debugging. The size of
      the generated object code can increase considerably. By default,
      code is compiled in optimised mode (<literal>$G4OPTIMISE</literal> set).
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4OPTDEBUG
    </term>
    <listitem>
      Only available for the <literal>g++</literal> compiler, specifies to
      compile the code (libraries or examples) in optimised mode, but
      including symbolic information in the object code for debugging.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4NO_OPTIMISE
    </term>
    <listitem>
      Specifies to compile the code (libraries or examples) without
      compiler optimisation.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4PROFILE
    </term>
    <listitem>
      On <literal>Linux</literal> systems with the <literal>g++</literal>
      compiler, it allows to build libraries with profiling setup for
      monitoring with the <literal>gprof</literal> tool.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4_NO_VERBOSE
    </term>
    <listitem>
      Geant4 code is compiled by default in high verbosity mode
      (<literal>$G4VERBOSE</literal> flag set). For better performance, 
      verbosity code can be left out by defining <literal>$G4_NO_VERBOSE</literal>.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4LIB_BUILD_SHARED
    </term>
    <listitem>
      Flag specifying if to build kernel libraries as shared libraries
      (libraries will be then used by default). If not set, static
      archive libraries are built by default.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4LIB_BUILD_STATIC
    </term>
    <listitem>
      Flag specifying if to build kernel libraries as static archive
      libraries in addition to shared libraries (in case
      <literal>$G4LIB_BUILD_SHARED</literal> is set as well).
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4LIB_BUILD_DLL <emphasis role="bold">(*)</emphasis>
    </term>
    <listitem>
      Internal flag for specifying to build DLL kernel libraries for
      Windows systems. The flag is automatically set when requested to
      build DLLs.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4LIB_USE_DLL
    </term>
    <listitem>
      For Windows systems only. Flag to specify to build an application
      using the installed DLL kernel libraries for Windows systems. It is
      required to have this flag set in the environment in order to
      successfully build an application if the DLL libraries have been
      installed.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4LIB_USE_GRANULAR
    </term>
    <listitem>
      To force usage of "granular" libraries against "compound" libraries
      at link time in case both have been installed. The Geant4 building
      system chooses "compound" libraries by default, if installed.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      
    </term>
    <listitem>
      
    </listitem>
  </varlistentry>
</variablelist>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
UI specific
</bridgehead>

<para>
The most relevant flags for User Interface drivers are just
listed here. A more detailed description is given also in section
2. of this User's Guide.
</para>

<para>
<variablelist>
  <varlistentry>
    <term>
      G4UI_USE_TERMINAL
    </term>
    <listitem>
      Specifies to use dumb terminal interface in the application to be
      built (default).
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      G4UI_USE_TCSH
    </term>
    <listitem>
      Specifies to use the tcsh-shell like interface in the application
      to be built.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      G4UI_BUILD_XM_SESSION, G4UI_BUILD_XAW_SESSION
    </term>
    <listitem>
      Specifies to include in kernel library the <emphasis>XM</emphasis> or 
      <emphasis>XAW</emphasis> Motif-based user interfaces.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      G4UI_USE_XM, G4UI_USE_XAW
    </term>
    <listitem>
      Specifies to use the <emphasis>XM</emphasis> or <emphasis>XAW</emphasis> 
      interfaces in the application to be built.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      G4UI_BUILD_WIN32_SESSION
    </term>
    <listitem>
      Specifies to include in kernel library the WIN32 terminal interface
      for Windows systems.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      G4UI_USE_WIN32
    </term>
    <listitem>
      Specifies to use the WIN32 interfaces in the application to be
      built on Windows systems.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      G4UI_BUILD_QT_SESSION
    </term>
    <listitem>
      Specifies to include in kernel library the Qt terminal interface.
      <literal>$QTHOME</literal> should specify the path where Qt libraries
      and headers are installed
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      G4UI_USE_QT
    </term>
    <listitem>
      Specifies to use the Qt interfaces in the application to be
      built.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      G4UI_NONE
    </term>
    <listitem>
      If set, no UI sessions nor any UI libraries are built. This can be
      useful when running a pure batch job or in a user framework having
      its own UI system.
    </listitem>
  </varlistentry>
</variablelist>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Visualization specific
</bridgehead>

<para>
The most relevant flags for visualization graphics drivers are
just listed here. A description of these variables is given also in
section 2. of this User's Guide.
</para>

<para>
<variablelist>
  <varlistentry>
    <term>
      $G4VIS_BUILD_OPENGLX_DRIVER
    </term>
    <listitem>
      Specifies to build kernel library for visualization including the
      OpenGL driver with X11 extension. It requires <literal>$OGLHOME</literal> 
      set (path to OpenGL installation).
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4VIS_USE_OPENGLX
    </term>
    <listitem>
      Specifies to use OpenGL graphics with X11 extension in the
      application to be built.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4VIS_BUILD_OPENGLXM_DRIVER
    </term>
    <listitem>
      Specifies to build kernel library for visualization including the
      OpenGL driver with XM extension. It requires <literal>$OGLHOME</literal> 
      set (path to OpenGL installation).
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4VIS_USE_OPENGLXM
    </term>
    <listitem>
      Specifies to use OpenGL graphics with XM extension in the
      application to be built.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      G4VIS_BUILD_OPENGLQT_DRIVER
    </term>
    <listitem>
      Specifies to build kernel library for visualization including the
      OpenGL driver with Qt extension. It requires <literal>$QTHOME</literal>
      set to specify the path where Qt libraries and headers are installed.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      G4VIS_USE_OPENGLQT
    </term>
    <listitem>
      Specifies to use OpenGL graphics with Qt extension in the
      application to be built.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4VIS_BUILD_OI_DRIVER
    </term>
    <listitem>
      Specifies to build kernel library for visualization including the
      OpenInventor driver. It requires <literal>$OIHOME</literal> set 
      (paths to the <literal>OpenInventor</literal> installation).
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4VIS_USE_OI
    </term>
    <listitem>
      Specifies to use OpenInventor graphics in the application to be
      built.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4VIS_BUILD_OIX_DRIVER
    </term>
    <listitem>
      Specifies to build the driver for the free X11 version of
      OpenInventor.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4VIS_USE_OIX
    </term>
    <listitem>
      Specifies to use the free X11 version of OpenInventor.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4VIS_BUILD_RAYTRACERX_DRIVER
    </term>
    <listitem>
      Specifies to build kernel library for visualization including the
      Ray-Tracer driver with X11 extension. It requires <literal>X11</literal>
      installed in the system.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4VIS_USE_RAYTRACERX
    </term>
    <listitem>
      Specifies to use the X11 version of the Ray-Tracer driver.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4VIS_BUILD_OIWIN32_DRIVER
    </term>
    <listitem>
      Specifies to build the driver for the free X11 version of
      OpenInventor on Windows systems.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4VIS_USE_OIWIN32
    </term>
    <listitem>
      Specifies to use the free X11 version of OpenInventor on Windows
      systems.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4VIS_BUILD_DAWN_DRIVER
    </term>
    <listitem>
      Specifies to build kernel library for visualization including the
      driver for DAWN.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4VIS_USE_DAWN
    </term>
    <listitem>
      Specifies to use DAWN as a possible graphics renderer in the
      application to be built.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4DAWN_HOST_NAME
    </term>
    <listitem>
      To specify the hostname for use with the DAWN-network driver.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4VIS_NONE
    </term>
    <listitem>
      If specified, no visualization drivers will be built or used.
    </listitem>
  </varlistentry>
</variablelist>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Hadronic physics specific
</bridgehead>

<para>
<variablelist>
  <varlistentry>
    <term>
      $G4NEUTRONHP_USE_ONLY_PHOTONEVAPORATION
    </term>
    <listitem>
      When using high precision neutron code, user may choose to force the
      use of Photon Evaporation model instead of using the neutron capture
      final state data.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4NEUTRONHP_SKIP_MISSING_ISOTOPES
    </term>
    <listitem>
      User can force high precison neutron code to use only exact isotope
      data files instead of allowing nearby isotope files to be used. If the
      exact file is not available, the cross section will be set to zero and a
      warning message will be printed.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4NEUTRONHP_NEGLECT_DOPPLER
    </term>
    <listitem>
      Sets neglecting doppler broadening mode for boosting performance.
    </listitem>
  </varlistentry>
</variablelist>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
<literal>GDML</literal>, <literal>zlib</literal> and <literal>g3tog4</literal> modules
</bridgehead>

<para>
<variablelist>
  <varlistentry>
    <term>
      $G4LIB_BUILD_GDML
    </term>
    <listitem>
      If set, triggers compilation of a plugin module <literal>gdml</literal> 
      for allowing import/export of detector description setups (geometrical
      volumes, solids, materials, etc.). By default, the flag is not set; if
      set, the path to the installation of XercesC package must be specified
      through the variable <literal>$XERCESCROOT</literal>. 
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4LIB_USE_GDML
    </term>
    <listitem>
      Specifies to use the <literal>gdml</literal> module. The flag is
      automatically set if <literal>$G4LIB_BUILD_GDML</literal> is set in the environment.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4LIB_BUILD_ZLIB
    </term>
    <listitem>
      If set, triggers compilation of a specific <literal>zlib</literal> 
      module for the compression of output files (mainly in use currently 
      for the HepRep graphics driver). By default, the flag is not set and 
      the built-in system library for compression is adopted instead. Setting
      this flag will also implicitely set the flag below.
      On Windows systems, if OpenGL or OpenInventor visualization drivers
      are built, this module is automatically built.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4LIB_USE_ZLIB
    </term>
    <listitem>
      Specifies to use the <literal>zlib</literal> module, either system 
      built-in or Geant4 specific.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4LIB_BUILD_G3TOG4
    </term>
    <listitem>
      If set, triggers compilation of the <literal>g3tog4</literal> module for
      conversions of simple legacy geometries descriptions to Geant4. By
      default, the flag is not set and the module's library is not built.
      Setting this flag will also implicitely set the flag below.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4LIB_USE_G3TOG4
    </term>
    <listitem>
      Specifies to use the <literal>g3tog4</literal> module, assuming the related
      library has been already installed.
    </listitem>
  </varlistentry>
</variablelist>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Analysis specific
</bridgehead>

<para>
<variablelist>
  <varlistentry>
    <term>
      $G4ANALYSIS_USE
    </term>
    <listitem>
      Specifies to activate the appropriate environment for analysis, if
      an application includes code for histogramming based on
      <emphasis>AIDA</emphasis>. Additional setup variables are required
      (<literal>$G4ANALYSIS_AIDA_CONFIG_CFLAGS</literal>,
      <literal>$G4ANALYSIS_AIDA_CONFIG_LIBS</literal>) to define config options 
      for AIDA ("<literal>aida-config --cflags</literal>" and 
      "<literal>aida-config --libs</literal>"). See installation instructions 
      of the specific analysis tools for details.
    </listitem>
  </varlistentry>
</variablelist>
</para>

<!-- ******* Bridgehead ******* -->
<bridgehead renderas='sect4'>
Directory paths to Physics Data
</bridgehead>

<para>
<variablelist>
  <varlistentry>
    <term>
      $G4NEUTRONHPDATA
    </term>
    <listitem>
      Path to external data set for Neutron Scattering processes.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4LEDATA
    </term>
    <listitem>
      Path to external data set for low energy electromagnetic
      processes.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4LEVELGAMMADATA
    </term>
    <listitem>
      Path to the data set for Photon Evaporation.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4RADIOACTIVEDATA
    </term>
    <listitem>
      Path to the data set for Radiative Decay processes.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4ABLADATA
    </term>
    <listitem>
      Path to nuclear shell effects data set for INCL/ABLA hadronic model.
    </listitem>
  </varlistentry>
  <varlistentry>
    <term>
      $G4REALSURFACEDATA
    </term>
    <listitem>
      Path to the data set for measured optical surface reflectance for
      precise optical physics.
    </listitem>
  </varlistentry>
</variablelist>
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.MkflEnvVar.LnkExtLib">
<title>
Linking External Libraries with Geant4
</title>

<para>
The Geant4 GNUmake infrastructure allows to extend the link list of
libraries with external (or user defined) packages which may be
required for some user's applications to generate the final
executable.
</para>

<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.MkflEnvVar.LnkExtLib.AddExtlibNoG4">
<title>
Adding external libraries which do *not* use Geant4
</title>

<para>
In the <literal>GNUmakefile</literal> of your application, before including
<literal>binmake.gmk</literal>, specify the extra library in
<literal>EXTRALIBS</literal> either using the <literal>-L...-l...</literal> 
syntax or by specifying the full pathname, e.g.:

<informalexample>
<programlisting>
  EXTRALIBS := -L&lt;your-path&gt;/lib -l&lt;myExtraLib&gt;
</programlisting>
</informalexample>
or
<informalexample>
<programlisting>
  EXTRALIBS := &lt;your-path&gt;/lib/lib&lt;myExtraLib&gt;.a
</programlisting>
</informalexample>
</para>

<para>
You may also specify <literal>EXTRA_LINK_DEPENDENCIES</literal>, which is
added to the dependency of the target executable, and you may also
specify a rule for making it, e.g.:

<informalexample>
<programlisting>
  EXTRA_LINK_DEPENDENCIES := &lt;your-path&gt;/lib/lib&lt;myExtraLib&gt;.a

  &lt;your-path&gt;/lib/lib&lt;myExtraLib&gt;.a:
        cd &lt;your-path&gt;/lib; $(MAKE)
</programlisting>
</informalexample>
</para>

<para>
Note that you almost certainly need to augment <literal>CPPFLAGS</literal>
for the header files of the external library, e.g.:

<informalexample>
<programlisting>
  CPPFLAGS+=-I&lt;your-path&gt;/include
</programlisting>
</informalexample>

See <xref linkend="programlist_MkflEnvVar_1" />.
</para>

<para>
<example id="programlist_MkflEnvVar_1">
<title>
An example of a customised GNUmakefile for an application or
example using an external module not bound to Geant4.
</title>

<programlisting>
 # --------------------------------------------------------------------
 # GNUmakefile for the application "sim" depending on module "Xplotter"
 # --------------------------------------------------------------------

 name := sim
 G4TARGET := $(name)
 G4EXLIB := true

 CPPFLAGS  += -I$(HOME)/Xplotter/include
 EXTRALIBS += -L$(HOME)/Xplotter/lib -lXplotter
 EXTRA_LINK_DEPENDENCIES := $(HOME)/Xplotter/lib/libXplotter.a

 .PHONY: all

 all: lib bin

 include $(G4INSTALL)/config/binmake.gmk

 $(HOME)/Xplotter/lib/libXplotter.a:
         cd $(HOME)/Xplotter; $(MAKE)
</programlisting>
</example>
</para>

</sect3>


<!-- ******************* Section (Level#3) ****************** -->
<sect3 id="sect.MkflEnvVar.LnkExtLib.AddExtlibWithG4">
<title>
Adding external libraries which use Geant4
</title>

<para>
In addition to the above, specify, in <literal>EXTRALIBSSOURCEDIRS</literal>,
a list of directories containing source files in its <literal>src/</literal>
subdirectory. Thus, your <literal>GNUmakefile</literal> might contain:

<informalexample>
<programlisting>
  EXTRALIBS += $(G4WORKDIR)/tmp/$(G4SYSTEM)/&lt;myApp&gt;/lib&lt;myApp&gt;.a \
               -L&lt;your-path&gt;/lib -l&lt;myExtraLib&gt;
  EXTRALIBSSOURCEDIRS += &lt;your-path&gt;/&lt;myApp&gt; &lt;your-path&gt;/&lt;MyExtraModule&gt;
  EXTRA_LINK_DEPENDENCIES := $(G4WORKDIR)/tmp/$(G4SYSTEM)/&lt;myApp&gt;/lib&lt;myApp&gt;.a

  MYSOURCES := $(wildcard &lt;your-path&gt;/&lt;myApp&gt;/src/*cc)
  $(G4WORKDIR)/tmp/$(G4SYSTEM)/&lt;myApp&gt;/lib&lt;myApp&gt;.a: $(MYSOURCES)
        cd &lt;your-path&gt;/&lt;myApp&gt;; $(MAKE)
</programlisting>
</informalexample>
</para>

<para>
See <xref linkend="programlist_MkflEnvVar_2" />.
</para>

<para>
<example id="programlist_MkflEnvVar_2">
<title>
An example of a customised GNUmakefile for an
application or example using external modules bound to Geant4.
</title>

<programlisting>
# -----------------------------------------------------------------
# GNUmakefile for the application "phys" depending on module "reco"
# -----------------------------------------------------------------

name := phys
G4TARGET := $(name)
G4EXLIB := true

EXTRALIBS += $(G4WORKDIR)/tmp/$(G4SYSTEM)/$(name)/libphys.a \
             -L$(HOME)/reco/lib -lreco
EXTRALIBSSOURCEDIRS += $(HOME)/phys $(HOME)/reco
EXTRA_LINK_DEPENDENCIES := $(G4WORKDIR)/tmp/$(G4SYSTEM)/$(name)/libphys.a

.PHONY: all
all: lib bin

include $(G4INSTALL)/config/binmake.gmk

MYSOURCES := $(wildcard $(HOME)/phys/src/*cc)
$(G4WORKDIR)/tmp/$(G4SYSTEM)/$(name)/libphys.a: $(MYSOURCES)
        cd $(HOME)/phys; $(MAKE)
</programlisting>
</example>
</para>

</sect3>

</sect2>
</sect1>
