Annotation of /gpamela/README


     Quick and dirty instruction list to build GPAMELA executable
     ------------------------------------------------------------

                   (F. Cafagna, Bari 11 July 2002)


1. INTRODUCTION

  In this directory you will find all the sources and auxiliary files needed 
  to build GPAMELA.

  GPAMELA sources are distributed in several subdirectories along with 
  the GARFIELD car files needed to build the GARFIELD library. 

  To build GPAMELA you need the Makefile in the top directory along with 
  the file: makefile_linux, stored in the garfield/src directory.

2. BUILD GPAMELA EXECUTABLE FOR INPATIENTS

Here is the list of action for the inpatients:

- Create the directory you want to store executables and run the program, 
  in this example I wil create my_gpamela in my home directory:

  > mkdir  $HOME/my_gpamela

- Define the environment variable GPAMELA_BIN pointing the the created directory:

  > GPAMELA_BIN = $HOME/my_gpamela; export GPAMELA_BIN (for [ba]sh )
  > setenv GPAMELA_BIN $HOME/my_gpamela (for [t]csh)

- Make it: 

  > make distclean; make gpamelax11.exe; make gpamela.exe
  > make gpamelax11_deb.exe; make gpamela_deb.exe
  
- Install it:

  > make install

3. DIRECTORY TREE

Here follows the gpamela directory tree:
.
|-- Makefile
|-- aux
|   |-- Auxiliary files needed by GPAMELA, i.e. field map, data cards, 
|       garfield definitions etc. etc. 
|-- cmz
|   `-- Versions
|       |-- History of the previous CMZ releases
|-- garfield
|   `-- src
|       |-- GARFIELD sources and makefile
|-- gcdes
|   |-- GEANT 3.21 include files
|-- gpamela
|   |-- general purpose routine, for example GUSTEP, GPDAT etc. etc. 
|-- gpcal
|   |-- CALorimeter related routines 
|-- gpcalor
|   |-- GCALOR interface between GEANT and MICAP
|-- gpcalordes
|   |-- GCALOR include files
|-- gpcas
|   |-- CAS related soubroutine
|-- gpcat
|   |-- CAT related soubroutine
|-- gpcdes
|   |-- GPAMELA include files
|-- gpfield
|   |-- magnetic field related subroutines
|-- gpgar
|   |-- GPAMELA- GARFIELD interface related subroutines
|-- gphys
|   |-- obsolete routines to integrate dE/dx fluctuations 
|        in the GEANT physics bank
|-- gpmain
|   `-- GPAMELA main routine
|-- gpnd
+   |-- neutron detector related routines
|-- gpobsolete
|   |-- obsolete code for tracker digitization
|-- gpspe
|   |-- SPEctrometer related subroutine
|-- gptof
|   |-- TOF related subroutine
|-- gptrd
|   |-- TOF related subroutine 
|-- gpxint
|   |-- GPAMELA main routine for the interactive version
|-- history
|   `-- history file (GPAMELA logbook)
`-- inform
    `-- list and usage of GPAMELA data cards

Please note that no lib and bin directories are presents in the distribution. 
They will be created by make. 

Please note that all the source files have the .F extensions, they must be preprocessed. 

4. BUILD GPAMELA EXECUTABLE, LONG VERSION

You can create GPAMELA executables using gmake. For sake of simplicity I am 
using just one Makefile located in the top directory: gpamela. 

The Makefile will create the executables locally in the bin directory
of the top directory gpamela and will install them into the any user
created directory along with the auxiliaries files need. You can pass
the used directory via the GPAMELA_BIN environment variable.

Please note that the Makefile does use GNUmake: gmake,
extension. Usually in the RedHat Linux distributions make points to
gmake so the usage is equivalent.

The Makefile contains the following targets:

