source: trunk/documents/UserDoc/DocBookUsersGuides/ForApplicationDeveloper/xml/Appendix/makeFile.xml @ 978

Last change on this file since 978 was 904, checked in by garnier, 16 years ago

ajout de la doc
File size: 30.9 KB
Line 
1<!-- ******************************************************** -->
2<!--                                                          -->
3<!--  [History]                                               -->
4<!--    Converted to DocBook: Katsuya Amako, Aug-2006         -->
5<!--                                                          -->
6<!-- ******************************************************** -->
7
8
9<!-- ******************* Section (Level#1) ****************** -->
10<sect1 id="sect.MkflEnvVar">
11<title>
12Makefiles and Environment Variables
13</title>
14
15<para>
16This section describes how the GNUmake infrastructure is
17implemented in Geant4 and provides a quick reference guide for the
18user/installer about the most important environment variables
19defined.
20</para>
21
22<!-- ******************* Section (Level#2) ****************** -->
23<sect2 id="sect.MkflEnvVar.GNUG4">
24<title>
25The GNUmake system in Geant4
26</title>
27
28<para>
29As described in <xref linkend="sect.HowToDefMain" /> of the
30Installation Guide, the GNUmake process in
31Geant4 is mainly controlled by the following GNUmake script files
32(<literal>*.gmk</literal> scripts are placed in
33<literal>$G4INSTALL/config</literal>):
34
35<itemizedlist spacing="compact">
36  <listitem><para>
37    <literal>architecture.gmk</literal>: defining all the architecture
38    specific settings and paths. System settings are stored in
39    <literal>$G4INSTALL/config/sys</literal> in separate files.
40  </para></listitem>
41  <listitem><para>
42    <literal>common.gmk</literal>: defining all general GNUmake rules for
43    building objects and libraries.
44  </para></listitem>
45  <listitem><para>
46    <literal>globlib.gmk</literal>: defining all general GNUmake rules for
47    building compound libraries.
48  </para></listitem>
49  <listitem><para>
50    <literal>binmake.gmk</literal>: defining the general GNUmake rules for
51    building executables.
52  </para></listitem>
53  <listitem><para>
54    <literal>GNUmake</literal> scripts: placed inside each directory in the
55    G4 distribution and defining directives specific to build a library
56    (or a set of sub-libraries) or and executable.
57  </para></listitem>
58</itemizedlist>
59</para>
60
61<para>
62To build a single library (or a set of sub-libraries) or an
63executable, you must explicitly change your current directory to
64the one you're interested in and invoke the "<literal>gmake</literal>"
65command from there ("<literal>gmake global</literal>" for building a
66compound library). Here is a list of the basic commands or GNUmake
67"targets" one can invoke to build libraries and/or executables:
68
69<itemizedlist spacing="compact">
70  <listitem><para>
71    <literal>gmake</literal>
72    <para>
73    starts the compilation process for building a kernel library or a
74    library associated with an example. Kernel libraries are built with
75    maximum granularity, i.e. if a category is a compound, this command 
76    will build all the related sub-libraries,
77    <emphasis role="bold">not</emphasis> the compound one.
78    The top level <literal>GNUmakefile</literal> in
79    <literal>$G4INSTALL/source</literal> will also build in this case a
80    dependency map <literal>libname.map</literal> of each library to establish
81    the linking order automatically at the <literal>bin</literal> step. The map
82    will be placed in <literal>$G4LIB/$G4SYSTEM</literal>.
83    </para>
84  </para></listitem>
85  <listitem><para>
86    <literal>gmake global</literal>
87    <para>
88    starts the compilation process to build a single compound kernel
89    library per category. If issued after "gmake", both 'granular' and
90    'compound' libraries will be available (NOTE: this will
91    consistently increase the disk space required. Compound libraries
92    will then be selected by default at link time, unless
93    G4LIB_USE_GRANULAR is specified).
94    </para>
95  </para></listitem>
96  <listitem><para>
97    <literal>gmake bin</literal> or <literal>gmake</literal> (only for
98    examples/)
99    <para>
100    starts the compilation process to build an executable. This command
101    will build implicitly the library associated with the example and
102    link the final application. It assumes <emphasis role="bold">all</emphasis> 
103    kernel libraries are already generated and placed in the correct
104    <literal>$G4INSTALL</literal> path defined for them.
105    </para>
106
107    <para>
108    The linking order is controlled automatically in case libraries
109    have been built with maximum granularity, and the link list is
110    generated on the fly.
111    </para>
112  </para></listitem>
113  <listitem><para>
114    <literal>make dll</literal>
115    <para>
116    On Windows systems this will start the compilation process to build
117    single compound kernel library per category and generate Dynamic
118    Link Libraries (DLLs). Once the libraries are generated, the
119    process will imply also the deletion of all temporary files
120    generated during the compilation.
121    </para>
122  </para></listitem>
123</itemizedlist>
124</para>
125
126<!-- ******* Bridgehead ******* -->
127<bridgehead renderas='sect4'>
128<literal>lib/ bin/</literal> and <literal>tmp/</literal> directories
129</bridgehead>
130
131<para>
132The <literal>$G4INSTALL</literal> environment variable specifies where
133the installation of the Geant4 toolkit should take place, therefore
134kernel libraries will be placed in <literal>$G4INSTALL/lib</literal>. The
135<literal>$G4WORKDIR</literal> environment variable is set by the user and
136specifies the path to the user working directory; temporary files
137(object-files and data products of the installation process of
138Geant4) will be placed in <literal>$G4WORKDIR/tmp</literal>, according to
139the system architecture used. Binaries will be placed in
140<literal>$G4WORKDIR/bin</literal>, according to the system architecture
141used. The path to <literal>$G4WORKDIR/bin/$G4SYSTEM</literal> should be
142added to <literal>$PATH</literal> in the user environment.
143</para>
144
145</sect2>
146
147
148<!-- ******************* Section (Level#2) ****************** -->
149<sect2 id="sect.MkflEnvVar.EnvVar">
150<title>
151Environment variables
152</title>
153
154<para>
155Here is a list of the most important environment variables defined
156within the Geant4 <literal>GNUmake</literal> infrastructure, with a short
157explanation of their use.
158</para>
159
160<para>
161<emphasis role="bold">We recommend that those environment variables listed here and
162marked with (*) NOT be overriden or set (explicitly or by
163accident). They are already set and used internally in the default
164setup !</emphasis>
165</para>
166
167<!-- ******* Bridgehead ******* -->
168<bridgehead renderas='sect4'>
169System configuration
170</bridgehead>
171
172<para>
173<variablelist>
174  <varlistentry>
175    <term>
176      $CLHEP_BASE_DIR
177    </term>
178    <listitem>
179      Specifies the path where the CLHEP package is installed in your system.
180    </listitem>
181  </varlistentry>
182  <varlistentry>
183    <term>
184      $G4SYSTEM
185    </term>
186    <listitem>
187      <para> 
188      Defines the architecture and compiler currently used.
189      </para>
190      <para> 
191      <emphasis role="bold">NOTE</emphasis>: This variable is set automatically
192      if the <literal>Configure</literal> script is adopted for the
193      installation. This will result in the proper settings also for
194      configuring the environment with the generated shell scripts
195      <literal>env.[c]sh</literal>.
196      </para>
197    </listitem>
198  </varlistentry>
199</variablelist>
200</para>
201
202
203
204<!-- ******* Bridgehead ******* -->
205<bridgehead renderas='sect4'>
206Installation paths
207</bridgehead>
208
209<para>
210<variablelist>
211  <varlistentry>
212    <term>
213      $G4INSTALL
214    </term>
215    <listitem>
216      Defines the path where the Geant4 toolkit should be installed. It
217      should be set by the system installer. By default, it sets to
218      <literal>$HOME/geant4</literal>, assuming the Geant4 distribution
219      is placed in <literal>$HOME</literal>.
220    </listitem>
221  </varlistentry>
222  <varlistentry>
223    <term>
224      $G4BASE <emphasis role="bold">(*)</emphasis>
225    </term>
226    <listitem>
227      Defines the path to the source code. Internally used to define
228      <literal>$CPPFLAGS</literal> and <literal>$LDFLAGS</literal> for
229      -I and -L directives. It has to be set to
230      <literal>$G4INSTALL/src</literal>.
231    </listitem>
232  </varlistentry>
233  <varlistentry>
234    <term>
235      $G4WORKDIR
236    </term>
237    <listitem>
238      Defines the path for the user's workdir for Geant4. It is set by
239      default to <literal>$HOME/geant4</literal>, assuming the user's
240      working directory for Geant4 is placed in <literal>$HOME</literal>.
241    </listitem>
242  </varlistentry>
243  <varlistentry>
244    <term>
245      $G4INCLUDE
246    </term>
247    <listitem>
248      Defines the path where source header files may be mirrored at
249      installation by issuing <literal>gmake includes</literal> (default
250      is set to <literal>$G4INSTALL/include</literal>)
251    </listitem>
252  </varlistentry>
253  <varlistentry>
254    <term>
255      $G4BIN, $G4BINDIR <emphasis role="bold">(*)</emphasis>
256    </term>
257    <listitem>
258      Used by the system to specify the place where to store executables.
259      By default they're set to <literal>$G4WORKDIR/bin</literal> and
260      <literal>$G4BIN/$G4SYSTEM</literal> respectively. The path to
261      <literal>$G4WORKDIR/bin/$G4SYSTEM</literal> should be added to
262      <literal>$PATH</literal> in the user environment.
263      <literal>$G4BIN</literal> can be overridden.
264    </listitem>
265  </varlistentry>
266  <varlistentry>
267    <term>
268      $G4TMP, $G4TMPDIR <emphasis role="bold">(*)</emphasis>
269    </term>
270    <listitem>
271      Used by the system to specify the place where to store temporary
272      files products of the compilation/build of a user application or
273      test. By default they're set to <literal>$G4WORKDIR/tmp</literal> 
274      and <literal>$G4TMP/$G4SYSTEM</literal> respectively.
275      <literal>$G4TMP</literal> can be overridden.
276    </listitem>
277  </varlistentry>
278  <varlistentry>
279    <term>
280      $G4LIB, $G4LIBDIR <emphasis role="bold">(*)</emphasis>
281    </term>
282    <listitem>
283      Used by the system to specify the place where to store libraries.
284      By default they're set to <literal>$G4INSTALL/lib</literal> and
285      <literal>$G4LIB/$G4SYSTEM</literal> respectively.
286      <literal>$G4LIB</literal> can be overridden.
287    </listitem>
288  </varlistentry>
289</variablelist>
290</para>
291
292<!-- ******* Bridgehead ******* -->
293<bridgehead renderas='sect4'>
294Build specific
295</bridgehead>
296
297<para>
298<variablelist>
299  <varlistentry>
300    <term>
301      $G4TARGET
302    </term>
303    <listitem>
304      Specifies the target (name of the source file defining the main())
305      of the application/example to be built. This variable is set
306      automatically for the examples and tests placed in
307      <literal>$G4INSTALL/examples</literal>.
308    </listitem>
309  </varlistentry>
310  <varlistentry>
311    <term>
312      $G4EXEC_BUILD
313    </term>
314    <listitem>
315      Flag specifying if to use a secondary template repository or not
316      for handling template instantiations at the time of building a user
317      application/example. For internal category tests in Geant4, this
318      variable is already in the related GNUmakefile. It's however not
319      needed for examples and tests in <literal>$G4INSTALL/examples</literal>,
320      where class names are already mangled and different each other. It
321      applies only on those compilers which make use of template
322      repositories (see Appendix A.2 of this Guide). The secondary
323      template repository is set to <literal>$G4TREP/exec</literal>.
324    </listitem>
325  </varlistentry>
326  <varlistentry>
327    <term>
328      $G4DEBUG
329    </term>
330    <listitem>
331      Specifies to compile the code (libraries or examples) including
332      symbolic information in the object code for debugging. The size of
333      the generated object code can increase considerably. By default,
334      code is compiled in optimised mode (<literal>$G4OPTIMISE</literal> set).
335    </listitem>
336  </varlistentry>
337  <varlistentry>
338    <term>
339      $G4NO_OPTIMISE
340    </term>
341    <listitem>
342      Specifies to compile the code (libraries or examples) without
343      compiler optimisation.
344    </listitem>
345  </varlistentry>
346  <varlistentry>
347    <term>
348      $G4OPTDEBUG
349    </term>
350    <listitem>
351      On <literal>Linux</literal> systems with the <literal>g++</literal>
352      compiler, it allows to build in optimised mode including symbolic
353      information for debugging.
354    </listitem>
355  </varlistentry>
356  <varlistentry>
357    <term>
358      $G4PROFILE
359    </term>
360    <listitem>
361      On <literal>Linux</literal> systems with the <literal>g++</literal>
362      compiler, it allows to build libraries with profiling setup for
363      monitoring with the <literal>gprof</literal> tool.
364    </listitem>
365  </varlistentry>
366  <varlistentry>
367    <term>
368      $G4_NO_VERBOSE
369    </term>
370    <listitem>
371      Geant4 code is compiled by default in high verbosity mode
372      (<literal>$G4VERBOSE</literal> flag set). For better performance,
373      verbosity code can be left out by defining <literal>$G4_NO_VERBOSE</literal>.
374    </listitem>
375  </varlistentry>
376  <varlistentry>
377    <term>
378      $G4LIB_BUILD_SHARED
379    </term>
380    <listitem>
381      Flag specifying if to build kernel libraries as shared libraries
382      (libraries will be then used by default). If not set, static
383      archive libraries are built by default.
384    </listitem>
385  </varlistentry>
386  <varlistentry>
387    <term>
388      $G4LIB_BUILD_STATIC
389    </term>
390    <listitem>
391      Flag specifying if to build kernel libraries as static archive
392      libraries in addition to shared libraries (in case
393      <literal>$G4LIB_BUILD_SHARED</literal> is set as well).
394    </listitem>
395  </varlistentry>
396  <varlistentry>
397    <term>
398      $G4LIB_BUILD_DLL <emphasis role="bold">(*)</emphasis>
399    </term>
400    <listitem>
401      Internal flag for specifying to build DLL kernel libraries for
402      Windows systems. The flag is automatically set when requested to
403      build DLLs.
404    </listitem>
405  </varlistentry>
406  <varlistentry>
407    <term>
408      $G4LIB_USE_DLL
409    </term>
410    <listitem>
411      For Windows systems only. Flag to specify to build an application
412      using the installed DLL kernel libraries for Windows systems. It is
413      required to have this flag set in the environment in order to
414      successfully build an application if the DLL libraries have been
415      installed.
416    </listitem>
417  </varlistentry>
418  <varlistentry>
419    <term>
420      $G4LIB_USE_GRANULAR
421    </term>
422    <listitem>
423      To force usage of "granular" libraries against "compound" libraries
424      at link time in case both have been installed. The Geant4 building
425      system chooses "compound" libraries by default, if installed.
426    </listitem>
427  </varlistentry>
428  <varlistentry>
429    <term>
430     
431    </term>
432    <listitem>
433     
434    </listitem>
435  </varlistentry>
436</variablelist>
437</para>
438
439<!-- ******* Bridgehead ******* -->
440<bridgehead renderas='sect4'>
441UI specific
442</bridgehead>
443
444<para>
445The most relevant flags for User Interface drivers are just
446listed here. A more detailed description is given also in section
4472. of this User's Guide.
448</para>
449
450<para>
451<variablelist>
452  <varlistentry>
453    <term>
454      G4UI_USE_TERMINAL
455    </term>
456    <listitem>
457      Specifies to use dumb terminal interface in the application to be
458      built (default).
459    </listitem>
460  </varlistentry>
461  <varlistentry>
462    <term>
463      G4UI_USE_TCSH
464    </term>
465    <listitem>
466      Specifies to use the tcsh-shell like interface in the application
467      to be built.
468    </listitem>
469  </varlistentry>
470  <varlistentry>
471    <term>
472      G4UI_BUILD_XM_SESSION, G4UI_BUILD_XAW_SESSION
473    </term>
474    <listitem>
475      Specifies to include in kernel library the <emphasis>XM</emphasis> or
476      <emphasis>XAW</emphasis> Motif-based user interfaces.
477    </listitem>
478  </varlistentry>
479  <varlistentry>
480    <term>
481      G4UI_USE_XM, G4UI_USE_XAW
482    </term>
483    <listitem>
484      Specifies to use the <emphasis>XM</emphasis> or <emphasis>XAW</emphasis> 
485      interfaces in the application to be built.
486    </listitem>
487  </varlistentry>
488  <varlistentry>
489    <term>
490      G4UI_BUILD_WIN32_SESSION
491    </term>
492    <listitem>
493      Specifies to include in kernel library the WIN32 terminal interface
494      for Windows systems.
495    </listitem>
496  </varlistentry>
497  <varlistentry>
498    <term>
499      G4UI_USE_WIN32
500    </term>
501    <listitem>
502      Specifies to use the WIN32 interfaces in the application to be
503      built on Windows systems.
504    </listitem>
505  </varlistentry>
506  <varlistentry>
507    <term>
508      G4UI_BUILD_QT_SESSION
509    </term>
510    <listitem>
511      Specifies to include in kernel library the Qt terminal interface.
512      <literal>$QTHOME</literal> should specify the path where Qt libraries
513      and headers are installed
514    </listitem>
515  </varlistentry>
516  <varlistentry>
517    <term>
518      G4UI_USE_QT
519    </term>
520    <listitem>
521      Specifies to use the Qt interfaces in the application to be
522      built.
523    </listitem>
524  </varlistentry>
525  <varlistentry>
526    <term>
527      G4UI_NONE
528    </term>
529    <listitem>
530      If set, no UI sessions nor any UI libraries are built. This can be
531      useful when running a pure batch job or in a user framework having
532      its own UI system.
533    </listitem>
534  </varlistentry>
535</variablelist>
536</para>
537
538<!-- ******* Bridgehead ******* -->
539<bridgehead renderas='sect4'>
540Visualization specific
541</bridgehead>
542
543<para>
544The most relevant flags for visualization graphics drivers are
545just listed here. A description of these variables is given also in
546section 2. of this User's Guide.
547</para>
548
549<para>
550<variablelist>
551  <varlistentry>
552    <term>
553      $G4VIS_BUILD_OPENGLX_DRIVER
554    </term>
555    <listitem>
556      Specifies to build kernel library for visualization including the
557      OpenGL driver with X11 extension. It requires <literal>$OGLHOME</literal> 
558      set (path to OpenGL installation).
559    </listitem>
560  </varlistentry>
561  <varlistentry>
562    <term>
563      $G4VIS_USE_OPENGLX
564    </term>
565    <listitem>
566      Specifies to use OpenGL graphics with X11 extension in the
567      application to be built.
568    </listitem>
569  </varlistentry>
570  <varlistentry>
571    <term>
572      $G4VIS_BUILD_OPENGLXM_DRIVER
573    </term>
574    <listitem>
575      Specifies to build kernel library for visualization including the
576      OpenGL driver with XM extension. It requires <literal>$OGLHOME</literal> 
577      set (path to OpenGL installation).
578    </listitem>
579  </varlistentry>
580  <varlistentry>
581    <term>
582      $G4VIS_USE_OPENGLXM
583    </term>
584    <listitem>
585      Specifies to use OpenGL graphics with XM extension in the
586      application to be built.
587    </listitem>
588  </varlistentry>
589  <varlistentry>
590    <term>
591      G4VIS_BUILD_OPENGLQT_DRIVER
592    </term>
593    <listitem>
594      Specifies to build kernel library for visualization including the
595      OpenGL driver with Qt extension. It requires <literal>$QTHOME</literal>
596      set to specify the path where Qt libraries and headers are installed.
597    </listitem>
598  </varlistentry>
599  <varlistentry>
600    <term>
601      G4VIS_USE_OPENGLQT
602    </term>
603    <listitem>
604      Specifies to use OpenGL graphics with Qt extension in the
605      application to be built.
606    </listitem>
607  </varlistentry>
608  <varlistentry>
609    <term>
610      $G4VIS_BUILD_OI_DRIVER
611    </term>
612    <listitem>
613      Specifies to build kernel library for visualization including the
614      OpenInventor driver. It requires <literal>$OIHOME</literal> set
615      (paths to the <literal>OpenInventor</literal> installation).
616    </listitem>
617  </varlistentry>
618  <varlistentry>
619    <term>
620      $G4VIS_USE_OI
621    </term>
622    <listitem>
623      Specifies to use OpenInventor graphics in the application to be
624      built.
625    </listitem>
626  </varlistentry>
627  <varlistentry>
628    <term>
629      $G4VIS_BUILD_OIX_DRIVER
630    </term>
631    <listitem>
632      Specifies to build the driver for the free X11 version of
633      OpenInventor.
634    </listitem>
635  </varlistentry>
636  <varlistentry>
637    <term>
638      $G4VIS_USE_OIX
639    </term>
640    <listitem>
641      Specifies to use the free X11 version of OpenInventor.
642    </listitem>
643  </varlistentry>
644  <varlistentry>
645    <term>
646      $G4VIS_BUILD_RAYTRACERX_DRIVER
647    </term>
648    <listitem>
649      Specifies to build kernel library for visualization including the
650      Ray-Tracer driver with X11 extension. It requires <literal>X11</literal>
651      installed in the system.
652    </listitem>
653  </varlistentry>
654  <varlistentry>
655    <term>
656      $G4VIS_USE_RAYTRACERX
657    </term>
658    <listitem>
659      Specifies to use the X11 version of the Ray-Tracer driver.
660    </listitem>
661  </varlistentry>
662  <varlistentry>
663    <term>
664      $G4VIS_BUILD_OIWIN32_DRIVER
665    </term>
666    <listitem>
667      Specifies to build the driver for the free X11 version of
668      OpenInventor on Windows systems.
669    </listitem>
670  </varlistentry>
671  <varlistentry>
672    <term>
673      $G4VIS_USE_OIWIN32
674    </term>
675    <listitem>
676      Specifies to use the free X11 version of OpenInventor on Windows
677      systems.
678    </listitem>
679  </varlistentry>
680  <varlistentry>
681    <term>
682      $G4VIS_BUILD_DAWN_DRIVER
683    </term>
684    <listitem>
685      Specifies to build kernel library for visualization including the
686      driver for DAWN.
687    </listitem>
688  </varlistentry>
689  <varlistentry>
690    <term>
691      $G4VIS_USE_DAWN
692    </term>
693    <listitem>
694      Specifies to use DAWN as a possible graphics renderer in the
695      application to be built.
696    </listitem>
697  </varlistentry>
698  <varlistentry>
699    <term>
700      $G4DAWN_HOST_NAME
701    </term>
702    <listitem>
703      To specify the hostname for use with the DAWN-network driver.
704    </listitem>
705  </varlistentry>
706  <varlistentry>
707    <term>
708      $G4VIS_NONE
709    </term>
710    <listitem>
711      If specified, no visualization drivers will be built or used.
712    </listitem>
713  </varlistentry>
714</variablelist>
715</para>
716
717<!-- ******* Bridgehead ******* -->
718<bridgehead renderas='sect4'>
719Hadronic physics specific
720</bridgehead>
721
722<para>
723<variablelist>
724  <varlistentry>
725    <term>
726      $G4NEUTRONHP_USE_ONLY_PHOTONEVAPORATION
727    </term>
728    <listitem>
729      When using high precision neutron code, user may choose to force the
730      use of Photon Evaporation model instead of using the neutron capture
731      final state data.
732    </listitem>
733  </varlistentry>
734  <varlistentry>
735    <term>
736      $G4NEUTRONHP_SKIP_MISSING_ISOTOPES
737    </term>
738    <listitem>
739      User can force high precison neutron code to use only exact isotope
740      data files instead of allowing nearby isotope files to be used. If the
741      exact file is not available, the cross section will be set to zero and a
742      warning message will be printed.
743    </listitem>
744  </varlistentry>
745  <varlistentry>
746    <term>
747      $G4NEUTRONHP_NEGLECT_DOPPLER
748    </term>
749    <listitem>
750      Sets neglecting doppler broadening mode for boosting performance.
751    </listitem>
752  </varlistentry>
753</variablelist>
754</para>
755
756<!-- ******* Bridgehead ******* -->
757<bridgehead renderas='sect4'>
758<literal>GDML</literal>, <literal>zlib</literal> and <literal>g3tog4</literal> modules
759</bridgehead>
760
761<para>
762<variablelist>
763  <varlistentry>
764    <term>
765      $G4LIB_BUILD_GDML
766    </term>
767    <listitem>
768      If set, triggers compilation of a plugin module <literal>gdml</literal> 
769      for allowing import/export of detector description setups (geometrical
770      volumes, solids, materials, etc.). By default, the flag is not set; if
771      set, the path to the installation of XercesC package must be specified
772      through the variable <literal>$XERCESCROOT</literal>.
773    </listitem>
774  </varlistentry>
775  <varlistentry>
776    <term>
777      $G4LIB_USE_GDML
778    </term>
779    <listitem>
780      Specifies to use the <literal>gdml</literal> module. The flag is
781      automatically set if <literal>$G4LIB_BUILD_GDML</literal> is set in the environment.
782    </listitem>
783  </varlistentry>
784  <varlistentry>
785    <term>
786      $G4LIB_BUILD_ZLIB
787    </term>
788    <listitem>
789      If set, triggers compilation of a specific <literal>zlib</literal> 
790      module for the compression of output files (mainly in use currently
791      for the HepRep graphics driver). By default, the flag is not set and
792      the built-in system library for compression is adopted instead. Setting
793      this flag will also implicitely set the flag below.
794    </listitem>
795  </varlistentry>
796  <varlistentry>
797    <term>
798      $G4LIB_USE_ZLIB
799    </term>
800    <listitem>
801      Specifies to use the <literal>zlib</literal> module, either system
802      built-in or Geant4 specific.
803    </listitem>
804  </varlistentry>
805  <varlistentry>
806    <term>
807      $G4LIB_BUILD_G3TOG4
808    </term>
809    <listitem>
810      If set, triggers compilation of the <literal>g3tog4</literal> module for
811      conversions of simple legacy geometries descriptions to Geant4. By
812      default, the flag is not set and the module's library is not built.
813      Setting this flag will also implicitely set the flag below.
814    </listitem>
815  </varlistentry>
816  <varlistentry>
817    <term>
818      $G4LIB_USE_G3TOG4
819    </term>
820    <listitem>
821      Specifies to use the <literal>g3tog4</literal> module, assuming the related
822      library has been already installed.
823    </listitem>
824  </varlistentry>
825</variablelist>
826</para>
827
828<!-- ******* Bridgehead ******* -->
829<bridgehead renderas='sect4'>
830Analysis specific
831</bridgehead>
832
833<para>
834<variablelist>
835  <varlistentry>
836    <term>
837      $G4ANALYSIS_USE
838    </term>
839    <listitem>
840      Specifies to activate the appropriate environment for analysis, if
841      an application includes code for histogramming based on
842      <emphasis>AIDA</emphasis>. Additional setup variables are required
843      (<literal>$G4ANALYSIS_AIDA_CONFIG_CFLAGS</literal>,
844      <literal>$G4ANALYSIS_AIDA_CONFIG_LIBS</literal>) to define config options
845      for AIDA ("<literal>aida-config --cflags</literal>" and
846      "<literal>aida-config --libs</literal>"). See installation instructions
847      of the specific analysis tools for details.
848    </listitem>
849  </varlistentry>
850</variablelist>
851</para>
852
853<!-- ******* Bridgehead ******* -->
854<bridgehead renderas='sect4'>
855Directory paths to Physics Data
856</bridgehead>
857
858<para>
859<variablelist>
860  <varlistentry>
861    <term>
862      $G4NEUTRONHPDATA
863    </term>
864    <listitem>
865      Path to external data set for Neutron Scattering processes.
866    </listitem>
867  </varlistentry>
868  <varlistentry>
869    <term>
870      $G4LEDATA
871    </term>
872    <listitem>
873      Path to external data set for low energy electromagnetic
874      processes.
875    </listitem>
876  </varlistentry>
877  <varlistentry>
878    <term>
879      $G4LEVELGAMMADATA
880    </term>
881    <listitem>
882      Path to the data set for Photon Evaporation.
883    </listitem>
884  </varlistentry>
885  <varlistentry>
886    <term>
887      $G4RADIOACTIVEDATA
888    </term>
889    <listitem>
890      Path to the data set for Radiative Decay processes.
891    </listitem>
892  </varlistentry>
893  <varlistentry>
894    <term>
895      $G4ABLADATA
896    </term>
897    <listitem>
898      Path to nuclear shell effects data set for INCL/ABLA hadronic model.
899    </listitem>
900  </varlistentry>
901</variablelist>
902</para>
903
904</sect2>
905
906
907<!-- ******************* Section (Level#2) ****************** -->
908<sect2 id="sect.MkflEnvVar.LnkExtLib">
909<title>
910Linking External Libraries with Geant4
911</title>
912
913<para>
914The Geant4 GNUmake infrastructure allows to extend the link list of
915libraries with external (or user defined) packages which may be
916required for some user's applications to generate the final
917executable.
918</para>
919
920<!-- ******************* Section (Level#3) ****************** -->
921<sect3 id="sect.MkflEnvVar.LnkExtLib.AddExtlibNoG4">
922<title>
923Adding external libraries which do *not* use Geant4
924</title>
925
926<para>
927In the <literal>GNUmakefile</literal> of your application, before including
928<literal>binmake.gmk</literal>, specify the extra library in
929<literal>EXTRALIBS</literal> either using the <literal>-L...-l...</literal> 
930syntax or by specifying the full pathname, e.g.:
931
932<informalexample>
933<programlisting>
934  EXTRALIBS := -L&lt;your-path&gt;/lib -l&lt;myExtraLib&gt;
935</programlisting>
936</informalexample>
937or
938<informalexample>
939<programlisting>
940  EXTRALIBS := &lt;your-path&gt;/lib/lib&lt;myExtraLib&gt;.a
941</programlisting>
942</informalexample>
943</para>
944
945<para>
946You may also specify <literal>EXTRA_LINK_DEPENDENCIES</literal>, which is
947added to the dependency of the target executable, and you may also
948specify a rule for making it, e.g.:
949
950<informalexample>
951<programlisting>
952  EXTRA_LINK_DEPENDENCIES := &lt;your-path&gt;/lib/lib&lt;myExtraLib&gt;.a
953
954  &lt;your-path&gt;/lib/lib&lt;myExtraLib&gt;.a:
955        cd &lt;your-path&gt;/lib; $(MAKE)
956</programlisting>
957</informalexample>
958</para>
959
960<para>
961Note that you almost certainly need to augment <literal>CPPFLAGS</literal>
962for the header files of the external library, e.g.:
963
964<informalexample>
965<programlisting>
966  CPPFLAGS+=-I&lt;your-path&gt;/include
967</programlisting>
968</informalexample>
969
970See <xref linkend="programlist_MkflEnvVar_1" />.
971</para>
972
973<para>
974<example id="programlist_MkflEnvVar_1">
975<title>
976An example of a customised GNUmakefile for an application or
977example using an external module not bound to Geant4.
978</title>
979
980<programlisting>
981 # --------------------------------------------------------------------
982 # GNUmakefile for the application "sim" depending on module "Xplotter"
983 # --------------------------------------------------------------------
984
985 name := sim
986 G4TARGET := $(name)
987 G4EXLIB := true
988
989 CPPFLAGS  += -I$(HOME)/Xplotter/include
990 EXTRALIBS += -L$(HOME)/Xplotter/lib -lXplotter
991 EXTRA_LINK_DEPENDENCIES := $(HOME)/Xplotter/lib/libXplotter.a
992
993 .PHONY: all
994
995 all: lib bin
996
997 include $(G4INSTALL)/config/binmake.gmk
998
999 $(HOME)/Xplotter/lib/libXplotter.a:
1000         cd $(HOME)/Xplotter; $(MAKE)
1001</programlisting>
1002</example>
1003</para>
1004
1005</sect3>
1006
1007
1008<!-- ******************* Section (Level#3) ****************** -->
1009<sect3 id="sect.MkflEnvVar.LnkExtLib.AddExtlibWithG4">
1010<title>
1011Adding external libraries which use Geant4
1012</title>
1013
1014<para>
1015In addition to the above, specify, in <literal>EXTRALIBSSOURCEDIRS</literal>,
1016a list of directories containing source files in its <literal>src/</literal>
1017subdirectory. Thus, your <literal>GNUmakefile</literal> might contain:
1018
1019<informalexample>
1020<programlisting>
1021  EXTRALIBS += $(G4WORKDIR)/tmp/$(G4SYSTEM)/&lt;myApp&gt;/lib&lt;myApp&gt;.a \
1022               -L&lt;your-path&gt;/lib -l&lt;myExtraLib&gt;
1023  EXTRALIBSSOURCEDIRS += &lt;your-path&gt;/&lt;myApp&gt; &lt;your-path&gt;/&lt;MyExtraModule&gt;
1024  EXTRA_LINK_DEPENDENCIES := $(G4WORKDIR)/tmp/$(G4SYSTEM)/&lt;myApp&gt;/lib&lt;myApp&gt;.a
1025
1026  MYSOURCES := $(wildcard &lt;your-path&gt;/&lt;myApp&gt;/src/*cc)
1027  $(G4WORKDIR)/tmp/$(G4SYSTEM)/&lt;myApp&gt;/lib&lt;myApp&gt;.a: $(MYSOURCES)
1028        cd &lt;your-path&gt;/&lt;myApp&gt;; $(MAKE)
1029</programlisting>
1030</informalexample>
1031</para>
1032
1033<para>
1034See <xref linkend="programlist_MkflEnvVar_2" />.
1035</para>
1036
1037<para>
1038<example id="programlist_MkflEnvVar_2">
1039<title>
1040An example of a customised GNUmakefile for an
1041application or example using external modules bound to Geant4.
1042</title>
1043
1044<programlisting>
1045# -----------------------------------------------------------------
1046# GNUmakefile for the application "phys" depending on module "reco"
1047# -----------------------------------------------------------------
1048
1049name := phys
1050G4TARGET := $(name)
1051G4EXLIB := true
1052
1053EXTRALIBS += $(G4WORKDIR)/tmp/$(G4SYSTEM)/$(name)/libphys.a \
1054             -L$(HOME)/reco/lib -lreco
1055EXTRALIBSSOURCEDIRS += $(HOME)/phys $(HOME)/reco
1056EXTRA_LINK_DEPENDENCIES := $(G4WORKDIR)/tmp/$(G4SYSTEM)/$(name)/libphys.a
1057
1058.PHONY: all
1059all: lib bin
1060
1061include $(G4INSTALL)/config/binmake.gmk
1062
1063MYSOURCES := $(wildcard $(HOME)/phys/src/*cc)
1064$(G4WORKDIR)/tmp/$(G4SYSTEM)/$(name)/libphys.a: $(MYSOURCES)
1065        cd $(HOME)/phys; $(MAKE)
1066</programlisting>
1067</example>
1068</para>
1069
1070</sect3>
1071
1072</sect2>
1073</sect1>
Note: See TracBrowser for help on using the repository browser.