STAR Computing | Tutorials main page |
Software Packages - Directory Structure and Explanation | |
Offline computing tutorial | Maintained by Turner and Wenaus |
Domains are the top level of directory structure for packages under the old STAF $STAR/pams organization and refer usually to a particular function or subsystem; e.g. there are domains for TPC, SVT, EMC, GSTAR. In the ROOT-based code we have flattened out the structure with all ROOT-based packages at one level, under StRoot/ at the top level.
Packages generally live under StRoot (or under domains for old pams/ software) and contain the software for a particular function.
Makers are the most common type of package people write; a Maker is a plug-in component to the ROOT based framework (dynamically loaded via a shared library).
Modules are software components in the old STAF context, defined by their IDL interface; they are analogous to Makers in the ROOT based framework. They are contained in a package (may be more than 1) and may perform different tasks leading to the full functionality of the package.
Packages should have names long enough to be descriptive and should follow naming conventions (StPackageName).
Each domain consists of a number of packages that are associated with a particular subsystem. Only packages originating in STAF days are under these domains; newer packages are under $STAR/StRoot. The domains live under the $STAR/pams directory. The list of domains as of 7/98 was
DOMAIN DESCRIPTION _________________________________________________________ ctf Central trigger barrel software doc Overall software documentation emc Electromagnetic calorimeter software ftpc Forward TPC software gen Physics generators geometry Detector geometry descriptions for GSTAR global Global track reconstruction magnet Magnetic field mwc MWC trigger detector sim GSTAR Geant simulation svt Silicon vertex tracker tpc Time projection chamber trg Trigger software vpd Vertex position detector
Each domain contains the following directory substructure:
pams/domain/idl table IDL file definitions for all packages /inc include or header files used by more than one package /kumac kumac files for all the packages /packages directory for each package
As an example, the TPC domain directories as of 7/98 are shown below.
pams/tpc/idl /inc /kumac /tcl - clustering /tdi - distortions /tfc - reformating plus misc. /tfs - fast simulator /tid - dE/dx for particle ID /tpg - geometry /tpt - tracking /tss - slow simulator /tte - track evaluator
Each domain is the overall responsibility of one person. Who that person is can be found from the list of responsibles for sections of the CVS repository - the lead entry for a particular domain is the responsible person. For example the entry
avail |margetis,caines,kathy |pams/globalindicates Spiros Margetis is responsible for the global domain. The full entry indicates the people currently allowed to check code into CVS.
In STAR we use the term package to refer to a set of software performing a specific and fairly narrow function, typically associated with one or a few authors. A package exists in the repository as a directory, typically under StRoot/ for recent packages and under pams/domain for old packages, and contains
As an example, the files in the pams/tpc/tfs package is shown below (as of 7/98). There are 2 modules (tfs_filt and tfs_g2t) with source code and module idl files. There are also other source codes called from the modules. The way to find the modules (as opposed to other source code) is to list the idl files and look for the source code of the same name.
pams/tpc/tfs/README - information doc - subdirectory with documents tfs_displ_event.F - associated source tfs_filt.c - Module source tfs_filt.idl - Module idl tfs_g2t.F - Module source tfs_g2t.idl - Module idl tfs_g2t_hit_rd.F - associated source tfs_gen_padres.F - associated source tfs_hit_smear.F - associated source tfs_hit_sort.F - associated source tfs_ini.F - associated source tfs_tpchit_merge.F - associated source
To find the definitions of the tables used by a particular module, first look at the module idl file and get the list of table idl's: For example, look at tfs_g2t.idl and see that it uses tables:
#include "PAM.idl" #include "g2t_tpc_hit.idl" #include "g2t_track.idl" #include "tfs_fspar.idl" #include "tfs_bmpar.idl" #include "tfs_fsctrl.idl" #include "tcl_tpc_index.idl" #include "tcl_tpc_index_type.idl" #include "tcl_tphit.idl"Then look in the pams/tpc/idl area for these files which define the structure of the table. They may also be under other domains (g2t*.idl above are in pams/sim/idl).
Use the CVS repository browser to browse the current directory structure.
Use the cross-referenced code browser to browse the software for specific recent releases with hyperlinked source code and the ability to search for particular identifiers, files and text.
For software under pams/, use the PAM browser to browse all domains and packages and all the tables they define and use.