-gpamelax11.exe     : builds the interactive version of GPAMELA
-gpamela.exe        : builds the batch version of GPAMELA
-gpamelax11_deb.exe : builds the interactive version of GPAMELA with debug flags
-gpamela_deb.exe    : builds the batch version of GPAMELA with debug flags
-depend             : creates dependency files for each source file
-install            : install GPAMELA executables and auxiliary files in GPAMELA_BIN
-${GPLIBDIR}/libgarfield-7.a: builds the GARFIELD library in garfield/src directory
-createdir          : creates the ./bin directory in the top directory
-distclean          : deletes all the objects, dependency files, executables, 
                      GARFIELD library, bin and lib directories
-clean              : deletes all the objects and dependency files

The Makefile contains the following implicit rule:

%.d: %.F  : builds dependency files from the .F files

Please note that no rule has been included to build dependencies for .f files. 
To avoid confusion all the GPAMELA fortran sources must have the .F extension. 

The Makefiles does use the g77 capability of creating dependencies suitable for
usage in makefile. Once the dependency files have been created Makefiles does include
them and use them as targets to build the objects from the sources. 
Because I am using a single Makefile in the top directory the rule does create the 
dependency files in the subdirectories. 

Please note tha gmake scans the Makefile before executing it. If no
files are available for the include directive gmake will try to build
them. For this reason you will get the "Creating dependency files"
message also when you try to delete them .......

Please note that all the object files are deleted after executable
creation. Because the GPAMELA code relies on the preprocessor
directives codes must be preprocessed for each case, i.e. interactive
or not interactive version. Deleting them in each executable target
will force the object creation next time you build any target.  To be
sure you are using the right objects you should issue a "make clean"
command before any executable creation.

Please note that the dependency files are note recreated. This means
that they should not depend on preprocessor directives, i.e. #if
#define etc. etc. 

GPAMELA depends on GARFIELD libraries. In case libgarfield-7.a is not
present in the lib subdirectory it will be created from scratch. This
is a long procedure that may take several minutes.

Here is the list of action to build GPAMELA executables:

- Create the directory you want to store executables and run the program, 
  in this example I wil create my_gpamela in my home directory:

  > mkdir  $HOME/my_gpamela

- Define the environment variable GPAMELA_BIN pointing the the created directory:

  > GPAMELA_BIN = $HOME/my_gpamela; export GPAMELA_BIN (for [ba]sh )
  > setenv GPAMELA_BIN $HOME/my_gpamela (for [t]csh)

- Delete all the objects, dependency files and GARFIELD library (you never know): 
  > make distclean 

- Create interactive executable (it will create the libgarfield-7.a also):
  > make gpamelax11.exe; 

- Create batch executable: 
  > make gpamela.exe

- Create debug versions
  > make gpamelax11_deb.exe; make gpamela_deb.exe
  
- Install all executables, along with GPAMELA.FFR, gpfield.rz,
  TRD_ATT.DAT, PROVA.GAR, in GPAMELA_BIN directory:
  > make install

5. OUTPUT MESSAGES

To maintain backward compatibility with the previous g77 version, I am
still using the debug-kludge flag to access fortran COMMONs in
debug. This is obsolete in the new release: 2.96. For this reason if
you are running a RedHat 7.x you will receive the message:

f771:warning: -fdebug-kludge disabled, use normal debugging flags

During gpamelax11(_deb).exe building you will get the message:

/cern/pro/lib/libpawlib.a(bugrep.o): In function `br_create_template':
bugrep.o(.text+0x113): the use of `tmpnam' is dangerous, better use `mkstemp'

