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

Last change on this file since 1358 was 1208, checked in by garnier, 16 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.