Cross-package dependencies in CLHEP

Proposed Rules for pieces of one CLHEP package that depend on another CLHEP package

Author: Mark Fischler, FNAL.

1. CLHEP has a package called Tools. This is in a sense a meta-package. It contains :
   
   
   1. Classes which are associated with one CLHEP package but which depend on some other CLHEP packages. We refer to these as cross-package classes (CPs for short in this document).
      
      The CPs are placed in subdirectories of the Tools package named the same as their associated package.
      
      Example: Tools/Random/RandMultiGauss.h and .cc
   
   
   
   2. Classes which are useful but not suitable for placing in a package of their own. These can also depend other CLHEP packages. These are in the directory Tools/Utilities.



2. Normally, the entire contents of a CLHEP package (other than Tools) must not depend on anything outside the package, and can be built in isolation. See -5- when an exception to this rule is necessary.



3. CPs may depend on any classes in regular CLHEP packages, and any classes in their own sub-directory of Tools. They may not depend on CPs associated with a different package. (Because of that last point, there inherently can't be cyclic dependencies among the CPs).
   
   Classes in Tools/Utilities can depend on any CLHEP packages or CPs.
   
   The entire Tools package is buildable by building all the regular CLHEP packages, then all the CPs, then the Utilities.



4. For documentation purposes, a class in a CP is considered to be part of its associated package. It must be documented as part of that package documentation, with an indication that the code is found in the Tools package due to dependencies.
   
   In the main directory of any package that has associated CPs, there must be a file named CrossingPackages listing the associated CPs, and showing which other packages they depend on.

   	  Example:  CLHEP/Random/CrossingPackages would list
   	            CLHEP/Tools/Random/RandomVector:   Matrix
   	            CLHEP/Tools/Random/RandMultiGauss: Matrix
   	

   There should be a link to this file, named dependencies, in the corresponding CP subdirectory (in the example, in CLHEP/Tools/Random).



5. Sometimes a large fraction of one package "A" may depend on another CLHEP package "B." In that case, rule -2- need not apply, and package A is said to have a fundamental dependency on package B. The rules become:
   
   
   1. There can be no cyclic dependencies among the fundamental dependencies.
      
      
   2. If package A has any fundamental dependencies, these must be listed in a file in the main director of package A, named FundamentalDependencies.
   
   Most packages probably have no fundamental dependencies. For example, Random should NOT depend on Matrix - that is what the idea of CPs is for.



6. CLHEP will maintain a package-level dependency diagram.
   • At the bottom will be the majority of CLHEP packages, which have no fundamental dependencies.
   • Next there will be the few packages with fundamental dependencies, with thick lines to show which other packages they need.
   • Then come the crossing packages, arranged above their associated package, and with thinner lines to other package they require.
   • Finally the Tools/Utilities classes are grouped into boxes, with lines indicating which packages each group depends upon.




---

Andreas.Pfeiffer@cern.ch
Last modified: Tue May 4 14:49:15 CEST