It is a warning related to the pawlib in the cern release that is still not RH7.x certified. 
1	cafagna	3.1
2			Quick and dirty instruction list to build GPAMELA executable
3			------------------------------------------------------------
4
5			(F. Cafagna, Bari 11 July 2002)
6
7
8			1. INTRODUCTION
9
10			In this directory you will find all the sources and auxiliary files needed
11			to build GPAMELA.
12
13			GPAMELA sources are distributed in several subdirectories along with
14			the GARFIELD car files needed to build the GARFIELD library.
15
16			To build GPAMELA you need the Makefile in the top directory along with
17			the file: makefile_linux, stored in the garfield/src directory.
18
19			2. BUILD GPAMELA EXECUTABLE FOR INPATIENTS
20
21			Here is the list of action for the inpatients:
22
23			- Create the directory you want to store executables and run the program,
24			in this example I wil create my_gpamela in my home directory:
25
26			> mkdir $HOME/my_gpamela
27
28			- Define the environment variable GPAMELA_BIN pointing the the created directory:
29
30			> GPAMELA_BIN = $HOME/my_gpamela; export GPAMELA_BIN (for [ba]sh )
31			> setenv GPAMELA_BIN $HOME/my_gpamela (for [t]csh)
32
33			- Make it:
34
35			> make distclean; make gpamelax11.exe; make gpamela.exe
36			> make gpamelax11_deb.exe; make gpamela_deb.exe
37
38			- Install it:
39
40			> make install
41
42			3. DIRECTORY TREE
43
44			Here follows the gpamela directory tree:
45			.
46			\|-- Makefile
47			\|-- aux
48			\| \|-- Auxiliary files needed by GPAMELA, i.e. field map, data cards,
49			\| garfield definitions etc. etc.
50			\|-- cmz
51			\| `-- Versions
52			\| \|-- History of the previous CMZ releases
53			\|-- garfield
54			\| `-- src
55			\| \|-- GARFIELD sources and makefile
56			\|-- gcdes
57			\| \|-- GEANT 3.21 include files
58			\|-- gpamela
59			\| \|-- general purpose routine, for example GUSTEP, GPDAT etc. etc.
60			\|-- gpcal
61			\| \|-- CALorimeter related routines
62	cafagna	3.2	\|-- gpcalor
63			\| \|-- GCALOR interface between GEANT and MICAP
64			\|-- gpcalordes
65			\| \|-- GCALOR include files
66	cafagna	3.1	\|-- gpcas
67			\| \|-- CAS related soubroutine
68			\|-- gpcat
69			\| \|-- CAT related soubroutine
70			\|-- gpcdes
71			\| \|-- GPAMELA include files
72			\|-- gpfield
73			\| \|-- magnetic field related subroutines
74			\|-- gpgar
75			\| \|-- GPAMELA- GARFIELD interface related subroutines
76			\|-- gphys
77			\| \|-- obsolete routines to integrate dE/dx fluctuations
78			\| in the GEANT physics bank
79			\|-- gpmain
80			\| `-- GPAMELA main routine
81	cafagna	3.2	\|-- gpnd
82			+ \|-- neutron detector related routines
83	cafagna	3.1	\|-- gpobsolete
84			\| \|-- obsolete code for tracker digitization
85			\|-- gpspe
86			\| \|-- SPEctrometer related subroutine
87			\|-- gptof
88			\| \|-- TOF related subroutine
89			\|-- gptrd
90			\| \|-- TOF related subroutine
91			\|-- gpxint
92			\| \|-- GPAMELA main routine for the interactive version
93			\|-- history
94			\| `-- history file (GPAMELA logbook)
95			`-- inform
96			`-- list and usage of GPAMELA data cards
97
98			Please note that no lib and bin directories are presents in the distribution.
99			They will be created by make.
100
101			Please note that all the source files have the .F extensions, they must be preprocessed.
102
103			4. BUILD GPAMELA EXECUTABLE, LONG VERSION
104
105			You can create GPAMELA executables using gmake. For sake of simplicity I am
106			using just one Makefile located in the top directory: gpamela.
107
108			The Makefile will create the executables locally in the bin directory
109			of the top directory gpamela and will install them into the any user
110			created directory along with the auxiliaries files need. You can pass
111			the used directory via the GPAMELA_BIN environment variable.
112
113			Please note that the Makefile does use GNUmake: gmake,
114			extension. Usually in the RedHat Linux distributions make points to
115			gmake so the usage is equivalent.
116
117			The Makefile contains the following targets:
118
119			-gpamelax11.exe : builds the interactive version of GPAMELA
120			-gpamela.exe : builds the batch version of GPAMELA
121			-gpamelax11_deb.exe : builds the interactive version of GPAMELA with debug flags
122			-gpamela_deb.exe : builds the batch version of GPAMELA with debug flags
123			-depend : creates dependency files for each source file
124			-install : install GPAMELA executables and auxiliary files in GPAMELA_BIN
125			-${GPLIBDIR}/libgarfield-7.a: builds the GARFIELD library in garfield/src directory
126			-createdir : creates the ./bin directory in the top directory
127			-distclean : deletes all the objects, dependency files, executables,
128			GARFIELD library, bin and lib directories
129			-clean : deletes all the objects and dependency files
130
131			The Makefile contains the following implicit rule:
132
133			%.d: %.F : builds dependency files from the .F files
134
135			Please note that no rule has been included to build dependencies for .f files.
136			To avoid confusion all the GPAMELA fortran sources must have the .F extension.
137
138			The Makefiles does use the g77 capability of creating dependencies suitable for
139			usage in makefile. Once the dependency files have been created Makefiles does include
140			them and use them as targets to build the objects from the sources.
141			Because I am using a single Makefile in the top directory the rule does create the
142			dependency files in the subdirectories.
143
144			Please note tha gmake scans the Makefile before executing it. If no
145			files are available for the include directive gmake will try to build
146			them. For this reason you will get the "Creating dependency files"
147			message also when you try to delete them .......
148
149			Please note that all the object files are deleted after executable
150			creation. Because the GPAMELA code relies on the preprocessor
151			directives codes must be preprocessed for each case, i.e. interactive
152			or not interactive version. Deleting them in each executable target
153			will force the object creation next time you build any target. To be
154			sure you are using the right objects you should issue a "make clean"
155			command before any executable creation.
156
157			Please note that the dependency files are note recreated. This means
158			that they should not depend on preprocessor directives, i.e. #if
159			#define etc. etc.
160
161			GPAMELA depends on GARFIELD libraries. In case libgarfield-7.a is not
162			present in the lib subdirectory it will be created from scratch. This
163			is a long procedure that may take several minutes.
164
165			Here is the list of action to build GPAMELA executables:
166
167			- Create the directory you want to store executables and run the program,
168			in this example I wil create my_gpamela in my home directory:
169
170			> mkdir $HOME/my_gpamela
171
172			- Define the environment variable GPAMELA_BIN pointing the the created directory:
173
174			> GPAMELA_BIN = $HOME/my_gpamela; export GPAMELA_BIN (for [ba]sh )
175			> setenv GPAMELA_BIN $HOME/my_gpamela (for [t]csh)
176
177			- Delete all the objects, dependency files and GARFIELD library (you never know):
178			> make distclean
179
180			- Create interactive executable (it will create the libgarfield-7.a also):
181			> make gpamelax11.exe;
182
183			- Create batch executable:
184			> make gpamela.exe
185
186			- Create debug versions
187			> make gpamelax11_deb.exe; make gpamela_deb.exe
188
189			- Install all executables, along with GPAMELA.FFR, gpfield.rz,
190			TRD_ATT.DAT, PROVA.GAR, in GPAMELA_BIN directory:
191			> make install
192
193			5. OUTPUT MESSAGES
194
195			To maintain backward compatibility with the previous g77 version, I am
196			still using the debug-kludge flag to access fortran COMMONs in
197			debug. This is obsolete in the new release: 2.96. For this reason if
198			you are running a RedHat 7.x you will receive the message:
199
200			f771:warning: -fdebug-kludge disabled, use normal debugging flags
201
202			During gpamelax11(_deb).exe building you will get the message:
203
204			/cern/pro/lib/libpawlib.a(bugrep.o): In function `br_create_template':
205			bugrep.o(.text+0x113): the use of `tmpnam' is dangerous, better use `mkstemp'
206
207			It is a warning related to the pawlib in the cern release that is still not RH7.x certified.