source: trunk/documents/UserDoc/DocBookUsersGuides/ForApplicationDeveloper/xml/Appendix/tipsCompilation.xml @ 921

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


<!-- ******************* Section (Level#1) ****************** -->
<sect1 id="sect.TpPrgCmp">
<title>
Tips for Program Compilation
</title>

<para>
This section is dedicated to illustrate and justify some of the
options used and fixed by default in the compilation of the Geant4
toolkit. It is also meant to be a simple guide for the
user/installer to avoid or overcome problems which may occur on
some compilers. Solutions proposed here are based on the experience
gained while porting the Geant4 code to different
architectures/compilers and are specific to the OS's and compiler's
version valid at the current time of writing of this manual.
</para>

<para>
It's well known that each compiler adopts its own internal
techniques to produce the object code, which in the end might be
more or less perfomant and more or less optimised, depending on
several factors also related to the system architecture which it
applies to. A peculiarity of C++ compilers nowadays is the way
templated instances are treated during the compilation/linkage
process. Some C++ compilers need to store temporarily template
instantiation files (object files or temporary source code files)
in a "template repository" or directory that can be specified as
unique or not directly from the compilation command (probably
historically coming from the old cfront-based implementation of the
C++ compiler).
</para>

<para>
After the installation of the libraries, we strongly suggest to
always distinguish between the installation directory (identified
by $G4INSTALL) and the working directory (identified by
$G4WORKDIR), in order not to alter the installation area for the
template repository.
</para>

<para>
In Geant4, the path to the template repository (for those
compilers which make use of it) is specified by the environment
variable $G4TREP, which is fixed and points by default to
<literal>$G4WORKDIR/tmp/$G4SYSTEM/g4.ptrepository/</literal>, where
<literal>$G4SYSTEM</literal> identifies the system-architecture/compiler
currently used and <literal>$G4WORKDIR</literal> is the path to the user
working directory for Geant4.
</para>

<para>
A secondary template repository <literal>$G4TREP/exec</literal> is
created by default and can be used when building executables to
isolate the main repository used for building the libraries in case
of clashes provoked by conflicting class-names. This secondary
template repository can be activated by defining in the environment
(or in the GNUmakefile related to the test/example to be built) the
flag <literal>G4EXEC_BUILD</literal>; once activated, the secondary
repository will become the read/write one, while the primary
repository will be considered read-only.
</para>

<para>
At the current time, only few compilers still make use of a
template repository. A good recommendation valid in general such
compilers is to make use of a single template repository (specified
by the <literal>$G4TREP</literal> environment variable) for building all
Geant4 libraries; then use a secondary template repository
(<literal>$G4TREP/exec</literal>, together with the
<literal>$G4EXEC_BUILD</literal> flag) when building any kind of example or
application.
</para>

<para>
It's always good practise to clean-up the secondary template
repository from time to time.
</para>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.TpPrgCmp.UnxLnxGpp">
<title>
Unix/Linux - g++
</title>

<para>
OS: Linux
</para>

<para>
Compiler: GNU/gcc
</para>

<para>
Strict ISO/ANSI compilation is forced (<literal>-ansi -pedantic</literal>
compiler flags), also code is compiled with high verbosity
diagnostics (<literal>-Wall</literal> flag). The default optimisation level
is <literal>-O2</literal>.
</para>

<note>
<title>Note</title>

<para>
Additional compilation options (<literal>-march=XXX
-mfpmath=sseYYY</literal>) to adopt chip specific floating-point
operations on the SSE unit, can be activated by adapting the
<literal>XXX, YYY</literal> options and uncommenting the relevant
part in the <literal>Linux-g++.gmk</literal> configuration script.
By doing so, it has been verified a greater stability of results,
making possible reproducibility of exact outputs between debug,
non-optimised and optimised runs. A little performance improvement
(in the order of 2%) can also be achieved in some cases. To be
considered that binaries built using these chip-specific options
will likely NOT be portable cross platforms; generated applications
will only run on the specific chip-based architectures.
</para>
</note>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.TpPrgCmp.WndMsVslCpp">
<title>
Windows - MS Visual C++
</title>

<para>
OS: MS/Windows
</para>

<para>
Compiler: MS-VC++
</para>

<para>
Since version .NET 7.0 of the compiler, ISO/ANSI compliance is
required.
</para>

<para>
See <xref linkend="sect.ClassCate" /> of the Installation Guide for 
more detailed information.
See also <xref linkend="sect.BldMSV" /> for more tips.
</para>

</sect2>


<!-- ******************* Section (Level#2) ****************** -->
<sect2 id="sect.TpPrgCmp.McXCpp">
<title>
MacOS-X - g++
</title>

<para>
OS: MacOS/Darwin
</para>

<para>
Compiler: GNU/gcc
</para>

<para>
The setup adopted for the <literal>g++</literal> compiler on MacOS
resembles in great part the one for Linux systems.
</para>

<para>
The default optimisation level in this case is <literal>-O2</literal>.
</para>

<para>
Dynamic libraries (<literal>.dylib</literal>) are supported as well; once
built, in order to run the generated application, the user must
specify the absolute path in the system where they're installed
with the <literal>DYLD_LIBRARY_PATH</literal> system variable.
</para>


</sect2>
</sect1>