source: trunk/documents/UserDoc/DocBookUsersGuides/InstallationGuide/xml/UnixMachines/unixMachines.xml @ 1358

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

<para>

Before installing Geant4, the required software listed in
<xref linkend="sect.ReqSoft" />
(and <xref linkend="sect.VisSoft" /> in the case of graphics drivers) 
of this Installation Guide must already be installed on
your system.
</para>

<para>
In this section, a short tutorial on how to install the
toolkit's kernel libraries is given. The installation of the Geant4
kernel libraries and the proper configuration of the environment
can be achieved either manually (by setting the proper environment
variables) or through the <literal>Configure</literal> shell script,
which will allow the installation of just the necessary source code
and libraries in a specified installation area.
</para>

<para>
<emphasis>Step-by-Step</emphasis> guides for the installation are
also available. See 
<ulink url="http://cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/apas06.html">
Appendix - Step-by-Step Installation Guides</ulink>
of <emphasis>Geant4 User's Guide - For Application Developers</emphasis>.
</para>

<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.UsingConfig">
<title>
Using the <literal>Configure</literal> Script for installation
</title>

<para>
A shell script is provided for building the libraries and to allow
easy installation in a specified area. The <literal>Configure</literal>
shell script is placed in the top directory tree of the
distribution (<literal>geant4/Configure</literal>) and allows the user or
system administrator to install the Geant4 toolkit in a
semi-automatic way. Some knowledge of the system is required for
the installation, such as:

<itemizedlist spacing="compact">
  <listitem><para>
    the compiler to be used
  </para></listitem>
  <listitem><para>
    the path where the Geant4 toolkit is to be installed
    (<literal>$G4INSTALL</literal>)
  </para></listitem>
  <listitem><para>
    definition of installation directory paths (optional)
  </para></listitem>
  <listitem><para>
    kind of graphics/analysis system(s) installed in the system,
    and paths to the installation of each graphics/analysis
    package
  </para></listitem>
  <listitem><para>
    the kind of library to be generated: static/shared,
    compound/granular.
  </para></listitem>
</itemizedlist>
</para>

<para>
To run the installer script for building the libraries of the Geant4 toolkit,
one must type the following from the top directory
<literal>geant4</literal>:

<informalexample>
<programlisting>
 &gt; ./Configure -build
</programlisting>
</informalexample>

and follow the on-screen instructions. No system administrator
privileges are required at this stage. The script will ask for the
path in the system where the Geant4 libraries should be installed
later on. The script provides default settings for most of the
environment variables to be set. By pressing -RETURN-, the default
values will be selected; otherwise the proper selection (or path,
in case a path is requested) must be typed in.
</para>

<para>
In case the installation procedure fails for some reason, or you
realise the selected options were not correct at the time the
installation started, you can repeat the whole process by manually
removing the current installation with:

<informalexample>
<programlisting>
 &gt; cd geant4/source
 &gt; make clean
</programlisting>
</informalexample>
where the <literal>$G4SYSTEM</literal> environment variable (specifying
the kind of architecture and compiler used) is manually set in your
environment (according to the flavors listed in 
<xref linkend="sect.Support" />).
</para>

<para>
In case new modules must be added to an existing build (for
example a module for visualization), this can be done manually by
re-running <literal>Configure</literal> and providing the new
settings.
</para>

<para>
Once the process of building the libraries has been completed
successfully, the Geant4 toolkit can be installed in the specified
(already existing) installation area by typing:

<informalexample>
<programlisting>
 &gt; ./Configure -install
</programlisting>
</informalexample>
</para>

<para>
Libraries and necessary source code will be installed in
<literal>lib/geant4</literal>, <literal>include/geant4</literal> (if selected to
install all headers in a single directory), <literal>src/geant4</literal>,
respectively. System administrator privileges may be required for the
installation stage, depending upon where in the system the installation
should happen.
</para>

<para>
<literal>$G4INSTALL</literal> will be set to
<literal>[INSTALLATION_AREA]/src/geant4</literal>.
</para>

</sect1>

<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.ConfigEnv">
<title>
Configuring the Environment to Use Geant4
</title>

<para>
Once libraries have been installed, the user's environment must be
correctly set up for the usage of the Geant4 toolkit. The
<literal>Configure</literal> script provides a way to check the existing
installation and provide the correct configuration for the user's
environment. Configuration scripts <literal>env[.sh.csh]</literal> can be
generated, and should be sourced by the final users in order to
configure their environment according to the performed
installation.
</para>

<para>
To generate the configuration scripts, the user should run
<literal>Configure</literal> placed in the installation area, as follows:

<informalexample>
<programlisting>
 &gt; $G4INSTALL/Configure
</programlisting>
</informalexample>
</para>

