1 | <!-- ******************************************************** --> |
---|
2 | <!-- --> |
---|
3 | <!-- [History] --> |
---|
4 | <!-- Converted to DocBook: Katsuya Amako, Aug-2006 --> |
---|
5 | <!-- --> |
---|
6 | <!-- ******************************************************** --> |
---|
7 | |
---|
8 | <para> |
---|
9 | |
---|
10 | Before installing Geant4, the required software listed in |
---|
11 | <xref linkend="sect.ReqSoft" /> |
---|
12 | (and <xref linkend="sect.VisSoft" /> in the case of graphics drivers) |
---|
13 | of this Installation Guide must already be installed on |
---|
14 | your system. |
---|
15 | </para> |
---|
16 | |
---|
17 | <para> |
---|
18 | In this section, a short tutorial on how to install the |
---|
19 | toolkit's kernel libraries is given. The installation of the Geant4 |
---|
20 | kernel libraries and the proper configuration of the environment |
---|
21 | can be achieved either manually (by setting the proper environment |
---|
22 | variables) or through the <literal>Configure</literal> shell script, |
---|
23 | which will allow the installation of just the necessary source code |
---|
24 | and libraries in a specified installation area. |
---|
25 | </para> |
---|
26 | |
---|
27 | <para> |
---|
28 | <emphasis>Step-by-Step</emphasis> guides for the installation are |
---|
29 | also available. See |
---|
30 | <ulink url="http://cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/apas06.html"> |
---|
31 | Appendix - Step-by-Step Installation Guides</ulink> |
---|
32 | of <emphasis>Geant4 User's Guide - For Application Developers</emphasis>. |
---|
33 | </para> |
---|
34 | |
---|
35 | <!-- ******************* Section (Level#1) ****************** --> |
---|
36 | <sect1 id="sect.UsingConfig"> |
---|
37 | <title> |
---|
38 | Using the <literal>Configure</literal> Script for installation |
---|
39 | </title> |
---|
40 | |
---|
41 | <para> |
---|
42 | A shell script is provided for building the libraries and to allow |
---|
43 | easy installation in a specified area. The <literal>Configure</literal> |
---|
44 | shell script is placed in the top directory tree of the |
---|
45 | distribution (<literal>geant4/Configure</literal>) and allows the user or |
---|
46 | system administrator to install the Geant4 toolkit in a |
---|
47 | semi-automatic way. Some knowledge of the system is required for |
---|
48 | the installation, such as: |
---|
49 | |
---|
50 | <itemizedlist spacing="compact"> |
---|
51 | <listitem><para> |
---|
52 | the compiler to be used |
---|
53 | </para></listitem> |
---|
54 | <listitem><para> |
---|
55 | the path where the Geant4 toolkit is to be installed |
---|
56 | (<literal>$G4INSTALL</literal>) |
---|
57 | </para></listitem> |
---|
58 | <listitem><para> |
---|
59 | definition of installation directory paths (optional) |
---|
60 | </para></listitem> |
---|
61 | <listitem><para> |
---|
62 | kind of graphics/analysis system(s) installed in the system, |
---|
63 | and paths to the installation of each graphics/analysis |
---|
64 | package |
---|
65 | </para></listitem> |
---|
66 | <listitem><para> |
---|
67 | the kind of library to be generated: static/shared, |
---|
68 | compound/granular. |
---|
69 | </para></listitem> |
---|
70 | </itemizedlist> |
---|
71 | </para> |
---|
72 | |
---|
73 | <para> |
---|
74 | To run the installer script for building the libraries of the Geant4 toolkit, |
---|
75 | one must type the following from the top directory |
---|
76 | <literal>geant4</literal>: |
---|
77 | |
---|
78 | <informalexample> |
---|
79 | <programlisting> |
---|
80 | > ./Configure -build |
---|
81 | </programlisting> |
---|
82 | </informalexample> |
---|
83 | |
---|
84 | and follow the on-screen instructions. No system administrator |
---|
85 | privileges are required at this stage. The script will ask for the |
---|
86 | path in the system where the Geant4 libraries should be installed |
---|
87 | later on. The script provides default settings for most of the |
---|
88 | environment variables to be set. By pressing -RETURN-, the default |
---|
89 | values will be selected; otherwise the proper selection (or path, |
---|
90 | in case a path is requested) must be typed in. |
---|
91 | </para> |
---|
92 | |
---|
93 | <para> |
---|
94 | In case the installation procedure fails for some reason, or you |
---|
95 | realise the selected options were not correct at the time the |
---|
96 | installation started, you can repeat the whole process by manually |
---|
97 | removing the current installation with: |
---|
98 | |
---|
99 | <informalexample> |
---|
100 | <programlisting> |
---|
101 | > cd geant4/source |
---|
102 | > make clean |
---|
103 | </programlisting> |
---|
104 | </informalexample> |
---|
105 | where the <literal>$G4SYSTEM</literal> environment variable (specifying |
---|
106 | the kind of architecture and compiler used) is manually set in your |
---|
107 | environment (according to the flavors listed in |
---|
108 | <xref linkend="sect.Support" />). |
---|
109 | </para> |
---|
110 | |
---|
111 | <para> |
---|
112 | In case new modules must be added to an existing build (for |
---|
113 | example a module for visualization), this can be done manually by |
---|
114 | re-running <literal>Configure</literal> and providing the new |
---|
115 | settings. |
---|
116 | </para> |
---|
117 | |
---|
118 | <para> |
---|
119 | Once the process of building the libraries has been completed |
---|
120 | successfully, the Geant4 toolkit can be installed in the specified |
---|
121 | (already existing) installation area by typing: |
---|
122 | |
---|
123 | <informalexample> |
---|
124 | <programlisting> |
---|
125 | > ./Configure -install |
---|
126 | </programlisting> |
---|
127 | </informalexample> |
---|
128 | </para> |
---|
129 | |
---|
130 | <para> |
---|
131 | Libraries and necessary source code will be installed in |
---|
132 | <literal>lib/geant4</literal>, <literal>include/geant4</literal> (if selected to |
---|
133 | install all headers in a single directory), <literal>src/geant4</literal>, |
---|
134 | respectively. System administrator privileges may be required for the |
---|
135 | installation stage, depending upon where in the system the installation |
---|
136 | should happen. |
---|
137 | </para> |
---|
138 | |
---|
139 | <para> |
---|
140 | <literal>$G4INSTALL</literal> will be set to |
---|
141 | <literal>[INSTALLATION_AREA]/src/geant4</literal>. |
---|
142 | </para> |
---|
143 | |
---|
144 | </sect1> |
---|
145 | |
---|
146 | <!-- ******************* Section (Level#1) ****************** --> |
---|
147 | <sect1 id="sect.ConfigEnv"> |
---|
148 | <title> |
---|
149 | Configuring the Environment to Use Geant4 |
---|
150 | </title> |
---|
151 | |
---|
152 | <para> |
---|
153 | Once libraries have been installed, the user's environment must be |
---|
154 | correctly set up for the usage of the Geant4 toolkit. The |
---|
155 | <literal>Configure</literal> script provides a way to check the existing |
---|
156 | installation and provide the correct configuration for the user's |
---|
157 | environment. Configuration scripts <literal>env[.sh.csh]</literal> can be |
---|
158 | generated, and should be sourced by the final users in order to |
---|
159 | configure their environment according to the performed |
---|
160 | installation. |
---|
161 | </para> |
---|
162 | |
---|
163 | <para> |
---|
164 | To generate the configuration scripts, the user should run |
---|
165 | <literal>Configure</literal> placed in the installation area, as follows: |
---|
166 | |
---|
167 | <informalexample> |
---|
168 | <programlisting> |
---|
169 | > $G4INSTALL/Configure |
---|
170 | </programlisting> |
---|
171 | </informalexample> |
---|
172 | </para> |
---|
173 | |
---|
174 | <para> |
---|
175 | This will generate the shell script <literal>env.csh</literal> |
---|
176 | (<literal>env.sh</literal> for <literal>bash</literal> shell) to be sourced or |
---|
177 | integrated into the shell login script (<literal>.tcshrc</literal> or |
---|
178 | <literal>.bashrc</literal>). The shell script will be generated in the |
---|
179 | user's current directory (<literal>$PWD</literal>). The user can |
---|
180 | customize it to specify for example her/his proper working |
---|
181 | directory through the variable <literal>$G4WORKDIR</literal>. Once the |
---|
182 | generated script is sourced, the user will be ready to start |
---|
183 | building a Geant4 application. |
---|
184 | </para> |
---|
185 | |
---|
186 | <para> |
---|
187 | Refer to section the section |
---|
188 | <emphasis> |
---|
189 | Getting Started with Geant4 - How to Make an Executable Program |
---|
190 | </emphasis> |
---|
191 | of the |
---|
192 | <ulink url="http://cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/index.html"> |
---|
193 | Geant4 User's Guide for Application Developers |
---|
194 | </ulink> |
---|
195 | for information on how to build an executable in Geant4. |
---|
196 | </para> |
---|
197 | |
---|
198 | </sect1> |
---|
199 | |
---|
200 | |
---|
201 | <!-- ******************* Section (Level#1) ****************** --> |
---|
202 | <sect1 id="sect.InstManually"> |
---|
203 | <title> |
---|
204 | Installing Geant4 Manually |
---|
205 | </title> |
---|
206 | |
---|
207 | <para> |
---|
208 | Before proceeding with the installation, some key environment |
---|
209 | variables must be defined in your user environment in order to |
---|
210 | specify where all software components are to be placed and to set |
---|
211 | some compilation options. A complete reference to all environment |
---|
212 | variables in Geant4 is available in section |
---|
213 | |
---|
214 | <emphasis> |
---|
215 | Appendix - Makefiles and Environment Variables |
---|
216 | </emphasis> |
---|
217 | of the |
---|
218 | <ulink url="http://cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/index.html"> |
---|
219 | Geant4 User's Guide for Application Developers |
---|
220 | </ulink>. |
---|
221 | </para> |
---|
222 | |
---|
223 | <!-- ******************* Section (Level#2) ****************** --> |
---|
224 | <sect2 id="sect.InstManually.ReqEnvVar"> |
---|
225 | <title> |
---|
226 | Required Environment Variables |
---|
227 | </title> |
---|
228 | |
---|
229 | <variablelist><title></title> |
---|
230 | <varlistentry> |
---|
231 | <term> |
---|
232 | <literal>G4SYSTEM:</literal> |
---|
233 | </term> |
---|
234 | <listitem><para> |
---|
235 | set to one of the flavors listed in section 1.1 to specify the |
---|
236 | kind of architecture and compiler used |
---|
237 | </para></listitem> |
---|
238 | </varlistentry> |
---|
239 | <varlistentry> |
---|
240 | <term> |
---|
241 | <literal>G4INSTALL:</literal> |
---|
242 | </term> |
---|
243 | <listitem><para> |
---|
244 | path where the Geant4 toolkit tree is installed (ex. |
---|
245 | <literal>$HOME/geant4</literal>) |
---|
246 | </para></listitem> |
---|
247 | </varlistentry> |
---|
248 | <varlistentry> |
---|
249 | <term> |
---|
250 | <literal>CLHEP_BASE_DIR:</literal> |
---|
251 | </term> |
---|
252 | <listitem><para> |
---|
253 | path to the CLHEP installation |
---|
254 | </para></listitem> |
---|
255 | </varlistentry> |
---|
256 | </variablelist> |
---|
257 | |
---|
258 | </sect2> |
---|
259 | |
---|
260 | <!-- ******************* Section (Level#2) ****************** --> |
---|
261 | <sect2 id="sect.InstManually.OptEnvVar"> |
---|
262 | <title> |
---|
263 | Optional Environment Variables |
---|
264 | </title> |
---|
265 | |
---|
266 | <variablelist><title></title> |
---|
267 | <varlistentry> |
---|
268 | <term> |
---|
269 | <literal>G4WORKDIR:</literal> |
---|
270 | </term> |
---|
271 | <listitem><para> |
---|
272 | path of the user's working directory (default in |
---|
273 | <literal>$G4INSTALL</literal>) |
---|
274 | </para></listitem> |
---|
275 | </varlistentry> |
---|
276 | <varlistentry> |
---|
277 | <term> |
---|
278 | <literal>G4LIB:</literal> |
---|
279 | </term> |
---|
280 | <listitem><para> |
---|
281 | path where the kernel libraries should be installed (default in |
---|
282 | <literal>$G4INSTALL/lib</literal>) |
---|
283 | </para></listitem> |
---|
284 | </varlistentry> |
---|
285 | <varlistentry> |
---|
286 | <term> |
---|
287 | <literal>G4TMP:</literal> |
---|
288 | </term> |
---|
289 | <listitem><para> |
---|
290 | path where temporary files (object files, dependency files) are |
---|
291 | placed (default in <literal>$G4WORKDIR/tmp)</literal> |
---|
292 | </para></listitem> |
---|
293 | </varlistentry> |
---|
294 | <varlistentry> |
---|
295 | <term> |
---|
296 | <literal>G4BIN:</literal> |
---|
297 | </term> |
---|
298 | <listitem><para> |
---|
299 | path where final executable files are placed (default in |
---|
300 | <literal>$G4WORKDIR/bin)</literal>. |
---|
301 | </para></listitem> |
---|
302 | </varlistentry> |
---|
303 | <varlistentry> |
---|
304 | <term> |
---|
305 | <literal>G4INCLUDE:</literal> |
---|
306 | </term> |
---|
307 | <listitem><para> |
---|
308 | path where source header files may be mirrored at installation |
---|
309 | by issuing <literal>make includes</literal> (default in |
---|
310 | <literal>$G4INSTALL/include</literal>) |
---|
311 | </para></listitem> |
---|
312 | </varlistentry> |
---|
313 | <varlistentry> |
---|
314 | <term> |
---|
315 | <literal>G4DEBUG:</literal> |
---|
316 | </term> |
---|
317 | <listitem><para> |
---|
318 | flag specifying that libraries be built with debug symbols |
---|
319 | (requires a lot of disk space). The default is optimised-mode |
---|
320 | </para></listitem> |
---|
321 | </varlistentry> |
---|
322 | <varlistentry> |
---|
323 | <term> |
---|
324 | <literal>G4LIB_BUILD_SHARED:</literal> |
---|
325 | </term> |
---|
326 | <listitem><para> |
---|
327 | flag specifying that kernel libraries be built as shared |
---|
328 | libraries (libraries will then be used by default). If not set, |
---|
329 | static archive libraries are built by default |
---|
330 | </para></listitem> |
---|
331 | </varlistentry> |
---|
332 | <varlistentry> |
---|
333 | <term> |
---|
334 | <literal>G4LIB_BUILD_STATIC:</literal> |
---|
335 | </term> |
---|
336 | <listitem><para> |
---|
337 | flag specifying that kernel libraries be built as static |
---|
338 | archive libraries. Note that you may specify this flag in addition |
---|
339 | to <literal>G4LIB_BUILD_SHARED</literal> to build shared and static |
---|
340 | libraries simultaneously. |
---|
341 | </para></listitem> |
---|
342 | </varlistentry> |
---|
343 | <varlistentry> |
---|
344 | <term> |
---|
345 | <literal>G4LIB_BUILD_G3TOG4:</literal> |
---|
346 | </term> |
---|
347 | <listitem><para> |
---|
348 | flag specifying that the library for the g3tog4 module be |
---|
349 | built. By default the library will not be built. |
---|
350 | </para></listitem> |
---|
351 | </varlistentry> |
---|
352 | <varlistentry> |
---|
353 | <term> |
---|
354 | <literal>G4LIB_BUILD_ZLIB:</literal> |
---|
355 | </term> |
---|
356 | <listitem><para> |
---|
357 | flag specifying that an additional library for file compression |
---|
358 | should be built (not required on Linux/Unix systems). By default |
---|
359 | the library will not be built. |
---|
360 | </para></listitem> |
---|
361 | </varlistentry> |
---|
362 | <varlistentry> |
---|
363 | <term> |
---|
364 | <literal>G4_NO_VERBOSE:</literal> |
---|
365 | </term> |
---|
366 | <listitem><para> |
---|
367 | defining this flag prevents the compilation of verbosity code |
---|
368 | (for better performance). The default is with verbosity on. |
---|
369 | </para></listitem> |
---|
370 | </varlistentry> |
---|
371 | </variablelist> |
---|
372 | |
---|
373 | <para> |
---|
374 | The list of all additional flags (also requiring third-party packages |
---|
375 | installed) can be found in |
---|
376 | <ulink url="http://cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/apas05.html#sect.MkflEnvVar.EnvVar">Section 5.2</ulink> |
---|
377 | of the |
---|
378 | <ulink url="http://cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/index.html"> |
---|
379 | Geant4 User's Guide for Application Developers |
---|
380 | </ulink>. |
---|
381 | </para> |
---|
382 | |
---|
383 | <para> |
---|
384 | The Geant4 installation requires native STL (the Standard Template |
---|
385 | Library) as the base foundation class library. This also implies |
---|
386 | strict ISO-ANSI language compliance. In addition to the above, you |
---|
387 | might want to set the proper environment for visualization, such |
---|
388 | as: |
---|
389 | |
---|
390 | <itemizedlist spacing="compact"> |
---|
391 | <listitem><para> |
---|
392 | the kind of graphics driver(s) installed in the system |
---|
393 | </para></listitem> |
---|
394 | <listitem><para> |
---|
395 | the path to the installation of each graphics driver |
---|
396 | </para></listitem> |
---|
397 | </itemizedlist> |
---|
398 | |
---|
399 | in case you want to build the Geant4 kernel libraries with the |
---|
400 | graphics drivers built-in. See |
---|
401 | |
---|
402 | <emphasis> |
---|
403 | Visualization - The Visualization Drivers |
---|
404 | </emphasis> |
---|
405 | of the |
---|
406 | <ulink url="http://cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/index.html"> |
---|
407 | Geant4 User's Guide for Application Developers |
---|
408 | </ulink>. |
---|
409 | </para> |
---|
410 | |
---|
411 | <para> |
---|
412 | At this point, you may choose one of two ways to compile and |
---|
413 | install the kernel libraries, depending on your needs and system |
---|
414 | resources. From <literal>$G4INSTALL/source</literal>: |
---|
415 | |
---|
416 | <orderedlist spacing="compact"> |
---|
417 | <listitem><para> |
---|
418 | <literal>make</literal> |
---|
419 | <para> |
---|
420 | This will make one library for each "leaf" category (maximum |
---|
421 | library granularity) and automatically produce a map of library use |
---|
422 | and dependencies.</para> |
---|
423 | </para></listitem> |
---|
424 | <listitem><para> |
---|
425 | <literal>make global</literal> |
---|
426 | <para> |
---|
427 | This will make global libraries, one for each major category. |
---|
428 | </para> |
---|
429 | </para></listitem> |
---|
430 | </orderedlist> |
---|
431 | </para> |
---|
432 | |
---|
433 | <para> |
---|
434 | The main advantage of the first approach is the speed of building |
---|
435 | the libraries and of the application, which in some cases can be |
---|
436 | improved by a factor of two or three compared to the "global |
---|
437 | library" approach. |
---|
438 | </para> |
---|
439 | |
---|
440 | <para> |
---|
441 | Using the "granular library" approach a fairly large number |
---|
442 | (roughly 90) of "leaf" libraries is produced. However, the |
---|
443 | dependencies and linking list are evaluated and generated |
---|
444 | automatically on the fly. The top-level <literal>GNUmakefile</literal> in |
---|
445 | <literal>$G4INSTALL/source</literal> parses the dependency files of |
---|
446 | Geant4 and produces a file <literal>libname.map</literal> in |
---|
447 | <literal>$G4LIB</literal>. <literal>libname.map</literal> is produced by the |
---|
448 | tool <literal>liblist</literal>, whose source code is in |
---|
449 | <literal>$G4INSTALL/config</literal>. |
---|
450 | </para> |
---|
451 | |
---|
452 | <para> |
---|
453 | When building a binary application the script |
---|
454 | <literal>binmake.gmk</literal> in <literal>$G4INSTALL/config</literal> will |
---|
455 | parse the user's dependency files and use <literal>libname.map</literal> |
---|
456 | to determine through <literal>liblist</literal> the required libraries to |
---|
457 | add to the linking list. Only the required libraries will be loaded |
---|
458 | in the link command. |
---|
459 | </para> |
---|
460 | |
---|
461 | <para> |
---|
462 | The command <literal>make libmap</literal> issued from |
---|
463 | <literal>$G4INSTALL/source</literal>, allows manual rebuilding of the |
---|
464 | dependency map. The command is issued by default in the normal |
---|
465 | build process for granular libraries. |
---|
466 | </para> |
---|
467 | |
---|
468 | <para> |
---|
469 | It is possible to install both "granular" and "compound" libraries, |
---|
470 | by typing "make" and "make global" in sequence. In this case, to |
---|
471 | choose usage of granular libraries at link time one should set the |
---|
472 | flag G4LIB_USE_GRANULAR in the environment; otherwise compound |
---|
473 | libraries will be adopted by default. |
---|
474 | </para> |
---|
475 | |
---|
476 | </sect2> |
---|
477 | </sect1> |
---|
478 | |
---|
479 | <!-- ******************* Section (Level#1) ****************** --> |
---|
480 | <sect1 id="sect.IntegGeneFrame"> |
---|
481 | <title> |
---|
482 | Integrating Geant4 into a Generic Framework |
---|
483 | </title> |
---|
484 | |
---|
485 | <para> |
---|
486 | As part of the Geant4 kernel libraries installation, it is also |
---|
487 | possible to put the entire set of header files in a single place, |
---|
488 | which is determined by the environment variable |
---|
489 | <literal>G4INCLUDE</literal> specifying the directory path. Therefore, |
---|
490 | it's rather straightforward to integrate Geant4 into a generic |
---|
491 | external framework, by simply knowing the path where header files |
---|
492 | are located in the system (<literal>G4INCLUDE</literal>) and where |
---|
493 | installed libraries are placed (<literal>G4LIB</literal>). |
---|
494 | </para> |
---|
495 | |
---|
496 | <para> |
---|
497 | In <ulink url="http://cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/apas05.html#sect.MkflEnvVar.EnvVar">Section 5.2</ulink>. |
---|
498 | (<emphasis>Appendix - Makefiles and Environment Variables</emphasis>) |
---|
499 | of the |
---|
500 | <ulink url="http://cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/index.html"> |
---|
501 | Geant4 User's Guide for Application Developers |
---|
502 | </ulink>, |
---|
503 | you can find a list of all the environment variables. In |
---|
504 | <ulink url="http://cern.ch/geant4/UserDocumentation/UsersGuides/ForApplicationDeveloper/html/apas05.html#sect.MkflEnvVar.LnkExtLib">Section 5.3</ulink> |
---|
505 | it is also explained how to integrate external libraries which may or |
---|
506 | may not use the Geant4 kernel libraries, using the <literal>GNUmake</literal> |
---|
507 | build system of Geant4. |
---|
508 | </para> |
---|
509 | |
---|
510 | </sect1> |
---|