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.