<para>
This will generate the shell script <literal>env.csh</literal>
(<literal>env.sh</literal> for <literal>bash</literal> shell) to be sourced or
integrated into the shell login script (<literal>.tcshrc</literal> or
<literal>.bashrc</literal>). The shell script will be generated in the
user's current directory (<literal>$PWD</literal>). The user can
customize it to specify for example her/his proper working
directory through the variable <literal>$G4WORKDIR</literal>. Once the
generated script is sourced, the user will be ready to start
building a Geant4 application.
</para>

<para>
Refer to section the section 
<emphasis>
Getting Started with Geant4 - How to Make an Executable Program
</emphasis>
of the 
<ulink url="http://cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/index.html"> 
Geant4 User's Guide for Application Developers
</ulink> 
for information on how to build an executable in Geant4.
</para>

</sect1>


<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.InstManually">
<title>
Installing Geant4 Manually
</title>

<para>
Before proceeding with the installation, some key environment
variables must be defined in your user environment in order to
specify where all software components are to be placed and to set
some compilation options. A complete reference to all environment
variables in Geant4 is available in section 

<emphasis>
Appendix - Makefiles and Environment Variables
</emphasis>
of the
<ulink url="http://cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/index.html"> 
Geant4 User's Guide for Application Developers
</ulink>.
</para>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.InstManually.ReqEnvVar">
<title>
Required Environment Variables
</title>

<variablelist><title></title>
<varlistentry>
  <term>
    <literal>G4SYSTEM:</literal>
  </term>
  <listitem><para>
    set to one of the flavors listed in section 1.1 to specify the
    kind of architecture and compiler used
  </para></listitem>
</varlistentry>
<varlistentry>
  <term>
    <literal>G4INSTALL:</literal>
  </term>
  <listitem><para>
    path where the Geant4 toolkit tree is installed (ex.
    <literal>$HOME/geant4</literal>)
  </para></listitem>
</varlistentry>
<varlistentry>
  <term>
    <literal>CLHEP_BASE_DIR:</literal>
  </term>
  <listitem><para>
    path to the CLHEP installation
  </para></listitem>
</varlistentry>
</variablelist>

</sect2>

<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.InstManually.OptEnvVar">
<title>
Optional Environment Variables
</title>

<variablelist><title></title>
<varlistentry>
  <term>
    <literal>G4WORKDIR:</literal>
  </term>
  <listitem><para>
    path of the user's working directory (default in
    <literal>$G4INSTALL</literal>)
  </para></listitem>
</varlistentry>
<varlistentry>
  <term>
    <literal>G4LIB:</literal>
  </term>
  <listitem><para>
    path where the kernel libraries should be installed (default in
    <literal>$G4INSTALL/lib</literal>)
  </para></listitem>
</varlistentry>
<varlistentry>
  <term>
    <literal>G4TMP:</literal>
  </term>
  <listitem><para>
    path where temporary files (object files, dependency files) are
    placed (default in <literal>$G4WORKDIR/tmp)</literal>
  </para></listitem>
</varlistentry>
<varlistentry>
  <term>
    <literal>G4BIN:</literal>
  </term>
  <listitem><para>
    path where final executable files are placed (default in
    <literal>$G4WORKDIR/bin)</literal>.
  </para></listitem>
</varlistentry>
<varlistentry>
  <term>
    <literal>G4INCLUDE:</literal>
  </term>
  <listitem><para>
    path where source header files may be mirrored at installation
    by issuing <literal>make includes</literal> (default in
    <literal>$G4INSTALL/include</literal>)
  </para></listitem>
</varlistentry>
<varlistentry>
  <term>
    <literal>G4DEBUG:</literal>
  </term>
  <listitem><para>
    flag specifying that libraries be built with debug symbols
    (requires a lot of disk space). The default is optimised-mode
  </para></listitem>
</varlistentry>
<varlistentry>
  <term>
    <literal>G4LIB_BUILD_SHARED:</literal>
  </term>
  <listitem><para>
    flag specifying that kernel libraries be built as shared
    libraries (libraries will then be used by default). If not set,
    static archive libraries are built by default
  </para></listitem>
</varlistentry>
<varlistentry>
  <term>
    <literal>G4LIB_BUILD_STATIC:</literal>
  </term>
  <listitem><para>
    flag specifying that kernel libraries be built as static
    archive libraries. Note that you may specify this flag in addition
    to <literal>G4LIB_BUILD_SHARED</literal> to build shared and static
    libraries simultaneously.
  </para></listitem>
</varlistentry>
<varlistentry>
  <term>
    <literal>G4LIB_BUILD_G3TOG4:</literal>
  </term>
  <listitem><para>
    flag specifying that the library for the g3tog4 module be
    built. By default the library will not be built.
  </para></listitem>
</varlistentry>
<varlistentry>
  <term>
    <literal>G4LIB_BUILD_ZLIB:</literal>
  </term>
  <listitem><para>
    flag specifying that an additional library for file compression
    should be built (not required on Linux/Unix systems, required on
    Windows if choosing OpenGL or OpenInventor visualization). By default
    the library will not be built.
  </para></listitem>
