Domains, Packages, Makers and Modules

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).

Domain

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/global

Packages and Modules

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

• source codes, including, typically, a Maker interface to make the package a plug-in component to the ROOT framework
• a README file which should describe the package and who maintains it
• documentation files in html form (in a doc subdirectory)
• header files
• module IDL files which define interfaces to STAF

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"

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.