source: trunk/documents/UserDoc/UsersGuides/ForApplicationDeveloper/html/Appendix/makeFile.html @ 1231

Last change on this file since 1231 was 1208, checked in by garnier, 15 years ago

CVS update
File size: 20.7 KB
Line 
1<HTML>
2<TITLE>
3</TITLE>
4
5<BODY>
6<TABLE WIDTH="100%"><TR>
7<TD>
8
9
10<A HREF="index.html">
11<IMG SRC="../../../../resources/html/IconsGIF/Contents.gif" ALT="Contents"></A>
12<A HREF="templateLib.html">
13<IMG SRC="../../../../resources/html/IconsGIF/Previous.gif" ALT="Previous"></A>
14<A HREF="buildFile.html">
15<IMG SRC="../../../../resources/html/IconsGIF/Next.gif" ALT="Next"></A>
16</TD>
17<TD ALIGN="Right">
18<FONT SIZE="-1" COLOR="#238E23">
19<B>Geant4 User's Guide</B>
20<BR>
21<B>For Application Developers</B>
22<BR>
23<B>Appendix</B>
24</FONT>
25</TD>
26</TR></TABLE>
27<BR><BR>
28
29<P ALIGN="Center">
30<FONT SIZE="+3" COLOR="#238E23">
31<A name="10.5">
32<B>10.5 Makefiles and Environment Variables</B></A>
33</FONT>
34<BR><BR>
35
36<HR ALIGN="Center" SIZE="7%">
37<BR><BR>
38
39<!-- ============================================== Section --> 
40This section describes how the GNUmake infrastructure is implemented in
41Geant4 and provides a quick reference guide for the user/installer
42about the most important environment variables defined.
43<P>
44
45<A name="10.5.1">
46<H2>10.5.1 The GNUmake system in Geant4</H2></A>
47
48As described in <A HREF="../../../InstallationGuide/html/UnixMachines/unixMachines.html#2.1">section
492.1</A> of the Installation Guide, the GNUmake process in
50Geant4 is mainly controlled by the following GNUmake script files
51(<KBD>*.gmk</KBD> scripts are placed in <KBD>$G4INSTALL/config</KBD>):
52<UL>
53<LI><KBD>architecture.gmk</KBD>: defining all the architecture specific
54    settings and paths. System settings are stored in
55    <KBD>$G4INSTALL/config/sys</KBD> in separate files.
56<LI><KBD>common.gmk</KBD>: defining all general GNUmake rules for building
57    objects and libraries.
58<LI><KBD>globlib.gmk</KBD>: defining all general GNUmake rules for building
59    compound libraries.
60<LI><KBD>binmake.gmk</KBD>: defining the general GNUmake rules for building
61    executables.
62<LI><KBD>GNUmake</KBD> scripts: placed inside each directory in the G4
63    distribution and defining directives specific to build a library (or a
64    set of sub-libraries) or and executable.
65</UL>
66
67To build a single library (or a set of sub-libraries) or an executable,
68you must explicitly change your current directory to the one you're
69interested in and invoke the "<KBD>gmake</KBD>" command from there
70("<KBD>gmake global</KBD>" for building a compound library).
71Here is a list of the basic commands or GNUmake "targets" one can
72invoke to build libraries and/or executables:
73<UL>
74<LI><KBD>gmake</KBD><BR>
75  starts the compilation process for building a kernel
76  library or a library associated with an example.
77  Kernel libraries are built with maximum granularity, i.e. if a category
78  is a compound, this command will build all the related sub-libraries,
79  <b>not</b> the compound one.  The top level <KBD>GNUmakefile</KBD> in
80  <KBD>$G4INSTALL/source</KBD> will also build in this case a dependency
81  map <KBD>libname.map</KBD> of each library to establish the linking order
82  automatically at the <KBD>bin</KBD> step. The map will be placed in
83  <KBD>$G4LIB/$G4SYSTEM</KBD>.
84<LI><KBD>gmake global</KBD><BR>
85  starts the compilation process to build a single compound kernel
86  library per category. If issued after "gmake", both
87  'granular' and 'compound' libraries will be available (NOTE: this will
88  consistently increase the disk space required. Compound libraries will then
89  be selected by default at link time, unless G4LIB_USE_GRANULAR is specified).
90<LI><KBD>gmake bin</KBD> or <KBD>gmake</KBD> (only for examples/)<BR>
91  starts the compilation process to build an executable.
92  This command will build implicitly the library associated with
93  the example and link the final application. It assumes <b>all</b>
94  kernel libraries are already generated and placed in the
95  correct <KBD>$G4INSTALL</KBD> path defined for them.<BR>
96  The linking order is controlled automatically in case libraries have been
97  built with maximum granularity, and the link list is generated on the fly.
98<LI><KBD>make dll</KBD><BR>
99  On Windows systems this will start the compilation process to build single
100  compound kernel library per category and generate Dynamic Link Libraries
101  (DLLs).
102  Once the libraries are generated, the process will imply also the deletion
103  of all temporary files generated during the compilation.
104</UL>
105
106<B><KBD>lib/ bin/</KBD> and <KBD>tmp/</KBD> directories</B>
107<P>
108The <KBD>$G4INSTALL</KBD> environment variable specifies where the
109installation of
110the Geant4 toolkit should take place, therefore kernel libraries will
111be placed in <KBD>$G4INSTALL/lib</KBD>.
112The <KBD>$G4WORKDIR</KBD> environment variable is set by the user and
113specifies
114the path to the user working directory; temporary files (object-files
115and data products of the installation process of Geant4) will be placed
116in <KBD>$G4WORKDIR/tmp</KBD>, according to the system architecture used.
117Binaries will be placed in <KBD>$G4WORKDIR/bin</KBD>, according to the
118system architecture used.
119The path to <KBD>$G4WORKDIR/bin/$G4SYSTEM</KBD> should be added to
120<KBD>$PATH</KBD> in the user environment.
121<P>
122
123<!-- ============================================== Section --> 
124<HR>
125<A name="10.5.2">
126<H2>10.5.2 Environment variables</H2></A>
127
128Here is a list of the most important environment variables defined
129within the Geant4 <TT>GNUmake</TT> infrastructure, with a short explanation of
130their use.<BR>
131<b>We recommend that those environment variables listed here and marked
132with (*) NOT be overriden or set (explicitly or by accident).
133They are already set and used internally in the default setup !</b>
134
135<UL>
136  <LI>System configuration
137    <P> $CLHEP_BASE_DIR<BR>
138      Specifies the path where the CLHEP package is installed in your system.
139    <P> $G4SYSTEM<BR>
140      Defines the architecture and compiler currently used.<BR>
141      <B>NOTE</B>: This variable is set automatically if the <TT>Configure</TT> script
142      is adopted for the installation. This will result in the proper settings also
143      for configuring the environment with the generated shell scripts <TT>env.[c]sh</TT>.
144    <P> 
145  <LI>Installation paths
146    <P> $G4INSTALL<BR>
147      Defines the path where the Geant4 toolkit should be installed. It should
148      be set by the system installer. By default, it sets to <TT>$HOME/geant4</TT>,
149      assuming the Geant4 distribution is placed in <TT>$HOME</TT>.
150    <P> $G4BASE <B>(*)</B><BR>
151      Defines the path to the source code.
152      Internally used to define <TT>$CPPFLAGS</TT> 
153      and <TT>$LDFLAGS</TT> for -I and -L directives.
154      It has to be set to <TT>$G4INSTALL/src</TT>.
155    <P> $G4WORKDIR<BR>
156      Defines the path for the user's workdir for Geant4. It is set by default
157      to <TT>$HOME/geant4</TT>, assuming the user's working directory for
158      Geant4 is placed in <TT>$HOME</TT>.
159    <P> $G4INCLUDE<BR>
160      Defines the path where source header files may be mirrored at installation
161      by issuing <TT>gmake includes</TT>
162      (default is set to <TT>$G4INSTALL/include</TT>)
163    <P> $G4BIN,<BR>
164        $G4BINDIR <B>(*)</B><BR>
165      Used by the system to specify the place where to store executables. By default
166      they're set to <TT>$G4WORKDIR/bin</TT> and <TT>$G4BIN/$G4SYSTEM</TT>
167      respectively. The path to <TT>$G4WORKDIR/bin/$G4SYSTEM</TT> should be added
168      to <TT>$PATH</TT> in the user environment. <TT>$G4BIN</TT> can be overridden.
169    <P> $G4TMP,<BR>
170        $G4TMPDIR <B>(*)</B><BR>
171      Used by the system to specify the place where to store temporary files products
172      of the compilation/build of a user application or test. By default they're
173      set to <TT>$G4WORKDIR/tmp</TT> and <TT>$G4TMP/$G4SYSTEM</TT> respectively.
174      <TT>$G4TMP</TT> can be overridden.
175    <P> $G4LIB,<BR>
176      $G4LIBDIR <B>(*)</B><BR>
177      Used by the system to specify the place where to store libraries. By default
178      they're set to <TT>$G4INSTALL/lib</TT> and <TT>$G4LIB/$G4SYSTEM</TT>
179      respectively. <TT>$G4LIB</TT> can be overridden.
180    <P> 
181  <LI>Build specific
182    <P> $G4TARGET<BR>
183      Specifies the target (name of the source file defining the main()) of the
184      application/example to be built. This variable is set automatically for
185      the examples and tests placed in <TT>$G4INSTALL/examples</TT>.
186    <P> $G4EXEC_BUILD<BR>
187      Flag specifying if to use a secondary template repository or not for handling
188      template instantiations at the time of building a user application/example.
189      For internal category tests in Geant4, this variable is already in the related
190      GNUmakefile. It's however not needed for examples and tests in
191      <TT>$G4INSTALL/examples</TT>, where class names are already mangled and
192      different each other. It applies only on those compilers which make use of template
193      repositories (see Appendix A.2 of this Guide). The secondary template repository
194      is set to <TT>$G4TREP/exec</TT>.
195    <P> $G4DEBUG<BR>
196      Specifies to compile the code (libraries or examples) including symbolic
197      information in the object code for debugging. The size of the generated
198      object code can increase considerably. By default, code is compiled in optimised
199      mode (<TT>$G4OPTIMISE</TT> set).
200    <P> $G4NO_OPTIMISE<BR>
201      Specifies to compile the code (libraries or examples) without compiler optimisation.
202    <P> $G4NO_STD_EXCEPTIONS <B>(*)</B><BR>
203      To avoid throwing of exceptions in Geant4.
204    <P> $G4_NO_VERBOSE<BR>
205      Geant4 code is compiled by default in high verbosity mode (<TT>$G4VERBOSE</TT>
206      flag set). For better performance, verbosity code can be left out by defining
207      <TT>$G4_NO_VERBOSE</TT>.
208    <P> $G4LIB_BUILD_SHARED<BR>
209      Flag specifying if to build kernel libraries as shared libraries (libraries
210      will be then used by default). If not set, static archive libraries are
211      built by default.
212    <P> $G4LIB_BUILD_STATIC<BR>
213      Flag specifying if to build kernel libraries as static archive libraries
214      in addition to shared libraries (in case <TT>$G4LIB_BUILD_SHARED</TT>
215      is set as well).
216    <P> $G4LIB_BUILD_DLL <B>(*)</B><BR>
217      Internal flag for specifying to build DLL kernel libraries for Windows
218      systems. The flag is automatically set when requested to build DLLs.
219    <P> $G4LIB_USE_DLL<BR>
220      For Windows systems only. Flag to specify to build an application using
221      the installed DLL kernel libraries for Windows systems. It is required
222      to have this flag set in the environment in order to successfully build
223      an application if the DLL libraries have been installed.
224    <P> $G4LIB_USE_GRANULAR<BR>
225      To force usage of "granular" libraries against "compound" libraries at link
226      time in case both have been installed. The Geant4 building system chooses
227      "compound" libraries by default, if installed.
228</UL>
229<UL>
230  <LI>UI specific
231    <P> The most relevant flags for User Interface drivers are just listed here.
232      A more detailed description is given also in section 2. of this User's Guide.
233    <P> G4UI_USE_TERMINAL<BR>
234      Specifies to use dumb terminal interface in the application to be built
235      (default).
236    <P> G4UI_USE_TCSH<BR>
237      Specifies to use the tcsh-shell like interface in the application to be built.
238    <P> G4UI_BUILD_XM_SESSION, G4UI_BUILD_XAW_SESSION<BR>
239      Specifies to include in kernel library the <I>XM</I> or <I>XAW</I> Motif-based
240      user interfaces.
241    <P> G4UI_USE_XM, G4UI_USE_XAW<BR>
242      Specifies to use the <I>XM</I> or <I>XAW</I> interfaces in the application
243      to be built.
244    <P> G4UI_USE_QT<BR>
245      Specifies to use the <I>Qt</I> interfaces in the application to be built.
246    <P> G4UI_BUILD_WIN32_SESSION<BR>
247      Specifies to include in kernel library the WIN32 terminal interface for
248      Windows systems.
249    <P> G4UI_USE_WIN32<BR>
250      Specifies to use the WIN32 interfaces in the application to be built on
251      Windows systems.
252    <P> G4UI_NONE<BR>
253      If set, no UI sessions nor any UI libraries are built. This can be useful
254      when running a pure batch job or in a user framework having its own UI system.
255</UL>
256<UL>
257  <LI>Visualization specific
258    <P> The most relevant flags for visualization graphics drivers are just listed
259      here. A description of these variables is given also in section 2. of this
260      User's Guide.
261    <P> $G4VIS_BUILD_OPENGLX_DRIVER<BR>
262      Specifies to build kernel library for visualization including the OpenGL
263      driver with X11 extension. It requires <TT>$OGLHOME</TT> set (path to
264      OpenGL installation).
265    <P> $G4VIS_USE_OPENGLX<BR>
266      Specifies to use OpenGL graphics with X11 extension in the application to
267      be built.
268    <P> $G4VIS_BUILD_OPENGLXM_DRIVER<BR>
269      Specifies to build kernel library for visualization including the OpenGL
270      driver with XM extension. It requires <TT>$OGLHOME</TT> set (path to
271      OpenGL installation).
272    <P> $G4VIS_USE_OPENGLXM<BR>
273      Specifies to use OpenGL graphics with XM extension in the application to
274      be built.
275    <P> $G4VIS_BUILD_QT_DRIVER<BR>
276      Specifies to build kernel library for visualization including the Qt
277      driver.
278    <P> $G4VIS_USE_QT<BR>
279      Specifies to use Qt graphics in the application to be built.
280    <P> $G4VIS_BUILD_OI_DRIVER<BR>
281      Specifies to build kernel library for visualization including the OpenInventor
282      driver. It requires <TT>$OIHOME</TT> set (paths to the <TT>OpenInventor</TT>
283      installation).
284    <P> $G4VIS_USE_OI<BR>
285      Specifies to use OpenInventor graphics in the application to be built.
286    <P> $G4VIS_BUILD_OIX_DRIVER<BR>
287      Specifies to build the driver for the free X11 version of OpenInventor.
288    <P> $G4VIS_USE_OIX<BR>
289      Specifies to use the free X11 version of OpenInventor.
290    <P> $G4VIS_BUILD_RAYTRACERX_DRIVER<BR>
291      Specifies to build kernel library for visualization including the
292      Ray-Tracer driver with X11 extension. It requires <TT>X11</TT> installed
293      in the system.
294    <P> $G4VIS_USE_RAYTRACERX<BR>
295      Specifies to use the X11 version of the Ray-Tracer driver.
296    <P> $G4VIS_BUILD_OIWIN32_DRIVER<BR>
297      Specifies to build the driver for the free X11 version of OpenInventor
298      on Windows systems.
299    <P> $G4VIS_USE_OIWIN32<BR>
300      Specifies to use the free X11 version of OpenInventor on Windows systems.
301    <P> $G4VIS_BUILD_DAWN_DRIVER<BR>
302      Specifies to build kernel library for visualization including the driver
303      for DAWN.
304    <P> $G4VIS_USE_DAWN<BR>
305      Specifies to use DAWN as a possible graphics renderer in the application
306      to be built.
307    <P> $G4DAWN_HOST_NAME<BR>
308      To specify the hostname for use with the DAWN-network driver.
309    <P> $G4VIS_NONE<BR>
310      If specified, no visualization drivers will be built or used.
311</UL>
312<UL>
313  <LI><TT>hadronic_lists</TT> module
314    <P> $G4LIB_BUILD_LISTS<BR>
315      Specifies to build or not the <TT>physics_lists</TT> module.
316      By default, the variable is set and the module is built.
317      Set it to <TT>NO</TT> to skip the compilation of the physics lists.
318</UL>
319<UL>
320  <LI><TT>zlib</TT> and <TT>g3tog4</TT> modules
321    <P> $G4LIB_BUILD_ZLIB<BR>
322      If set, triggers compilation of a specific <TT>zlib</TT> module for
323      the compression of output files (mainly in use currently for the HepRep
324      graphics driver). By default, the flag is not set and the built-in system
325      library for compression is adopted instead. Setting this flag will also
326      implicitely set the flag below.
327    <P> $G4LIB_USE_ZLIB<BR>
328      Specifies to use the <TT>zlib</TT> module, either system built-in or
329      Geant4 specific.
330    <P> $G4LIB_BUILD_G3TOG4<BR>
331      If set, triggers compilation of the <TT>g3tog4</TT> module for conversions
332      of simple legacy geometries descriptions to Geant4. By default, the flag is
333      not set and the module's library is not built. Setting this flag will also
334      implicitely set the flag below.
335    <P> $G4LIB_USE_G3TOG4<BR>
336      Specifies to use the <TT>g3tog4</TT> module, assuming the related library
337      has been already installed.
338</UL>
339<UL>
340  <LI>Analysis specific
341    <P> $G4ANALYSIS_USE<BR>
342      Specifies to activate the appropriate environment for analysis, if an application
343      includes code for histogramming based on <I>AIDA</I>. Additional setup variables
344      are required (<TT>$G4ANALYSIS_AIDA_CONFIG_CFLAGS</TT>,
345      <TT>$G4ANALYSIS_AIDA_CONFIG_LIBS</TT>) to define config options for AIDA
346      ("<TT>aida-config --cflags</TT>" and "<TT>aida-config --libs</TT>").
347      See installation instructions of the specific analysis tools for details.
348</UL>
349<UL>
350  <LI>Directory paths to Physics Data
351    <P> $NeutronHPCrossSections<BR>
352      Path to external data set for Neutron Scattering processes.
353    <P> $G4LEDATA<BR>
354      Path to external data set for low energy electromagnetic processes.
355    <P> $G4LEVELGAMMADATA<BR>
356      Path to the data set for Photon Evaporation.
357    <P> $G4RADIOACTIVEDATA<BR>
358      Path to the data set for Radiative Decay processes.
359</UL>
360
361<!-- ============================================== Section --> 
362<HR>
363<A name="10.5.3">
364<H2>10.5.3 Linking External Libraries with Geant4</H2></A>
365
366The Geant4 GNUmake infrastructure allows to extend the link list of
367libraries with external (or user defined) packages which may be required
368for some user's applications to generate the final executable.
369<P>
370
371<A name="10.5.3.1">
372<H3>10.5.3.1 Adding external libraries which do *not* use Geant4</H3></A>
373
374In the <TT>GNUmakefile</TT> of your application, before including
375<TT>binmake.gmk</TT>, specify the extra library in <TT>EXTRALIBS</TT>
376either using the <TT>-L...-l...</TT> syntax or by specifying the full
377pathname, e.g.:
378
379<PRE>
380  EXTRALIBS := -L&lt;your-path&gt;/lib -l&lt;myExtraLib&gt;
381or
382  EXTRALIBS := &lt;your-path&gt;/lib/lib&lt;myExtraLib&gt;.a
383</PRE>
384
385You may also specify <TT>EXTRA_LINK_DEPENDENCIES</TT>, which is added to the
386dependency of the target executable, and you may also specify a rule for
387making it, e.g.:
388
389<PRE>
390  EXTRA_LINK_DEPENDENCIES := &lt;your-path&gt;/lib/lib&lt;myExtraLib&gt;.a
391
392  &lt;your-path&gt;/lib/lib&lt;myExtraLib&gt;.a:
393        cd &lt;your-path&gt;/lib; $(MAKE)
394</PRE>
395
396Note that you almost certainly need to augment <TT>CPPFLAGS</TT> for
397the header files of the external library, e.g.:
398
399<PRE>
400  CPPFLAGS+=-I&lt;your-path&gt;/include
401</PRE>
402
403See table 10.5.1.
404<P>
405<CENTER><TABLE BORDER=1 CELLPADDING=8>
406<TR><TD>
407<PRE>
408 # --------------------------------------------------------------------
409 # GNUmakefile for the application "sim" depending on module "Xplotter"
410 # --------------------------------------------------------------------
411
412 name := sim
413 G4TARGET := $(name)
414 G4EXLIB := true
415
416 CPPFLAGS  += -I$(HOME)/Xplotter/include
417 EXTRALIBS += -L$(HOME)/Xplotter/lib -lXplotter
418 EXTRA_LINK_DEPENDENCIES := $(HOME)/Xplotter/lib/libXplotter.a
419
420 .PHONY: all
421
422 all: lib bin
423
424 include $(G4INSTALL)/config/binmake.gmk
425
426 $(HOME)/Xplotter/lib/libXplotter.a:
427         cd $(HOME)/Xplotter; $(MAKE)</PRE>
428<TR>
429<TD ALIGN=CENTER>
430 Table 10.5.1<BR>
431 An example of a customised GNUmakefile for an application or example
432 using an external module not bound to Geant4.
433</TABLE></CENTER>
434<P>
435
436<A name="10.5.3.2">
437<H3>10.5.3.2 Adding external libraries which use Geant4</H3></A>
438
439In addition to the above, specify, in <TT>EXTRALIBSSOURCEDIRS</TT>, a list of
440directories containing source files in its <TT>src/</TT> subdirectory.
441Thus, your <TT>GNUmakefile</TT> might contain:
442
443<PRE>
444  EXTRALIBS += $(G4WORKDIR)/tmp/$(G4SYSTEM)/&lt;myApp&gt;/lib&lt;myApp&gt;.a \
445               -L&lt;your-path&gt;/lib -l&lt;myExtraLib&gt;
446  EXTRALIBSSOURCEDIRS += &lt;your-path&gt;/&lt;myApp&gt; &lt;your-path&gt;/&lt;MyExtraModule&gt;
447  EXTRA_LINK_DEPENDENCIES := $(G4WORKDIR)/tmp/$(G4SYSTEM)/&lt;myApp&gt;/lib&lt;myApp&gt;.a
448
449  MYSOURCES := $(wildcard &lt;your-path&gt;/&lt;myApp&gt;/src/*cc)
450  $(G4WORKDIR)/tmp/$(G4SYSTEM)/&lt;myApp&gt;/lib&lt;myApp&gt;.a: $(MYSOURCES)
451        cd &lt;your-path&gt;/&lt;myApp&gt;; $(MAKE)
452</PRE>
453
454See Table 10.5.2.
455<P>
456
457<CENTER><TABLE BORDER=1 CELLPADDING=8>
458<TR><TD>
459<PRE>
460# -----------------------------------------------------------------
461# GNUmakefile for the application "phys" depending on module "reco"
462# -----------------------------------------------------------------
463
464name := phys
465G4TARGET := $(name)
466G4EXLIB := true
467
468EXTRALIBS += $(G4WORKDIR)/tmp/$(G4SYSTEM)/$(name)/libphys.a \
469             -L$(HOME)/reco/lib -lreco
470EXTRALIBSSOURCEDIRS += $(HOME)/phys $(HOME)/reco
471EXTRA_LINK_DEPENDENCIES := $(G4WORKDIR)/tmp/$(G4SYSTEM)/$(name)/libphys.a
472
473.PHONY: all
474all: lib bin
475
476include $(G4INSTALL)/config/binmake.gmk
477
478MYSOURCES := $(wildcard $(HOME)/phys/src/*cc)
479$(G4WORKDIR)/tmp/$(G4SYSTEM)/$(name)/libphys.a: $(MYSOURCES)
480        cd $(HOME)/phys; $(MAKE)</PRE>
481<TR>
482<TD ALIGN=CENTER>
483 Table 10.5.2<BR>
484 An example of a customised GNUmakefile for an application or example
485 using external modules bound to Geant4.
486</TABLE></CENTER>
487<P>
488<HR>
489<A HREF="../../../../Authors/html/subjectsToAuthors.html">
490<I>About the authors</I></A>
491
492</BODY>
493</HTML>
494
495
496
497
Note: See TracBrowser for help on using the repository browser.