</varlistentry>
<varlistentry>
  <term>
    <literal>G4_NO_VERBOSE:</literal>
  </term>
  <listitem><para>
    defining this flag prevents the compilation of verbosity code
    (for better performance). The default is with verbosity on.
  </para></listitem>
</varlistentry>
</variablelist>

<para>
The list of all additional flags (also requiring third-party packages
installed) can be found in
<ulink url="http://cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/apas05.html#sect.MkflEnvVar.EnvVar">Section 5.2</ulink>
of the
<ulink url="http://cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/index.html"> 
Geant4 User's Guide for Application Developers
</ulink>.
</para>

<para>
The Geant4 installation requires native STL (the Standard Template
Library) as the base foundation class library. This also implies
strict ISO-ANSI language compliance. In addition to the above, you
might want to set the proper environment for visualization, such
as:

<itemizedlist spacing="compact">
  <listitem><para>
    the kind of graphics driver(s) installed in the system
  </para></listitem>
  <listitem><para>
    the path to the installation of each graphics driver
  </para></listitem>
</itemizedlist>

in case you want to build the Geant4 kernel libraries with the
graphics drivers built-in. See 

<emphasis>
Visualization - The Visualization Drivers
</emphasis>
of the
<ulink url="http://cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/index.html"> 
Geant4 User's Guide for Application Developers
</ulink>.
</para>

<para>
At this point, you may choose one of two ways to compile and
install the kernel libraries, depending on your needs and system
resources. From <literal>$G4INSTALL/source</literal>:

<orderedlist spacing="compact">
  <listitem><para>
    <literal>make</literal>
    <para>
    This will make one library for each "leaf" category (maximum
    library granularity) and automatically produce a map of library use
    and dependencies.</para>
  </para></listitem>
  <listitem><para>
    <literal>make global</literal>
    <para>
    This will make global libraries, one for each major category.
    </para>
  </para></listitem>
</orderedlist>
</para>

<para>
The main advantage of the first approach is the speed of building
the libraries and of the application, which in some cases can be
improved by a factor of two or three compared to the "global
library" approach.
</para>

<para>
Using the "granular library" approach a fairly large number
(roughly 90) of "leaf" libraries is produced. However, the
dependencies and linking list are evaluated and generated
automatically on the fly. The top-level <literal>GNUmakefile</literal> in
<literal>$G4INSTALL/source</literal> parses the dependency files of
Geant4 and produces a file <literal>libname.map</literal> in
<literal>$G4LIB</literal>. <literal>libname.map</literal> is produced by the
tool <literal>liblist</literal>, whose source code is in
<literal>$G4INSTALL/config</literal>.
</para>

<para>
When building a binary application the script
<literal>binmake.gmk</literal> in <literal>$G4INSTALL/config</literal> will
parse the user's dependency files and use <literal>libname.map</literal>
to determine through <literal>liblist</literal> the required libraries to
add to the linking list. Only the required libraries will be loaded
in the link command.
</para>

<para>
The command <literal>make libmap</literal> issued from
<literal>$G4INSTALL/source</literal>, allows manual rebuilding of the
dependency map. The command is issued by default in the normal
build process for granular libraries.
</para>

<para>
It is possible to install both "granular" and "compound" libraries,
by typing "make" and "make global" in sequence. In this case, to
choose usage of granular libraries at link time one should set the
flag G4LIB_USE_GRANULAR in the environment; otherwise compound
libraries will be adopted by default.
</para>

</sect2>
</sect1>

<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.IntegGeneFrame">
<title>
Integrating Geant4 into a Generic Framework
</title>

<para>
As part of the Geant4 kernel libraries installation, it is also
possible to put the entire set of header files in a single place,
which is determined by the environment variable
<literal>G4INCLUDE</literal> specifying the directory path. Therefore,
it's rather straightforward to integrate Geant4 into a generic
external framework, by simply knowing the path where header files
are located in the system (<literal>G4INCLUDE</literal>) and where
installed libraries are placed (<literal>G4LIB</literal>).
</para>

<para>
In <ulink url="http://cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/apas05.html#sect.MkflEnvVar.EnvVar">Section 5.2</ulink>.
(<emphasis>Appendix - Makefiles and Environment Variables</emphasis>)
of the
<ulink url="http://cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/index.html"> 
Geant4 User's Guide for Application Developers
</ulink>,
you can find a list of all the environment variables. In
<ulink url="http://cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/apas05.html#sect.MkflEnvVar.LnkExtLib">Section 5.3</ulink>
it is also explained how to integrate external libraries which may or 
may not use the Geant4 kernel libraries, using the <literal>GNUmake</literal> 
build system of Geant4.
</para>

</sect1>