<?xml version="1.0"?>
<!DOCTYPE CMT [ 
  <!ENTITY nbsp "&nbsp;">
  <!ENTITY CMTrelease "18">
  <!ENTITY CMTVersion "v1r18p20041201">
  <!ENTITY CMTvTag "CMTv1">
  <!ENTITY CMTrTag "CMTr18">
  <!ENTITY CMTpTag "CMTp20041201">
  <!ENTITY CMTrequirements "&nbsp;<a HREF='#The requirements file'>requirements</a>&nbsp;">
]>  

<!--

  <!ENTITY  SYSTEM ".xml">

-->


<cmt:book
	  name='CMT'
	  title='Configuration Management Tool'
	  version='&CMTVersion;'
	  author='Christian Arnault'
	  email='arnault@lal.in2p3.fr'>

  <cmt:section title='Presentation'>

    <p>This environment, based on some management conventions and
    comprising several utilities, is an attempt to
    formalize software production and especially configuration
    management around a <i>package</i>-oriented principle.</p>

    <p>The notion of <i>packages</i> represents hereafter a set of
    software components (that may be applications, libraries,
    documents, tools etc...)  that are to be used for producing a
    <i>system</i> or a <i>framework</i>.  In such an environment,
    several persons are assumed to participate in the development and
    the components themselves are either independent or related to
    each other.</p>

    <p>The environment provides conventions (for <i>naming</i>
    packages, files, directories and for <i>addressing</i> them) and
    tools for <i>automating</i> as much as possible the implementation
    of these conventions. It permits the <i>description</i> of the
    configuration requirements and automatically deduce from the
    description the effective set of configuration parameters needed
    to operate the packages (typically for <i>building</i> them or
    <i>using</i> them).</p>

    <p><tt>CMT</tt> lays upon some organisational or managerial
    principles or mechanisms described below. However, it permits in
    many respects the users or the managers to <i>control</i>,
    specialize and customize these mechanisms, through
    parameterization, strategy control and generic specifications.

      <ul>
        <li> Many such packages are produced and maintained.  </li>

        <li> Packages sets may be structured in <i>areas</i>
        implementing a <i>project</i> oriented organization.  </li>

        <li> The projects represent independent organisations of
        packages, but may be interconnected as a <i>direct acyclic
        graph</i> of projects</li>

	<li> The packages may or not be related with each other
	(defining also a <i>direct acyclic graph</i> of packages - not just
	a single tree).  </li>

	<li> The concept of package may be extended to implement
	structuring or organizing patterns such as those involved in
	project management. </li>

	<li> Project management policies and behavioural patterns can
	be easily expressed and automated by CMT. </li>

	<li> Each <i>executable application</i> (from now on simply
	named <i>applications</i>) either belongs to a particular
	package and/or defines its own environment and then makes use
	of some other packages.  </li>

        <li> Each package can be uniquely identified within the system
        or the framework by a <i>name</i> which is usually a short
        <i>mnemonic</i> and which may be also used for isolating its
        name-space (eg. by <i>prefixing</i> components of the package
        by its mnemonic).  </li>

	<li> A package installed in this environment may be
	<i>exported</i> to a site where the architecture is
	reproduced, and as long as the local organisation defined for
	the package is preserved through the transport, the
	reconstruction procedure will be preserved. Configuration
	specifications can be easily provided to cope with machine,
	site or system specific features.  </li>

	<li> Packages are maintained consistently to their declared
	relationships to each other through a <i>version</i>
	identification model based on :

	  <ul>

	    <li> a version is defined with a mnemonic comprising one
	    to three numbers the <i>major</i> id, the <i>minor</i> id,
	    and the <i>patch</i> id </li>

            <li> versions with different major ids are said to be
            incompatible, </li>

            <li> versions with same major ids but different minor ids
            are said to be backward compatible with respect of the
            minor id ordering.  </li>

            <li> versions differing only by their patch id are said to
            be fully compatible with each other. </li>

          </ul> 
        </li> 

        <li>Projects are also referenced using a <i>release</i></li>

        <li> Version control and management schemes (eg. by using
        <tt>CVS</tt>) are usually consistently operated, applying the
        conventions on organization and version identification.  </li>

        <li> An application that uses one or several packages managed
        in this environment should not itself be constrained to be
        managed by <tt>CMT</tt>. The tools should only require a few
        exported features (such as a few environment variables) for
        referencing any given package.  </li>

        <li> Similarly, a package maintained in this environment must
        be able to use packages that are <i>not</i> managed in this
        environment (which are often called <i>external</i> packages).
        </li>

      </ul>
    </p>

    <p>Following these definitions, the basic configuration management
    operations involved here (and serviced by the <tt>CMT</tt>' tools)
    consist of :

      <ul> 

        <li> installing the packages in conventional locations so that
        they can be referenced by each other, following projects or
        teams structuring paradigms, </li>

        <li> describing the configuration &CMTrequirements; for each
        package:

          <ul> 

            <li> dependencies to other packages, </li>

            <li> generic behavioural patterns meant to describe
            generic configuration items or project specific policies.
            </li>

            <li> symbols to be exported to client packages
            (environment variables, make macros, etc...)  </li>

            <li> parameterized configuration activities (documentation
            generation, deploiement, installation, etc...)</li>

            <li> components (also named <i>constituents</i>) of the
            packages (libraries, applications, generated documents) </li>

            <li> parameterization of the build and test tools </li>

            <li> parameterization of the deployment tools </li>

            <li> strategies that <tt>CMT</tt> should follow at run time,
            overriding its default ones.  </li>

          </ul> 
        </li> 

        <li> deducing the effective configuration parameters from the
        &CMTrequirements; so as to
        automatize the building phases and the run-time operations and
        connections between packages (typically for generating
        makefiles, generating compiler and linker options, shared
        libraries paths etc...). This construction mechanism follows
        customizable strategies (eg. for selecting among possible
        alternate versions of available packages).  </li>

      </ul> 
    </p>

  </cmt:section>

  <cmt:section title='The conventions'>

    <p>This environment relies on a set of conventions, mainly for
    organizing the directories where projects and packages are
    maintained and developed : </p>

    <ul> 

      <li> Each package is installed in a standard directory structure
      defined at least as follows:

        <cmt:code>&lt;some root&gt;/&lt;Package mnemonic&gt;/&lt;version mnemonic&gt;/cmt</cmt:code>

        <p>or (<i>obsolescent convention</i>)

          <cmt:code>&lt;some root&gt;/&lt;Package mnemonic&gt;/&lt;version mnemonic&gt;/mgr</cmt:code>

        </p>

	<p>The &lt;version mnemonic&gt; directory level may also be
	omitted, in which case the version information will be stored
	inside the cmt directory in a conventional file named
	<tt>version.cmt</tt> leading to the following alternate
	organization:</p>

        <cmt:code>&lt;some root&gt;/&lt;Package mnemonic&gt;/cmt/version.cmt </cmt:code>

        <p>In both cases, the <tt>cmt</tt> directory holds the main source of information
        needed by <tt>CMT</tt>: the <i>requirements</i> file. All
        <tt>CMT</tt>-related operations are generally executed from this
        directory.</p>

        <p>This style of organization should be considered as the
        basic (and unique) criterion for a package to be recognized as
        a valid <i>CMT package</i>. Any other structuring convention will
        be supported by CMT and its operations can always be
        customized to follow them</p>

        <p>This structure is a central concept since all relationships
        between packages relies on the package identification which
        unambiguously and exclusively consists in the duet [
        <i>package-name</i>, <i>package-version</i> ] (or
        <i>package-name</i> only when the version directory level is
        omitted).</p>

      </li>

      <li> Constructing the internal structure of a package.

        <p>Many other parallel directory branches (similar to <tt>cmt</tt>) such
        as <tt>src</tt>, <tt>include</tt> or <tt>test</tt> may be freely
        added to this list according to the specific needs of each
        package.  In particular, a set of such parallel branches are
        expected to contain <i>binary</i> outputs (those that
        compilers, linkers, archive managers or other kinds of code or
        pseudo-code generators can produce). Their name always
        corresponds to the particular <i>configuration tag</i> used to
        produce the output (such as the machine or operating system
        type). The <tt>CMT</tt> toolkit provides, through the <tt>cmt
        system</tt> utility, a default value for this token. An
        environment variable (<tt>CMTCONFIG</tt>) is also assigned to
        this value (See the <a href="#Selecting a specific configuration">complete description</a> 
        of configuration tags).</p>

        <p>Each branch may in addition be freely structured, and there
        is no constraint to the complexity of this organization.</p>

        <cmt:image src="Images/InternalPackageStructure.jpg" caption="Structuring a package - A typical example."/>

      </li> 

      <p></p>

      <li> Organizing a software base.

        <p>A software base is generally composed of multiple coherent
        sets of packages, each installed in its specific root
        directory and forming different <i>package areas</i> or
        <i>sub-projects</i></p>

        <p>Package areas implement the concept of <i>projects</i> or
        <i>sub-projects</i> which correspond to the practical
        organization of the software base.</p>

        <p>There are no constraints on the number of such sub-projects
        or areas into which <tt>CMT</tt> packages are installed. We'll
        see <a HREF="#Localizing a package">later</a> how the
        different sub-projects can be declared and identified by
        <tt>CMT</tt>.</p>

        <p>examples of such organization can be : </p>

        <cmt:image src="Images/PackageStructure.jpg" caption="Structuring a sofware base."/>

      </li> 
    </ul> 

  </cmt:section>

  <cmt:section title="The architecture of the environment">

    <p>This environment is based on the fact that one of its packages
    (named <tt>CMT</tt>) provides the basic management
    tools. <tt>CMT</tt>, as a package, has very little specificities
    and as such itself obeys the general conventions.</p>

    <p>Then the complete software base is organized in terms of
    projects (or <i>sub-projects</i>), containing consistently managed
    package sets. Projects are localized either globally or
    individually:

      <ul>

        <li>globally using the environment variable
        <tt>CMTPROJECTPATH</tt> that describes all locations where CMT
        projects can be found</li>

        <li>individually using the environment variable
        <tt>CMTPATH</tt> that describe all package areas where
        packages can be found</li>

      </ul>

    Packages are localized respectively to the projects they belong
    to.</p>

    <p>It should be noted that the choice of a location for installing
    CMT itself is totally independent of the locations where projects
    are installed and managed.</p>

    <p><tt>CMT</tt> is operated through one main user interface : the
    <tt>cmt</tt> command, which operates the <tt>CMT</tt> conventions
    and which provides a set of services for : </p>

    <ul> 

      <li> creating a new package. This operation will create or check
      the local package directory tree and generate several minimal
      scripts (see the description of the <a HREF="#create">create</a>
      command), </li>

      <li> describing or monitoring :

        <ul> 

          <li> the relationships between the package and other
          packages </li>

          <li> the configuration features either specified in the
          current package, or imported from related (<i>used</i>)
          ones. (symbols, patterns, fragments) </li>

          <li> the constituents of the package in terms of libraries,
          executables, or generated documents.  </li>

        </ul> 
      </li> 

      <li> automatically generating the reconstruction scripts
      (<tt>makefiles</tt>) from this description.  </li>

      <li> recursively acting upon the hierarchy of used packages.
      </li>

    </ul> 

    <p>Several other utilities are also provided for some specific
    activities (such as the automatic production of shared libraries,
    <tt>C</tt> prototypes, management of interactions between <tt>CVS</tt>
    and <tt>CMT</tt> itself, the management of a similar architecture
    for <tt>Windows</tt> or <tt>OS9</tt>, setting up protections for
    packages (through locks) etc...). </p>

    <cmt:section title="Supported platforms">

      <tt>CMT</tt> has been ported and tested on a wide range of
      machines/operating systems, including :

      <ul>

        <li> DEC-Unix V4.0 </li>

        <li> HP-UX-10 (several types of platforms) </li>

        <li> AIX-4 </li>

        <li> Solaris </li>

        <li> IRIX </li>

        <li> Several variants of LynxOS </li>

        <li> All variants of Linux (RedHat, Debian, SuSe, ScientificLinux, ...) </li>

        <li> Windows 95/98/NT/Windows2000 in various environments:

	  <ul>

	    <li> <tt>CYGWIN_NT-5.1</tt> environment </li>

	    <li> <tt>nmake</tt> based environment </li>

	    <li> <tt>MSDev/VisualC 6</tt> environment</li>

	    <li> <tt>MSDev/VisualC 7</tt> environment</li>

	  </ul>

        </li>

        <li> Darwin (Mac OS X) </li>

      </ul> 

      This in particular means that a package developped on one
      platform may be re-configured towards any of these platforms
      without any change to its configuration description. All
      platform specific tools will be dynamically reconfigured and
      parameterized transparently.

    </cmt:section> 

  </cmt:section> 


  <cmt:section title="Defining and managing projects">

    <p>In the CMT terminology, the complete software base is composed
    of CMT packages. Those packages are organized into
    sub-projects. The semantics of a sub-project is very opened since
    it's merely an area for grouping CMT packages. Typically
    sub-projects may correspond to</p>

    <ul>

      <li>a structuration in software domains, such as Reconstruction,
      Simulation, Graphics, Core, etc.</li>

      <li>how responsibilities or management policies are defined and
      assigned </li>

      <li>reusing or sharing different software products from
      different projects</li>

    </ul>

    <p>Considering the simple structuring aspects of sub-projects, two
    important configuration parameters (environment variables) handled
    by CMT must be understood before attempting to manage
    packages:</p>

    <ul>

      <li><a href="#CMTPROJECTPATH"><tt>CMTPROJECTPATH</tt></a> for a
      global specification of where projects can be found. This
      specification should be considered as the standard mechanism for
      structuring the software base since from it, CMT can and will
      deduce all other localization parameters (like
      <tt>CMTPATH</tt>).<p></p></li>

      <li><a href="#CMTPATH"><tt>CMTPATH</tt></a> offers a more
      internal mechanism for localizing packages. It's not generally
      meant to be defined manually since CMT will construct it from
      <tt>CMTPROJECTPATH</tt>. However, it's important to understand
      how this configuration parameter is used to locate
      packages.</li>
    </ul>

    <p>Projects receive detailed descriptions or specifications in a
    dedicated <i>project file</i>, always located in a <tt>cmt</tt>
    directory at their top directory level, and named
    <tt>cmt/project.cmt</tt>. It can receive the following
    specifications:</p>

    <cmt:cmtcode>
project &lt;project-name&gt;          [1]
<i>project-use specifications...</i>   [2]
<i>strategy specifications...</i>      [3]
</cmt:cmtcode>

    <ol>

      <li>The project name specified here takes precedence over the
      project name specified in the directory structure. However when
      <tt>CMTPROJECTPATH</tt> is not specified, this may cause
      conflicts in the localization of projects. In this case it's
      highly recommended to always use the same naming convention in
      project files as in the directory hierarchy.<p></p></li>

      <li>Projects are hierarchized as a directed acyclic graph. The
      minimal hierarchy simply corresponds to the order of the
      <tt>CMTPATH</tt> items. A more complex hierarchy can be
      specified through use statements between sub-projects. This
      hierarchy also defines a <i>parent/child</i> relationship between
      projects. If a project <tt>A</tt> uses another project
      <tt>B</tt>, <tt>A</tt> is also named the <i>parent</i> and
      <tt>B</tt> the <i>child</i><p></p></li>

      <li>CMT Strategies (for build or setup) are separately
       collected into each project. Therefore one can apply different
       strategies to different sub-projects. The strategy
       specifications may appear in requirements file of any package
       of a project or in the <tt>cmt/project.cmt</tt> project file.

       <p>By default a project inherits the strategies of its
       parents. Or if it's the top project, it follows the default
       strategies defined by CMT (Refer to this 

       <a href="#The default strategies defined in CMT">appendix</a>
       to see the default strategies currently defined by CMT).</p>

       <p></p></li>

    </ol>

    <cmt:section title="The project file">

      <p>The project file can be created using the command:</p>

      <cmt:code>
&gt; cmt create_project &lt;project-name&gt; [&lt;release&gt;] [&lt;path&gt;]</cmt:code>

      <p>This will create the complete directory hierarchy from the
      current directory (or, when it is specified from the optional
      project path). It will also create a project file containing the
      project name.</p>

      <blockquote><i>Note that the &lt;release&gt; argument may be
      left empty (or to an empty string). In this case, the directory
      hierarchy will be limited to one level devoted to the project
      name.</i></blockquote>

      <cmt:code>
&lt;path&gt;/&lt;project-name&gt;/&lt;release&gt;/cmt/project.cmt
&lt;path&gt;/&lt;project-name&gt;/cmt/project.cmt</cmt:code>

      <p>As an example, we create the following projects:</p>

      <cmt:code>
&gt; cmt create_project WorkArea "" /test
&gt; cmt create_project ProjectA 1.0 /test
&gt; cmt create_project ProjectB 1.0 /test</cmt:code>

      <p>And we fill <tt>CMTPATH</tt> with:</p>

      <cmt:code>
/test/WorkArea:/test/ProjectA/1.0:/test/ProjectB/1.0</cmt:code>

      <p>Then the following projects will appear displayed from bottom
      to top as</p>

      <cmt:code>
&gt; cd /test/WorkArea
&gt; cmt show projects 
<i><font face="courier new, courier" COLOR="#000077">WorkArea (in /test/WorkArea) (current)
  ProjectA 1.0 (in /test/ProjectA/1.0)
    ProjectB 1.0 (in /test/ProjectB/1.0)</font></i></cmt:code>

      <p>Of course the preferred way to characterize this software
      base should rather be based on specifying the relationships
      between those three sub-projects, through the use statements in
      the projects files.</p>

      <p>For instance in our little example, we could add the
      following statement into the project file of WorkArea:</p>

      <cmt:code>
use ProjectA 1.0</cmt:code>

      <p>and the following statement into the project file of ProjectB:</p>

      <cmt:code>
use ProjectB 1.0</cmt:code>

      <p>Then instead of specifying <tt>CMTPATH</tt> we'd rather
      simply define <tt>CMTPROJECTPATH</tt> as:</p>

      <cmt:code>
/test</cmt:code>

    </cmt:section>

    <cmt:section title="Projects and strategies">

      <p>Every strategy setting defines two mutually exclusive tags
      and activates one of them.</p>

      <cmt:cmtcode>
&lt;project&gt;_&lt;have_item&gt; 
&lt;project&gt;_&lt;have_not_item&gt; </cmt:cmtcode>

      <p>Examples</p> 

      <cmt:cmtcode>
&lt;project&gt;_prototypes
&lt;project&gt;_no_prototypes
&lt;project&gt;_with_install_area
&lt;project&gt;_without_install_area
&lt;project&gt;_config
&lt;project&gt;_no_config
&lt;project&gt;_root
&lt;project&gt;_no_root
&lt;project&gt;_cleanup
&lt;project&gt;_no_cleanup</cmt:cmtcode>

      <p>In particular, the installation area mechanism is strongly
      connected with the project hierarchy. This happens through
      several mechanisms:</p>

      <ul>

        <li>The <tt>&lt;project&gt;</tt> parameter is expanded in the
        <tt>cmtpath_pattern</tt> construct in addition to the
        <tt>&lt;path&gt;</tt> parameter. This parameter is assigned
        the name of the project associated with the running
        <tt>CMTPATH</tt> entry.  <p></p></li>

        <li>The <tt>&lt;project&gt;</tt> parameter is also available
        for normal patterns. In this case it is assigned the project
        name associated with the cmtpath parameter for the current
        package.<p></p></li>

        <li>Every project defines a tag of the same name, and the tag
        of the current project is active.<p></p></li>

        <li>The <tt>cmt_installarea_prefix</tt> macro is specialized
        <i>per project</i> and every project may override the
        <tt>&lt;project&gt;_installarea_prefix</tt> macro. The default
        value of any <tt>&lt;project&gt;_installarea_prefix</tt> is
        <tt>${cmt_installarea_prefix}</tt> <p></p></li>

      </ul>

    </cmt:section>

    <cmt:section title="CMTPROJECTPATH">

      <p>This is an environment variable containing a search list,
      very similar to the well know Unix or Windows <tt>PATH</tt>
      environment variable, containing a list of file paths where CMT
      projects can be found. The syntax of this search list follows
      the standard syntax of search lists, i.e. items are separated
      using a <tt>:</tt> character on Unix and a <tt>;</tt> character
      on Windows.</p>

      <p><blockquote><i>One should understand this search list as the
      primary mechanism to locate sub-projects in the software base,
      and therefore packages. This in particular can completely
      replace the <tt>CMTPATH</tt>-based search mechanism for packages
      that was used before <tt>v1r18</tt>. However the two mechanisms
      are still both supported and in fact interact with each
      other.</i></blockquote></p>

      <p>A sub-project in itself is a multi-level directory structure,
      located below one of the items of this search list, and composed
      of:</p>

      <ul>

        <li>the sub-project name</li>

        <li>the sub-project release (which may span several directory levels)</li>

      </ul>

      <p>Then, below this directory structure, we find</p>

      <ul>

        <li>A project definition file in <tt>cmt/project.cmt</tt></li>

        <li>A set of CMT packages</li>

      </ul>

      <p>A typical example of such a structure could be:</p>

      <cmt:code>
/project-area1/Reconstruction/1.0/cmt/project.cmt
                                 /RecA/...
                                 /RecB/...
/project-area1/Reconstruction/2.0/cmt/project.cmt
                                 /RecA/...
                                 /RecB/...

/project-area1/Simulation/1.0/cmt/project.cmt
                             /SimA/...
                             /SimB/...
/project-area1/Core/1.0/cmt/project.cmt
                       /CoreA/...
                       /CoreB/...


/project-area2/ProductA/1.1.2/cmt/project.cmt
                             /PA_A/...
                             /PA_B/...
                             /PA_C/...
/project-area2/ProductB/v1r8p3/cmt/project.cmt
                              /PB_A/...
                              /PB_B/...
/project-area2/ProductB/v1r10/cmt/project.cmt
                             /PB_A/...
                             /PB_B/...   </cmt:code>

      <ul>

        <li>there are two project areas, one for the main
        developments, and another one for managing external products</li>

        <li><tt>project-area1</tt> offers three sub-projects
        <tt>Reconstruction</tt>, <tt>Simulation</tt> and
        <tt>Core</tt></li>

        <li><tt>project-area2</tt> offers two sub-projects
        <tt>ProductA</tt> and <tt>ProductB</tt></li>

        <li>the sub-project <tt>Reconstruction</tt> is available in two
        releases <tt>1.0</tt> and <tt>2.0</tt></li>

        <li>the sub-project <tt>Reconstruction</tt> offers two packages
        <tt>RecA</tt> and <tt>RecB</tt></li>

        <li>the sub-project <tt>ProductB</tt> is available in two
        releases <tt>v1r8p3</tt> and <tt>v1r10</tt></li>

      </ul>

      <p>This search list is used to interpret the <i>use</i>
      statements written in the project files. This project use
      statement takes the form:</p>

      <cmt:syntax name="project-use">
        <cmt:rule name="project-use">
          <cmt:alt>
            <cmt:kwd name="use"/>
            <cmt:term name="project-name"/>
            <cmt:term name="project-release"/>
          </cmt:alt>
        </cmt:rule>
      </cmt:syntax>

      <p>Typically, in our example one could construct the project
      file of the <tt>Reconstruction</tt> sub-project as follows:</p>

      <cmt:code>
use Core 1.0
use ProductA 1.1.2</cmt:code>

      <p><i>Note that sub-project release identifiers are always
      considered using a perfect-match principle.</i></p>

      <p>Structuring the set of sub-projects comprising a software
      base is sufficient to permit CMT to find <i>all</i> sub-projects
      and thus <i>all</i> packages in them. Defining
      <tt>CMTPROJECTPATH</tt> <i>and</i> installing the list of use
      statements in all appropriate project files entirely suppress
      the need of manually defining the <tt>CMTPATH</tt> search
      list.</p>

    </cmt:section>

    <cmt:section title="CMTPATH">

      <p>This is an environment variable containing a search list,
      very similar to the well know <tt>PATH</tt> environment
      variable, containing a list of file paths where CMT packages can
      be found. The syntax of this search list follows the standard
      syntax of search lists, i.e. items are separated using a
      <tt>:</tt> character on Unix and a <tt>;</tt> character on
      Windows.</p>

      <p><blockquote><i>When the software base is organized and
      configured using the <a
      href="#CMTPROJECTPATH"><tt>CMTPROJECTPATH</tt></a> search list
      and project-use statements in the project files, this search
      list is automatically and internally generated by CMT, and
      therefore it should not be manually defined nor manipulated. If
      this is your case, you can skip this
      section</i></blockquote></p>

      <p>It is possible to manually define this search list (when
      <tt>CMTPROJECTPATH</tt> is not defined or when project files are
      not provided)</p>

      <p>There should be one entry per package area, and the list is
      ordered. The order of items is used to prioritize the package
      search.</p>

      <p><tt>CMTPATH</tt> can be specified:</p>

      <ul>

        <li>as the environment variable named <tt>CMTPATH</tt>

          <cmt:code>
sh&gt; export CMTPATH=/home/arnault/mydev:/ProjectB </cmt:code>

          <cmt:code>
bat&gt; set CMTPATH=/home/arnault/mydev;/ProjectB </cmt:code>

          or (in a <tt>requirements</tt> file) 

          <cmt:cmtcode>
path_append CMTPATH "/home/arnault/mydev"
path_append CMTPATH "/ProjectB"</cmt:cmtcode>

        </li>

        <li>in <tt>.cmtrc</tt> files, which can be located either in
        the current directory, in the <i>home</i> directory of the
        developper or in <tt>${CMTROOT}/mgr</tt>. The syntax to use in this
        configuration file is:

          <cmt:code>
CMTPATH=/home/arnault/mydev:/ProjectB </cmt:code>

        </li>

        <li>In the Windows environment, this configuration parameter
        may also be installed as a <i>Registry</i> under the alternate
        keys:

          <ul> 
            <li> <tt>HKEY_LOCAL_MACHINE/Software/CMT/path</tt> </li>
            <li> <tt>HKEY_CURRENT_USER/Software/CMT/path</tt> </li>
          </ul>
        </li>
      </ul>

      <blockquote><i>The project file (i.e. the file
      <tt>cmt/project.cmt</tt>), when it exists for the current
      package (i.e. upstream in the directory hierarchy), also
      provides an automatic value for the <tt>CMTPATH</tt> search
      list.</i></blockquote>

    </cmt:section>

  </cmt:section>

  <cmt:section title="Installing a new package">

    <p>We consider here the installation of a user package. Installing
    <tt>CMT</tt> itself requires special attention and is described in a 
    dedicated <a href="#Installing CMT for the first time">section</a>
    of this document.</p>

    <p>Therefore, we assume that <tt>CMT</tt> is already installed in
    some location in the system.  One first has to <i>setup</i>
    <tt>CMT</tt> in order to gain access to the various management
    utilities, using for example the shell command: </p>

    <cmt:code>
csh&gt; source /lal/CMT/&CMTVersion;/mgr/setup.csh

or 

ksh&gt; . /lal/CMT/&CMTVersion;/mgr/setup.sh

or 

dos&gt; call \lal\CMT\&CMTVersion;\mgr\setup.bat</cmt:code> 

    <p>Obviously, this operation <i>must</i> be performed (once)
    before any other <tt>CMT</tt> action. Therefore it is often
    recommended to install this setup action straight in the
    <i>login</i> script. </p>

    <cmt:blockquote>
      <i>

        <p> The <i>setup script</i> used in this example is a constant
        in the <tt>CMT</tt> environment : every configured package
        will have one such setup script automatically generated and
        installed by <tt>CMT</tt>. It is one important entry point to
        any package (and thus to <tt>CMT</tt> itself). It provides
        environment variable definitions for all related (<i>used</i>)
        packages (A corresponding cleanup script is also
        provided). This script contains a uniform mechanism for
        <i>interpreting</i> the &CMTrequirements; file so as to
        dynamically define environment variables, aliases for the
        package itself and all its used packages. It is constructed
        once per package installation by the <tt>cmt create</tt>
        command, or restored by the <tt>cmt config</tt> command (if it
        has been lost).</p>

      </i>
    </cmt:blockquote>        

    <p>It is generally good to start by immediately defining a
    <i>project</i>. This project is our first disk area where CMT
    packages will be located. Remember that several such projects can
    be set up and defined. The simplest way to do this is:</p>

    <cmt:code>
&gt; cmt create_project Dev
<i><font face="courier new, courier" COLOR="#000077">------------------------------------------
Configuring environment for project Dev
CMT version &CMTVersion;.
------------------------------------------
Installing the cmt directory
Creating a new project file </font></i></cmt:code>

    <p>This creates a project structure
    <tt>Dev/cmt/project.cmt</tt> from the current directory. Once
    this project has been created we have a complete environment to
    start creating packages below <tt>Dev</tt> and working out our software base.</p>

    <p> A package is primarily defined by a <i>name</i> and a
    <i>version</i> identifier (this duet actually forms the complete
    <i>package identifier</i>). These two attributes will be given as
    arguments to <tt>cmt create</tt> such as in the following example :
    </p>

    <cmt:code>
csh&gt; cd Dev
csh&gt; cmt create Foo v1
<i><font face="courier new, courier" COLOR="#000077">------------------------------------------
Configuring environment for package Foo version v1.
CMT version &CMTVersion;.                              [1]
Root set to /home/arnault/Dev.
System is Linux-i686                                     [2]
------------------------------------------
Installing the package directory                         [3]
Installing the version directory
Installing the cmt directory
Installing the src directory
Creating setup scripts.
Creating cleanup scripts. </font></i></cmt:code>

    <ol>

      <li>This shows which actual CMT version you are currently using</li>

      <li>This shows the current configuration tag (also available by
      the <tt>cmt system</tt> command). In this example this is a
      <tt>Linux</tt> machine</li>

      <li>This shows the detailed construction of the complete
      directory structure, starting from the top directory which has
      the name of the package. Since we are creating a completely new
      package, there will be by default only two branches below the
      version directory : <tt>cmt</tt> and <tt>src</tt>.</li>

    </ol>

    <p>The package creation occured from the current directory,
    creating from there the complete directory tree for this new
    package.</p>

    <p>In the next example, we install the package in a completely
    different area, by explicitly specifying the path to it as a third
    argument to <tt>cmt create</tt> : </p>

    <cmt:code>
&gt; cmt create Foo v1 /ProjectB 
<i><font face="courier new, courier" COLOR="#007700">------------------------------------------
Configuring environment for package Foo version v1.
CMT version &CMTVersion;.
Root set to /ProjectB.
System is Linux-i686
------------------------------------------
Installing the path directory
Installing the package directory
Installing the version directory
Installing the cmt directory
Installing the src directory
Creating setup scripts.
Creating cleanup scripts. </font></i></cmt:code>

    <p></p>        

    Several file creations occurred at this level : 

    <ul> 

      <li> a minimal directory tree for the package, including
      <tt>src</tt> and <tt>cmt</tt> (the other branches will be installed
      when needed or generated at build time).  </li>

      <p></p>

      <li> an empty configuration specification file (named
      <tt>requirements</tt>) installed in the <tt>cmt</tt> branch.  </li>

      <p></p>

      <li> A minimal <tt>Makefile</tt> (on Unix environments only),
      containing

        <cmt:code>
include $(CMTROOT)/src/Makefile.header 

include $(CMTROOT)/src/constituents.make </cmt:code>

        <p></p>

        This <tt>Makefile</tt> does not need any further modification to
        build any of the constituents managed by <tt>CMT</tt>. The
        intermediate makefile fragments will always be re-generated
        transparently and automatically at build time. However (and
        thanks to this feature), this file will not be modified
        <i>anymore</i> by <tt>CMT</tt> itself. Thus you may insert any
        particular make statement you would feel appropriate,
        typically when you ask for operations that cannot be taken
        - if any - into account by <tt>CMT</tt>.

      </li> 

      <p></p>

      <li> A similar minimal <tt>NMake</tt> file (on Windows
      environments only), containing

        <cmt:code>
!include $(CMTROOT)\src\NMakefile.header 

!include $(CMTROOT)\src\constituents.nmake </cmt:code>

      </li>

      <p></p>

      <li> the setup and cleanup scripts (one flavour for each shell
      family).  </li>

    </ul> 

    One <i>may</i> then setup this new package by running the setup
    script (which will not have much effect yet since the requirements
    file is empty) :

    <cmt:code>
sh&gt; cd ~/mydev/Foo/v1/cmt 
sh&gt; . setup.sh </cmt:code>

or 

    <cmt:code>
csh&gt; cd ~/mydev/Foo/v1/cmt 
csh&gt; source setup.csh </cmt:code>

or 

    <cmt:code>
dos&gt; cd \mydev\Foo\v1\cmt 
dos&gt; call setup.bat</cmt:code>

    <p>The <tt>FOOROOT</tt> and <tt>FOOCONFIG</tt> environment variables
    are defined automatically by this operation. </p>

    <p>It should be noted that running the setup script of a package
    is not always necessary for building operations. The only
    situation where running this script <i>may</i> become useful, is
    when an application is to be run, while requiring domain specific
    environment variables defined in one of the used packages. Besides
    this particular situation, running the setup scripts may not be
    needed at all. </p>

    <p>Lastly, this newly created package may be removed by the quite
    similar remove command, using exactly the same arguments as those
    used for creating the package.</p>

    <cmt:code>csh&gt; cd mydev
csh&gt; cmt remove Foo v1 
<i><font face="courier new, courier" COLOR="#000077">------------------------------------------
Removing package Foo version v1.
CMT version &CMTVersion;.
Root set to /home/arnault/mydev.
System is Linux-i686
------------------------------------------
Version v1 has been removed from /home/arnault/mydev/Foo
Package Foo has no more versions. Thus it has been removed.</font></i></cmt:code>

    or:

    <cmt:code>csh&gt; cmt remove Foo v1 /ProjectB
<i><font face="courier new, courier" COLOR="#000077">------------------------------------------
Removing package Foo version v1.
CMT version &CMTVersion;.
Root set to /ProjectB.
System is Linux-i686
------------------------------------------
Version v1 has been removed from /ProjectB/Foo
Package Foo has no more versions. Thus it has been removed.</font></i></cmt:code>

    <p>So far our package is not very useful since no constituent
    (application or library) is installed yet. You can jump to the
    section showing how to work on an <a href="#Working on an application">application</a> 
    or on a <a href="#Working on a library">library</a> 
    for details on these operations or we can
    roughly draw the sequence used to specify and build the simplest
    application we can think of as follows:</p>

    <cmt:code>
csh&gt; cd ~/mydev/Foo/v1/cmt
csh&gt; cat &gt;../src/FooTest.c 
#include &lt;stdio.h&gt;

int main ()
{
  printf ("Hello Foo\n");
  return (0);
}

csh&gt; vi requirements 
... 
application FooTest FooTest.c 
csh&gt; gmake
csh&gt; source setup.csh
csh&gt; FooTest.exe
<i><font face="courier new, courier" COLOR="#007700">Hello Foo</font></i></cmt:code>

    <p>Directly running the application is possible since the
    application has been installed after being built in
    an automatic <i>installation area</i> reachable through the
    standard <tt>PATH</tt> environment variable</p>

    <p>This can also be integrated in the build process by providing
    the -check option to the application definition:</p>

    <cmt:code>
csh&gt; cd ../cmt 
csh&gt; vi requirements 
... 
application FooTest -check FooTest.c 
csh&gt; gmake check
<i><font face="courier new, courier" COLOR="#000077">Hello Foo</font></i></cmt:code>

  </cmt:section>

  <cmt:section title="Localizing a package">

    <p>In the next sections, we'll see that packages <i>reference</i>
    each other by means of <i>use</i> relationships. Generally
    packages are found in different locations, according to the
    project - or sub-project - they belong to.  <tt>CMT</tt> provides a
    quite flexible mechanism for <i>localizing</i> the referenced
    packages. </p>

    <p>The first ingredient we need at this level is to understand how
    projects themselves are localized, since packages will be found
    inside project areas. You should therefore refer to the 

    <a href="#Defining and managing projects">section on projects</a>
    where the complete mechanism based on <a
    href="#CMTPROJECTPATH"><tt>CMTPROJECTPATH</tt></a> or <a
    href="#CMTPATH"><tt>CMTPATH</tt></a> is described.</p>

    <p>However, there is one special case where this path list can be
    avoided, i.e. when only one project is considered. In this case,
    the knowledge of this single project area can simply be deduced
    from the detection of the project file, created at the top of its
    disk space.</p>

    <p>A given version of a given package is always referred to by
    using a <i>use</i> statement within its <tt>&CMTrequirements;</tt>
    file. This statement should specify the package through three
    <i>keys</i> :</p>

    <ul> 

      <li> its name (such as <tt>Bar</tt>) </li>

      <li> its version (such as <tt>v7r5</tt>) </li>

      <li> optionally its expected absolute location or relative
      offset
      </li>

    </ul> 

    <cmt:cmtcode>
use Bar v7r5                    [1]</cmt:cmtcode>

    <i>or</i>

    <cmt:cmtcode>
use Bar v7r5 A                  [2]</cmt:cmtcode>

    <i>or</i>

    <cmt:cmtcode>
use Bar v7r5 /ProjectB/A        [3]</cmt:cmtcode>

    <p>Given these keys, the referenced package is looked for
    according to a prioritized search list which is (in decreasing
    priority order) : </p>

    <ol> 

      <li> the absolute access path, if the <i>use path</i> is
      absolute (case #3), </li>

      <li> the access paths registered in the configuration parameter
      <a href="#CMTPATH"><tt>CMTPATH</tt></a> (and in decreasing
      priority, the first element being searched for first).</li>

    </ol> 

    <p>If the <i>path</i> argument is specified as a relative path
    (case #2 above) (ie. there is no leading <i>slash</i> character or
    it's not a <i>disk</i> on windows machines), it will be used as an
    <i>offset</i> to each search case. The search is done starting
    from the list specified in the <tt>CMTPATH</tt> configuration
    parameter; and the offset is appended at each searched
    location.</p>

    <p>As an example, if the <tt>CMTPATH</tt> parameter contains: </p>

    <cmt:code>
/home/arnault/mydev:/ProjectB </cmt:code>

    <p>Then a <i>use</i> statement (defined within a given package)
    containing : </p>

    <cmt:cmtcode>
... 
use Bar v7r5
use BarA v1 A</cmt:cmtcode>

    would look for the package <tt>Bar</tt> from :

    <ol> 

      <li> <tt>/home/arnault/mydev/Bar/v7r5/cmt</tt> </li>

      <li> <tt>/ProjectB/Bar/v7r5/cmt</tt> </li>

    </ol> 

    Whereas the package <tt>BarA</tt> would be searched from : 

    <ol> 

      <li> <tt>/home/arnault/mydev/A/BarA/v1/cmt</tt> </li>

      <li> <tt>/ProjectB/A/BarA/v1/cmt</tt> </li>

    </ol> 

    The packages are searched assuming that the directory hierarchy
    below the access paths always follow the convention :

    <ol> 

      <li> there is a first directory level exactly named according to
      the package name (this is case sensitive), </li>

      <li> then (optionally) the next directory level is named
      according to the version tag, </li>

      <li> then there is a branch named <tt>cmt</tt>, </li>

      <li> lastly there is a <i>requirements</i> file within this
      <tt>cmt</tt> branch.  </li>

    </ol> 

    Thus the list of access paths is searched for until these
    conditions are properly met.

    <p> The actual complete search list can always be visualized by
    the command:


      <cmt:code>
&gt; cmt show path
<i><font face="courier new, courier" COLOR="#000077"># Add path /home/arnault/dev from CMTPATH
# Add path /ProjectB from CMTPATH
#
/home/arnault/dev:/ProjectB</font></i></cmt:code>

    </p>

  </cmt:section>

  <cmt:section title="Assigning semantics to packages. Common practices">

    Generally speaking, CMT makes no assumption on how or why is used
    a package. However past experience has shown that packages can be
    categorized according to their purpose or their type of contents.

    <cmt:section title="The primary package">

      This is the most general and basic pakage type, which provides
      actual pieces of software, such as libraries or
      applications. Generally the main activities performed by such a
      package include building the software (compiling, linking),
      testing, generating the documentation, installing, ...

      <p>A typical package of that kind will contain:</p>

      <ul>

        <li>a <tt>../src</tt> directory containing the sources of the package</li>

	<li>a directory for the include files, with a name that will
	depend on the structuring policies defined for the
	project. Tyical examples are

	  <cmt:code>
../include/
../&lt;packagename&gt;/</cmt:code>

	</li>

	<li>a <tt>../doc</tt> directory for the documentation</li>

	<li>a <tt>../test</tt> directory for the test programs.</li>

      </ul>

      <p>The requirements file will generally contain at least
      <tt>library</tt> and <tt>application</tt> statements.</p>

    </cmt:section>

    <cmt:section title="The policy package">

      This kind of package only provides conventions, working methods,
      general purpose shell scripts but generally provides no software
      per se. It is designed to gather all policies and management
      conventions for a project or a sub project.

      <p>The basic contents of such a package is the requirements file
      including</p>

      <ul>

        <li>strategy definitions</li>
        <li>pattern definitions</li>
        <li>general purpose symbol definitions</li>

      </ul>

      <p>In principle the idea when such a policy package is defined,
      is that all packages of the project or of the sub-project will
      use it</p>

      <p>Global patterns may be specified so as to automate the
      applying of basic policies and conventions.</p>

      <p>Typical examples of policies that are profitably specified in
      such a package are:</p>

      <ul>

        <li>include search path convention (using a global pattern
        with the <tt>include_dir</tt> statement)</li>

        <li>build or setup strategies</li>

        <li>compiler or linker generic options</li>

        <li>defining the project-wide production tools (compiler,
        documentation generator, etc...)</li>

        <li>tag associations need to describe the binary tag
        convention in the project</li>

      </ul>

      <p>In large projects, it is even often desirable to split the
      policies into a set of specialized policies and to associate one
      dedicated policy package with each of those.</p>

      <ul>

        <li>policies for the test</li>

        <li>policies for each programming language</li>

        <li>policies for documentation management</li>

        <li>policies for installation and deployment</li>

        <li>policies for external software organisation</li>

      </ul>

      Then the global policy package will use them

    </cmt:section>

    <cmt:section title="The container or management package">

      In large projects, it's often useful to decompose the software
      base into specialized domains (Core software, Graphics,
      Database, Online, etc...) or subsets of the software (eg per
      detector in a physics experiment). Then a container package
      consists in constructing a simple package with only one
      requirements file in it and only containing a set of use
      statements.

      <p>Management activities directly related with the associated
      sub-domain can then be undertaken through this special
      package:</p>

      <ul>

        <li>version management (such as CVS tagging) of packages
        belonging to the domain</li>

	<li>consistently building the domain</li>

	<li>Generally the <tt>cmt broadcast</tt> command is widely exploited
	to perform those management activities.</li>

      </ul>

      <p> Generally the use statements installed in a container
      package make use of explicit version specification (and prohibit
      wild carding) since each version of this container package acts
      as a reference of the set of version tags validated for the
      packages of the domain.</p>

    </cmt:section>

    <cmt:section title="The release package">

      This package is one particular example of the container concept,
      but dedicated to manage the project-wide activities. This
      release package is the primary target of the project manager. It
      will generally receive as its version tags the version tags
      assigned to the project releases themselves.

    </cmt:section>

    <cmt:section title="The glue or interface package">

      This kind of package defines an interface to an existing
      software product not managed in the context of the project
      itself. Typical examples concern:

      <ul>

        <li>packages shared from external projects that don't use CMT
        as their configuration tool</li>

	<li>third party software (free software, commercial products,
	...)  locally installed on the development platform.</li>

      </ul>

      <p>The primary goal fo such a glue package is to convert the
      management conventions and policies expected by the referenced
      product to the ones appropriate for the current project.</p>

      <ul>

        <li>compiler and linker options</li>

	<li>run time settings such as environment variable definitions
	(PATH, LD_LIBRARY_PATH, etc..)</li>

	<li>data file access</li>

	<li>specification of local installation according to the
	project strategy</li>

      </ul>

      <p>Generally this kind of package only provides a requirements
      file, or make fragments used to automate some actions (typically
      when document generation is expected from thie interfaced
      product)</p>

    </cmt:section>

  </cmt:section>

  <cmt:section title="Managing site dependent features - The CMTSITE environment variable">

    <p>Software bases managed by <tt>CMT</tt> are often replicated to
    multiple geographically distant sites (as opposed to machines
    connected through AFS-like WAN). In this kind of situation, some
    of the configuration parameters (generally those used for instance
    to reference local installations of <i>external</i> software) take
    different values. </p>

    <p>The <tt>CMTSITE</tt> environment variable or <i>registry</i> in
    Windows environments, is entirely under the control of the
    <i>site</i> manager and can be set with a value representing
    the site (typical values may be <tt>LAL</tt>, <tt>Virgo</tt>,
    <tt>Atlas</tt>, <tt>LHCb</tt>, <tt>CERN</tt>, etc.). </p>

    <p>This variable, when set, corresponds to a <i>tag</i> which can
    be used to select different values for make macros or environment
    variables. </p>

    <p>A typical use for this tag is to build up actual values for the
    location path of an external software package. Here we take the
    example of the Anaphe utility: </p>

    <cmt:cmtcode>
macro AnapheTOP "" \
      CERN  "/afs/cern.ch/sw/lhcxx" \
      BNL   "/afs/rhic/usatlas/offline/external/lhcxx" \
      LBNL  "/auto/atlas/sw/lhcxx"</cmt:cmtcode>

  </cmt:section>

  <cmt:section title="Configuring a package">

    <p>The first ingredient of a proper package configuration is the
    set of configuration parameters which has to be specified in a
    text file uniquely named <tt>&CMTrequirements;</tt> and necessarily
    installed in the <tt>cmt</tt> branch of the package directory tree. </p>

    <p>An empty version of this file is automatically created the
    first time the package is installed, and the package manager is
    expected to augment it with configuration specifications. </p>

    <p>The primary goal of this configuration file is to specify
    <i>any</i> configuration information for this package. There is
    virtually no limit to what could be specified there. And we can
    expect to find exhaustive information about:

    <ul>

      <li>the primary constituents of the package</li>

      <li>how to rebuild the software</li>

      <li>how to setup and use the software</li>

      <li>how to transport and deploy the package</li>

    </ul>

    </p>

    <p>Many configuration parameters are supposed to be described into
    this &CMTrequirements; file - see the <a href="#The requirements file">detailed</a>
    syntax specifications here - namely :</p>

    <ul> 

      <li> the package information about its author(s) and manager(s) </li>

      <li> the relationships with other packages </li>

      <li> the package constituents (libraries, applications,
      documents, etc.) </li>

      <li> the policy patterns to be applied by clients of this
      package </li>

      <li> the parameterization of the tools used in the build process
      (eg. make macros) </li>

      <li> the parameterization of the run-time activity
      (eg. environment variables, search paths, etc.) </li>

    </ul> 

    <p>Generally, every such appropriate parameter will be deduced on
    demand from the &CMTrequirements; file(s) through the various
    query functions available from the <tt>cmt</tt> main
    driver. Therefore there is no systematic package re-configuration
    per se, besides the very first time a package is newly installed
    in its location (using the <tt>cmt create</tt> action). </p>

    <p>Query actions (generally provided using the <tt>cmt show ...</tt>
    <a HREF="#show">family</a> of commands) are to be embedded in the
    various productivity tools, such as the setup shell scripts, or
    makefile fragment generators. </p>

    <p>These query actions always interpret the set of
    &CMTrequirements; files obtained from the current package
    <i>and</i> from the packages in the effective <i>used</i>
    chain. Symbols, tags and other definitions are then computed and
    built up according to inheritance-like mechanisms set up between
    used packages. </p>

    <p>Conversely one may say that parameters defined in a
    &CMTrequirements; file are meant to be exported to the clients of
    the package.</p>

    <p>Other configuration parameters are also optionally inserted
    from the <tt>HOME</tt> and <tt>USER</tt> <a href=""><i>context</i></a>
    requirements files</p>

    <p>Typical examples of these query functions are: </p>

    <ul> 

      <li><tt>cmt setup</tt> builds a shell command line for setting up
      environment variables </li>

      <li><tt>cmt show projects</tt> gives the ordered sequence of
      sub-projects comprising the complete software base </li>

      <li><tt>cmt show macros</tt> construct the effective set of
      inherited make macros </li>

      <li><tt>cmt show uses</tt> gives the ordered and flattened set of
      used packages </li>

      <li><tt>cmt show constituents</tt> lists the package's
      constituents </li>

      <li><tt>cmt show path</tt> lists the effective search path for
      packages. </li>

      <li><tt>cmt show strategies</tt> shows the current setup of
      various functional <tt>CMT</tt> strategies. </li>

      <li><tt>cmt show setup</tt> combines in one display the result
      of <tt>uses</tt>, <tt>tags</tt> and <tt>path</tt> </li>

    </ul> 

  </cmt:section>

  <cmt:section title="Selecting a specific configuration">

    A configuration describes the conditions in which the package has
    to be built (ie. compiled and linked) or applications can be
    run. This configuration can depend on :

    <ul> 

      <li> the operating system (such as <i>Linux</i>, <i>Windows</i>,
      ...)  </li>

      <li> the platform (such as <i>Intel</i>, <i>Compaq</i>,
      <i>Sun</i>, etc...)  </li>

      <li> the sub-project into which a package is inserted </li>

      <li> the choice of the compiler (such as <i>g++</i>,
      <i>egcs</i>, <i>CC</i>, etc...)  </li>

      <li> options used for compiling (such as <i>optimizer</i>,
      <i>debugger</i>, etc...)  or linking </li>

      <li> the context specifications (selecting a particular version
      of a firmware, selecting a database server, ...)  </li>

      <li> the site itself</li>

      <li> the context of a constituent during its rebuild operation</li>

    </ul> 

    Carefully describing this configuration is essential both for
    maintenance operations (so as to remember the precise conditions
    in which the package was built) and when the development area is
    <i>shared</i> between machines running different operating
    systems, or when a project has to be deployed on several sites.

    <cmt:section title="Describing a configuration">

      <p> <tt>CMT</tt> relies on several complementary conventions or
      mechanisms for this description and the associated
      management. All these conventions rely on the concept of
      <i>configuration tags</i>.</p>

      <ul>

        <li>A tag is a symbol that describes one aspect of the
        configuration.</li>

	<li>A tag can be <i>active</i> when the corresponding aspect
	of the configuration is true or <i>inactive</i> otherwise</li>

	<li>The set of active tags represents the complete
	configuration known by CMT, and can be visualized with the
	<tt>cmt show tags</tt> command</li>

        <li>Tags can be combined using logical expressions to form tag
        associations</li>

      </ul>

      <ol>

      <li>Some aspects of the configuration - and their associated tags -
      are automatically deduced from some standard environment
      variables that the user is expected to specify (typically using
      shell commands):<p></p>

      <p></p>
      <ul>

        <li><tt>CMTCONFIG</tt> describes the current settings for producing
        binary objects. One default value is provided automatically by
        CMT, but generally project will override it to apply specific
        conventions.

	<cmt:blockquote>The default value is computed by CMT in the
	${CMTROOT}/mgr/cmt_system.sh shell script.

          <p>This script automatically builds a value characterizing
          both the machine type and the opebrating system type (using a
          mixing of the <tt>uname</tt> standard <tt>UNIX</tt> command with
          various operating system specific definitions such as the
          <tt>AFS</tt> based <tt>fs sysname</tt> command)</p>
	</cmt:blockquote><p></p></li>

        <li><tt>CMTSITE</tt> characterizes the current site. Its syntax is
        completely free<p></p></li>

	<li><tt>CMTEXTRATAGS</tt> may contain a space-separated list of
	additional tags to systematically activate</li>

      </ul>
      <p></p>

      <cmt:blockquote><i>Note that the <tt>CMTBIN</tt> variable which
      represents the current binary installation of CMT itself does
      NOT correspond to any tag.</i></cmt:blockquote>

      <p></p>
      </li>

      <li>
      Some aspects of the configuration represents the implicit
      knowledge CMT gets of the current context:

      <p></p>
      <ul>

        <li>The value given by the <i>uname</i> standard Unix facility
        is always a valid configuration tag. (eg. <tt>Linux</tt>)</li>

	<li>The current major version id of CMT is a valid tag and
	takes the form <tt>CMTv&lt;n&gt;</tt> (eg. <tt>&CMTvTag;</tt>)</li>

	<li>The current minor version id of CMT is a valid tag and
	takes the form <tt>CMTr&lt;n&gt;</tt> (eg. <tt>&CMTrTag;</tt>)</li>

	<li>The current patch id of CMT is a valid tag and takes the
	form <tt>CMTp&lt;n&gt;</tt> (eg. <tt>CMTp20030616</tt>)</li>

        <li> The current sub-project to which the current package
        belongs, and the various tags automatically generated by CMT
        to qualify the strategy options.</li>

        <li> The current hardware understood as filled in the
        <tt>cmt_hardware</tt> macro</li>

        <li> The current OS understood as filled in the
        <tt>cmt_system_version</tt> macro</li>

        <li> The version of the C++ compiler understood as filled in
        the <tt>cmt_compiler_version</tt> macro</li>

      </ul>

      <p></p>
      </li>

      <li>
        During a <tt>make</tt> session, each individual target being
        rebuilt may define its own context, when the
        <tt>-target_tag</tt> is set to the associated constituent, and
        this is materialized with a dedicated tag named
        <tt>target_&lt;constituent&gt;</tt>.

        <p>For instance, a package defines a library <tt>A</tt> and an
        application <tt>P</tt>, both in the default group. Both
        constituents have their <tt>-target_tag</tt> option set. Thus,
        when the standard <tt>make</tt> command is run, then those two
        targets will be rebuilt successively (eg <tt>A</tt> then
        <tt>B</tt>). Then, during the build of <tt>A</tt> (and only
        then) the tag named <tt>target_A</tt> will be active and
        during the build of <tt>B</tt>, the tag named
        <tt>target_B</tt>will in turn be active.</p>

        <cmt:cmtcode>
library A -target_tag A.cxx
application P -target_tag P.cxx

macro_append cppflags "" target_A "-DA" target_P "-DP"</cmt:cmtcode>

      <p></p>
      </li>

      <li>
        During the execution of an 
        <a href="#actions"><tt>action</tt></a>, a specific context is
        created, which is materialized with a dedicated tag named
        <tt>target_&lt;action&gt;</tt>, very similarly to the target
        tags for constituents.

      <p></p>
      </li>

      <li>
      User defined tags can be explicitly or implicitly activated:

      <p></p>
      <ul>

        <li>explicitly from the <tt>cmt</tt> command line, using the
        <tt>-tag=&lt;tag-list&gt;</tt> option </li>

	<li>explictly from requirements files using the <tt>apply_tag
	&lt;tag&gt;</tt> syntax</li>

	<li> implicitly from requirements files using the tag
	association syntax, when a tag is associated with an otherwise
	activated tag. One example is the <tt>Unix</tt> tag associated
	by CMT itself with most Unix variants </li>

      </ul>
      </li>

      </ol>

      The minimal tag set available from CMT can be visualized as
      follows (note that the exact output will obviously not
      necessarily be the one presented in this document according to
      the context effectively used):

      <cmt:code>
&gt; cd ${CMTROOT}
&gt; cmt show tags
<i><font face="courier new, courier" COLOR="#000077">&CMTvTag; (from CMTVERSION)                                                   [1]
&CMTrTag; (from CMTVERSION) package CMT implies [CMTr14]                     [1]
CMTp20040701 (from CMTVERSION)                                            [1]
Linux (from uname) package CMT implies [Unix]                             [2]
i686-rh73-gcc32-opt (from CMTCONFIG)                                      [3]
CERN (from CMTSITE)                                                       [4]
CMT_prototypes (from PROJECT) excludes [CMT_no_prototypes]                [5]
CMT_with_installarea (from PROJECT) excludes [CMT_without_installarea]
CMT_setup_config (from PROJECT) excludes [CMT_setup_no_config]
CMT_setup_root (from PROJECT) excludes [CMT_setup_no_root]
CMT_setup_cleanup (from PROJECT) excludes [CMT_setup_no_cleanup]
CMTr14 (from package CMT)
i686 (from package CMT)                                                   [6]
rh73 (from package CMT)                                                   [7]
gcc32 (from package CMT)                                                  [8]
Unix (from package CMT) excludes [WIN32 Win32]                            [9]</font></i></cmt:code>


      <ol>

        <li>Implicit tags deduced from the current version of CMT</li>
        <li>Implicit tag obtained from the uname command (note that there is an associated tag defined here)</li>
        <li>The current value of CMTCONFIG</li>
        <li>The current value of CMTSITE</li>
        <li>The strategy tags</li>
        <li>Automatic detection of the hardware</li>
        <li>Automatic detection of the current OS</li>
        <li>Automatic detection of the C++ compiler version</li>
        <li>A indirectly activated tag (associated with another active tag)</li>

      </ol>

    </cmt:section>

    <cmt:section title="Defining the user tags">

      <p>The user configuration tags can generally be specified though
      various complementary mechanisms:</p>

      <ul>

        <li>CMTSITE and CMTCONFIG can be specified using standard
        shell commands (setenv, export, set)</li>

        <cmt:code>
sh&gt; export CMTSITE=CERN</cmt:code>

        <p></p>

        <li>CMTSITE and CMTCONFIG can alternatively be specified using
        the <tt>set</tt> statement in a requirements file</li>

        <cmt:cmtcode>
set CMTSITE "CERN"
set CMTCONFIG "${CMTBIN}" sun "Solaris-CC-dbg"</cmt:cmtcode>

        <p></p>

        <li> Additional tags may also be associated with other tags,
        using the <tt>tag</tt> statement (in a requirements file):

          <cmt:cmtcode>
tag newtag tag1 tag2 tag3</cmt:cmtcode>

          which means that:

          <ul>

            <li><tt>newtag</tt> defines a tag (inactive by default)</li>

            <li>when <tt>newtag</tt> is active, then both tag1, tag2 and
            tag3 are simultaneously active</li>

          </ul>
        </li>

        <p></p>

        <li>
	Tags may be declared as <i>exclusive</i> using the <tt>tag_exclude</tt> syntax.

          <cmt:cmtcode>
tag_exclude debug optimized</cmt:cmtcode>

	  This example implies that the two tags <tt>debug</tt> and
	  <tt>optimized</tt> should never become active simultaneously.

	</li>

        <p></p>

        <li>
	Tags are assigned priorities according to the way they have
	been defined. The priority is particularly useful for
	specifying exclusion. The tag association promotes the
	priority of the associated tags to the priority of the
	defining tag.

	The following decreasing priorities are currently defined by
	CMT:

	<p></p>

	<ol>

	  <li>tag specified in the command line using the -tag=&lt;tag-list&gt; option</li>
	  <li>tag deduced from CMTCONFIG</li>
	  <li>tag defined in a requirements file using the <tt>tag</tt> syntax</li>
	  <li>tag deduced from CMTSITE</li>
	  <li>tag deduced from <i>uname</i></li>
	  <li>tags deduced from the version of CMT</li>

	</ol>

	</li>

      </ul>

    </cmt:section>

    <cmt:section title="Activating tags">

      By default, <tt>CMTCONFIG</tt>, <tt><i>uname</i></tt> and
      <tt>CMTSITE</tt> (also named system tags) are always active.

      <p>The tag associated with the current project name as well as
      those describing the strategy properties of all projects are
      also always active.</p>

      <p>The target tags associated with constituents (when the
      <tt>-target_tag</tt> option was set on them) or with actions are
      automatically activated during the build of the constituent or
      during the execution of the action.</p>

      <p>It is possible to <i>activate</i> other tags through the
      following arguments to <i>any</i> cmt command:</p>

      <ul>

        <li>
          <tt>-tag=&lt;tag-list&gt;</tt>

          <p> will cleanup the complete current tag set, and
          activate the new tags (the system tags are restored).
          </p>

        </li>

        <li>
          <tt>-tag_add=&lt;tag-list&gt;</tt>

          <p> will add to the current tag set the tags
          specified in the comma separated list </p>

        </li>

        <li>
          <tt>-tag_remove=&lt;tag-list&gt;</tt>

          <p>will remove from the current tag set the tags specified
            in the comma separated list</p>

        </li>
      </ul>

      <cmt:blockquote>

      Beware that giving these arguments generally make the selected
      tag set active only during the selected command. Therefore two
      different CMT commands run with different tag sets will
      generally yield different results.

      </cmt:blockquote>

      <p>However it's often useful to state that a given tag or tag
      set should be active. This can be obtained by the following
      mechanisms:</p>

      <ol>

        <li>
	  <i>Forcing a tag in a requirements file using the <tt>apply_tag</tt> &nbsp;syntax</i>

	  <p></p>

	  Eg the following syntax installed in a requirements file
	  will force the tag <tt>foo</tt>:

	  <cmt:cmtcode>
tag_apply foo</cmt:cmtcode>

	  <cmt:code>
&gt; cmt show tags
<i><font face="courier new, courier" COLOR="#000077">&CMTvTag; (from CMTVERSION)
&CMTrTag; (from CMTVERSION)
CMTp0 (from CMTVERSION)
Linux (from uname)
Linux-i686 (from CMTCONFIG) package CMT implies [Linux]
A (From PROJECT)
Default (from Default)
foo (from package Foo)</font></i></cmt:code>

	</li>

	<li>
	  <i>Implying a tag from another one using the tag association syntax</i>

	  <cmt:cmtcode>
tag Linux foo</cmt:cmtcode>

	  <cmt:code>
&gt; cmt show tags
<i><font face="courier new, courier" COLOR="#000077">&CMTvTag; (from CMTVERSION)
&CMTrTag; (from CMTVERSION)
CMTp0 (from CMTVERSION)
Linux (from uname) package Foo implies [foo]
Linux-i686 (from CMTCONFIG) package CMT implies [Linux]
A (From PROJECT)
Default (from Default)
foo (from package Foo)</font></i></cmt:code>

	</li>

	<li>
	  <i>Through conventionally encoded values of <tt>CMTCONFIG</tt></i>

	  <cmt:cmtcode>
tag Linux-foo Linux foo</cmt:cmtcode>

	  <cmt:code>
&gt; export CMTCONFIG=Linux-foo
&gt; cmt show tags
<i><font face="courier new, courier" COLOR="#000077">&CMTvTag; (from CMTVERSION)
&CMTrTag; (from CMTVERSION)
CMTp0 (from CMTVERSION)
Linux (from uname)
Linux-foo (from CMTCONFIG) package Foo implies [Linux foo]
A (From PROJECT)
Default (from Default)
Linux-i686 (from package CMT) package CMT implies [Linux]
foo (from package Foo)</font></i></cmt:code>

	</li> 

      </ol>

      <p>The current active tag set can always be visualized using the
      <tt>cmt show tags</tt> command.</p>

      <cmt:code>
&gt; cmt show tags
<i><font face="courier new, courier" COLOR="#000077">&CMTvTag; (from CMTVERSION)
&CMTrTag; (from CMTVERSION)
CMTp0 (from CMTVERSION)
Linux (from uname)
Linux-i686 (from CMTCONFIG) package CMT implies [Linux]
A (From PROJECT)
Default (from Default)
</font></i>
&gt; cmt -tag_add=tag1,tag2,tag3 show tags
<i><font face="courier new, courier" COLOR="#000077">&CMTvTag; (from CMTVERSION)
&CMTrTag; (from CMTVERSION)
CMTp0 (from CMTVERSION)
Linux (from uname)
Linux-i686 (from CMTCONFIG) package CMT implies [Linux]
A (From PROJECT)
tag1 (from arguments)
tag2 (from arguments)
tag3 (from arguments)
Default (from Default)</font></i></cmt:code>

      <p>Typical usages of those extra tags are:</p>

      <ul> 

        <li> when using special compiler options (e.g. optimization,
        debugging, ...)  </li>

        <li> for switching to different compilers (e.g. <tt>gcc</tt>
        versus the native compiler) </li>

        <li> when one uses a special debugging environment such as
        <tt>Insure</tt> or <tt>Purify</tt> </li>

        <li> when using special system specific features (such as
        whether one uses thread-safe algorithms or not) </li>

      </ul> 

      <p>All symbol definitions providing specific values triggered by
      the active selectors will be selected, such as in:</p>

      <cmt:cmtcode>
macro_append cppflags "" \
             debug    " -g "</cmt:cmtcode>

    </cmt:section> 

  </cmt:section> 

  <cmt:section title="Working on a package">

    <p>In this section, we'll see, through a quite simple scenario,
    the typical operations generally needed for installing, defining
    and building a package.  We are continuing the <a
    href="#Installing a new package">example</a> of the <tt>Foo</tt>
    package already used in this document. </p>

    <cmt:section title="Working on a library">

      <p>Let's assume, as a first example, that the <tt>Foo</tt> package
      <i>is</i> originally composed of one library <tt>libFoo.a</tt>
      itself made from two sources : <tt>FooA.c</tt> and
      <tt>FooB.c</tt>. A shared flavour of the library <tt>libFoo.so</tt>
      or <tt>libFoo.sl</tt> or <tt>libFoo.dll</tt>) is also foreseen.</p>

      <p> The minimal set of branches provided by <tt>CMT</tt> (once the
      <tt>cmt create</tt> operation has been performed) for a package
      includes <tt>src</tt> for the sources and <tt>cmt</tt> for the
      <i>Makefiles</i> and other scripts.</p>

      <p> The various tools <tt>CMT</tt> provide will be fully exploited
      if one respects the roles these branches have to play. However
      it is always possible to extend the default understanding
      <tt>CMT</tt> gets on the package by appropriate modifiers
      (typically by overriding <a href="#Standard macros predefined in CMT">standard</a> macros). </p>

      <p> Assuming the conventional usage is selected, the steps
      described in this section can be undertaken in order to actually
      develop a software package. </p>

      <p> We first have to create the two source files into the
      <tt>src</tt> branch (typically using our favourite text
      editor). Then a description of the expected library (ie. built
      from these two source files) will be entered into the
      <tt>requirements</tt> file. The minimal syntax required in our
      example will be :</p>

      <cmt:code>
csh&gt; cd ../cmt
csh&gt; vi requirements             (1)
library Foo FooA.cxx FooB.cxx</cmt:code>

      <ol> 

        <li> the <tt>&CMTrequirements;</tt> 
        file located in the <tt>cmt</tt>
        branch of the package receives the description of this
        <i>library</i> component. This is done using one
        <tt>library</tt> statement.  </li>

      </ol> 

      <p>The <tt>cmt create</tt> command had generated a simple
      <i>Makefile</i> (or <tt>NMake</tt> file) which is generaly
      sufficient for all standard operations, since <tt>CMT</tt>
      continuously and transparently manages the automatic
      reconstruction of all intermediate makefile fragments. We
      therefore simply and immediately execute gmake as follows:</p>

      <cmt:code>
...v1/cmt&gt; gmake QUIET=1
<i><font face="courier new, courier" COLOR="#000077">------> (Makefile.header) Rebuilding constituents.make
------> (constituents.make) Rebuilding setup.make Linux-i686.make         [1]
setup.make ok
------> (constituents.make) Rebuilding library links
------> (constituents.make) all done
------> (constituents.make) Building Foo.make                             [2]
Library Foo
------> (constituents.make) Starting Foo
------> (Foo.make) Rebuilding ../Linux-i686/Foo_dependencies.make         [3]
rebuilding ../Linux-i686/FooA.o
rebuilding ../Linux-i686/FooB.o
rebuilding library
------> Foo : library ok
------> Foo ok
Installing library libFoo.so into /home/arnault/mydev/InstallArea/Linux-i686/lib
installation done                                                         [4]
------> (constituents.make) Foo done
 all ok.
Linux-i686.make ok
gmake[2]: `config' is up to date.
gmake[2]: `all' is up to date.</font></i></cmt:code>

      <ol> 

        <li> Some intermediate makefile fragments are automatically
        built to reflect the current effective set of Makefile macros
        deduced from the configuration (read from the <tt>
        &CMTrequirements;</tt> file). These fragments are automatically
        rebuilt (if needed) each time one of the
        <tt>&CMTrequirements;</tt> file changes.  </li>

        <li> Each component of the package (be it a particular
        <i>library</i> or a particular <i>executable</i>) will have
        its own <i>makefile</i> fragment (named
        <tt>../${CMTCONFIG}/&lt;name&gt;.[n]mak[e]</tt>). This dedicated
        <i>makefile</i> takes care of filling up the library and
        creating the shared library (on the systems where this is
        possible).  </li>

        <li> The directory which is used for the binaries (i.e. the
        results of compilation or the libraries) has been
        automatically created by a generic target (<tt>dirs</tt>)
        which is defined within <tt>[N]Makefile.header</tt>. A new
        binary directory will be created each time a new value of the
        <tt>CMTCONFIG</tt> environment variable is defined or a
        <i>tag</i> is provided on the command line to <tt>make</tt>.
        </li>

        <li> An automatic installation mechanism is applied for all
        successfully built binaries. </li>

      </ol>

      or, for nmake:

      <cmt:code>
...v1/cmt&gt; nmake /f nmake </cmt:code>

      <p>This mechanism relies on some conventional <i>macros</i> and
      incremental <i>targets</i> used within the specific
      makefiles. Some are automatically generated, some have to be
      specified in user packages. It's quite important to understand
      the list of possible customization macros, since this is the
      main communication medium between <tt>CMT</tt> and the package
      manager. See the complete 
      <a href="#Standard macros predefined in CMT">table</a> 
      of those conventional macro when you want to
      interact with the standard CMT behaviour.  </p>

      <p>However, it is also possibble to use a simplified and
      platform independent form to build a constituent</p>

      <cmt:code>
...v1/cmt&gt; cmt make </cmt:code>

      <p>This syntax is identical on all platforms, and also does not
      require any <tt>cmt config</tt> nor <tt>source setup</tt>
      operation</p>

    </cmt:section> 

    <cmt:section title="Working on an application">

      <p>Assume we now want to add a test program to our
      development. Then we create a <tt>FooTest.cxx</tt> source, and
      generate the associated makefile (specifying that it will be an
      executable instead of a library) : </p>

      <cmt:code>
csh&gt; cd ../src 
csh&gt; emacs FooTest.cxx
... 
csh&gt; cd ../cmt 
csh&gt; vi requirements 
... 
application FooTest FooTest.cxx</cmt:code>

      So that we may simply build the complete stuff by running : 

      <cmt:code>
&gt; cmt make QUIET=1
<i><font face="courier new, courier" COLOR="#000077">------> (Makefile.header) Rebuilding constituents.make
------> (constituents.make) Rebuilding setup.make Linux-i686.make
setup.make ok
------> (constituents.make) Rebuilding library links
------> (constituents.make) all done
------> (constituents.make) Building Foo.make
Library Foo
------> (constituents.make) Starting Foo
------> Foo : library ok
------> Foo ok
installation done
------> (constituents.make) Foo done
------> (constituents.make) Building FooTest.make
Application FooTest
------> (constituents.make) Starting FooTest
------> (FooTest.make) Rebuilding ../Linux-i686/FooTest_dependencies.make
rebuilding ../Linux-i686/FooTest.o
rebuilding ../Linux-i686/FooTest.exe
------> FooTest ok
Installing application FooTest.exe into /home/arnault/mydev/InstallArea/Linux-i686/bin
installation done
------> (constituents.make) FooTest done
 all ok.
Linux-i686.make ok
gmake[2]: `config' is up to date.
gmake[2]: `all' is up to date.</font></i></cmt:code>

      Which shows that a program <tt>FooTest.exe</tt> has been built
      from our sources. Assuming now that this program needs to access
      the <tt>Foo</tt> library, we'll just add the following definition
      in the <tt>&CMTrequirements;</tt>
      file :

      <cmt:cmtcode>
... 
macro Foo_linkopts " -lFoo " \
      WIN32        " $(FOOROOT)/$(Foo_tag)/Foo.lib "
... </cmt:cmtcode>

      <p>The <tt>Foo_linkopts</tt> conventional macro will be automatically
      inserted within the <tt>use_linkopts</tt> macro. And the shared
      library location will be automatically set to the installation
      areas.</p>

      <p>It is also possible to select extra tag sets when running
      gmake as follows (in this example we first cleanup the previous
      build and rebuild with debug options added to the compiler and
      linker commands) :</p>

      <cmt:code>
&gt; cmt make clean
&gt; cmt make CMTEXTRATAGS=debug</cmt:code>

      <p> Like all other make macros used to build a component, the
      <tt>Foo_linkopts</tt> will be specified within the
      <tt>&CMTrequirements;</tt> which gives several benefits: </p>

      <ul> 

        <li> variants of the macro definition can be provided </li>

        <li> monitoring features of <tt>CMT</tt> such as the <tt>cmt show
        macro Foo_linkopts</tt> command can be used later on </li>

        <li> macros defined this way may be later on inherited by
        client packages which will <i>use</i> our package.  </li>

      </ul> 

    </cmt:section> 

    <cmt:section title="Working on a test or external application">

      It is also possible to work on a <i>test</i> or <i>external</i>
      application, ie. when one does not wish to configure the
      development for this application using <tt>CMT</tt>. Even in this
      case, it is possible to benefit from the packages configured
      using <tt>CMT</tt> by partially using <tt>CMT</tt>, just for
      <i>used</i> relationships.

      <p> Here, no special convention is assumed on the location of
      the sources, the binaries, the management scripts,
      etc... However, it is possible to describe in a <tt>
      &CMTrequirements;</tt> file the <i>use</i> relationships, as well
      as the <tt>make</tt> macro definitions, quite similarly to the
      package entirely configured using <tt>CMT</tt>. </p>

      <p> Most of the options provided by the <tt>cmt</tt> user
      interface are still available in these conditions. </p>

    </cmt:section> 

  </cmt:section>

  <cmt:section title="Defining a document generator">

    <p> In a Unix environment, documents are built using <tt>make</tt>
    (well generally its <i>gnu</i> flavour) or <tt>nmake</tt> in Windows
    environments. The basic mechanism provided in <tt>CMT</tt> relies on
    <i>make fragment patterns</i> containing instructions on how to
    rebuild document pieces. Many such generators are provided by
    <tt>CMT</tt> itself so as to take care of of the most usual cases
    (e.g. compilations, link operations, archive manipulations,
    etc...). In addition to those, any package has to possibility to
    provide a new generator for its own purpose, i.e. either for
    providing rules for a special kind of document, or even to
    override the default ones provided by <tt>CMT</tt>. This mechanism
    is very similar to the definition or re-definition of
    <i>macros</i> or environment variables in that every new generator
    has to be first declared in a <tt> &CMTrequirements;</tt> file
    belonging to a package (<tt>CMT</tt> actually declares all its
    default generators within its <tt>&CMTrequirements;</tt> file),
    allowing all its client packages to transparently acquire the
    capacity to generate documents of that sort.  </p>

    <p> <tt>CMT</tt> manages two categories of constituents:

      <ol>

        <li><i>Applications</i> and <i>Libraries</i> are handled using
        pre-defined make fragments (mainly related with languages) and
        behaviour.  </li>

        <li><i>Documents</i> offer a quite general framework for
        introducing completely new behaviours through user-defined
        make fragments. This includes actually generating documents,
        but also simply performing an operation (in which case
        sometimes no real <i>document</i> is produced).  </li>

      </ol>
    </p>

    <p> In this section we only discuss the latter category and the
    following paragraphs explain the framework used for defining new
    document types.  </p>

    <p>The main concept of this framework is that each document to be
    generated or manipulated must be associated with a "document-type"
    (also sometimes named "document-style"), which corresponds to a
    dedicated make fragment of that name. Then, when specified in a
    <tt>document</tt> statement, this make fragment will be
    <i>instanciated</i> once or several times (typically once per
    source file) to construct a complete and functional make fragment,
    containing one main target. Both the resulting make fragment and
    the make target will have the name of the constituent.</p>

    <cmt:section title="An example : the tex document-style">

      <p>

        <cmt:blockquote> <i>This section discusses one simple example (the
        production of postscript from latex files) available in the
        standard <tt>CMT</tt> distribution kit.  </i> </cmt:blockquote>

      </p>

      <p>Converting a latex source file into a postcript output
      implies to chain two text processors, with an intermediate dvi
      format.</p>

      <p>The fragment described here exactly performs this sequence,
      taking care of intermediate file deletion. The document style is
      named "tex" (the associated fragment shown here and named "tex"
      is actually provided by <tt>CMT</tt> itself, and can be looked at
      in <tt>${CMTROOT}/fragments/tex</tt>.) :</p>

      <cmt:cmtcode>
============ tex ===================================== 
${CONSTITUENT} :: ${FILEPATH}/${NAME}.ps

${FILEPATH}/${NAME}.dvi : ${FULLNAME} 
	cd ${doc}; latex ${FULLNAME} 

${FILEPATH}/${NAME}.ps : ${FILEPATH}/${NAME}.dvi 
	cd ${doc}; dvips ${FILEPATH}/${NAME}.dvi 

${CONSTITUENT}clean ::
	cd $(doc); /bin/rm -f ${FILEPATH}/${NAME}.ps ${FILEPATH}/${NAME}.dvi

====================================================== </cmt:cmtcode>

      <ul> 

        <li> They are declared in the <tt>CMT</tt>'s <a HREF="#The
        requirements file">requirements</a> file as follows :

          <cmt:cmtcode>
make_fragment tex -header=tex_header</cmt:cmtcode>

          where: 

          <ol> 

            <p></p>

            <li> "tex" represents both the fragment name and the document style. </li>

            <p></p>

            <li>the <tt>-header=tex_header</tt> option indicates that
            the generated makefile fragment will first include this
            header (which is actually an empty file in this case)</li>

            <p></p>

          </ol> 

        </li>

        <li> A user package willing to apply this behaviour will have
        to include in its &CMTrequirements; file a statement similar
        to the following:

          <cmt:cmtcode>
document tex MyDoc -s=../doc doc1.tex doc2.tex </cmt:cmtcode>

          where: 

          <ol> 

            <li> The first parameter "tex" is the document-style </li>

            <li> The second parameter "MyDoc" is used for building the
            constituent's makefile (under the name MyDoc.make) and for
            providing the make target "MyDoc". </li>

            <li> The other parameters (doc1.tex and doc2.tex) are the
            sources of the document. Explicit location is required
            (since default is currently defined to be ../src) </li>

            <li> The constituent's makefile MyDoc.make is built as
            follows :

              <ol> 

                <li> Install a copy of the
                <tt>$CMTROOT/fragments/make_header</tt> generic fragment
                </li>

                <li> Install a copy of the <tt>$CMTROOT/fragments/tex_header</tt> fragment </li>

                <li> For each of the sources, install a copy of the fragment "tex"</li> 

                <li> Install a copy of the <tt>$CMTROOT/fragments/cleanup_header</tt> fragment </li>

              </ol> 

            </li>            

          </ol> 

          <p>The result for our example is: </p>

          <cmt:cmtcode>
=========== MyDoc.make =============================== 

#==================================== 
#  Document MyDoc 
# 
#   Generated   by  
# 
#==================================== 

help :: 
@echo 'MyDoc' 

doc1_dependencies = ../doc/doc1.tex 
doc2_dependencies = ../doc/doc2.tex 

MyDoc :: ../doc/doc1.ps 

../doc/doc1.dvi : $(doc)doc1.tex 
	cd ${doc}; latex $(doc)doc1.tex 

../doc/doc1.ps : ../doc/doc1.dvi 
	cd ${doc}; dvips ../doc/doc1.dvi 

MyDocclean ::
	cd $(doc); /bin/rm -f ../doc/doc1.ps ../doc/doc1.dvi

MyDoc :: ../doc/doc2.ps 

../doc/doc2.dvi : $(doc)doc2.tex 
	cd ${doc}; latex $(doc)doc2.tex 

../doc/doc2.ps : ../doc/doc2.dvi 
	cd ${doc}; dvips ../doc/doc2.dvi 

MyDocclean ::
	cd $(doc); /bin/rm -f ../doc/doc2.ps ../doc/doc2.dvi

clean :: MyDocclean 
	cd . 

MyDocclean :: 
====================================================== </cmt:cmtcode>
        </li>
      </ul> 

    </cmt:section> 

    <cmt:section title="How to create and install a new document style">

      <p><cmt:blockquote><i>This section presents the general framework
      for designing a document generator.</i></cmt:blockquote></p>

      <ol> 

        <li> Select a name for the document style. It should not clash
        with existing ones (use the <tt>cmt show fragments</tt> for a
        complete list of document types currently defined).</li>

        <p></p>

        <li> A fragment exactly named after the document style name
        must be installed into a subdirectory named <tt>fragments</tt>
        below the <tt>cmt</tt> branch of a given package (which becomes
        the <i>provider</i> package).</li>

        <p></p>

        <li> Optionally, two other fragments may be installed into the
        same subdirectory, one of them will be the <i>header</i> of
        the generated complete fragment, the other will be its
        <i>trailer</i></li>

        <p></p>

        <li> Those fragments <i>must</i> be declared in the
        &CMTrequirements; file of the provider package as follows:

          <cmt:cmtcode>
make_fragment &lt;fragment-name&gt; [ options... ] </cmt:cmtcode>

          where options may be : 

          <p>

            <table BORDER='1' COLS='2'> 
                  <tr> 
                    <td><tt>-suffix=&lt;suffix&gt;</tt></td> 
                    <td width="500">provide the suffix of the output files (without the dot)</td> 
                  </tr> 
                  <tr> 
                    <td><tt>-header=&lt;header&gt;</tt></td> 
                    <td>provide another make fragment meant to be prepended to 
                      the constituent's make fragment.</td> 
                  </tr> 
                  <tr> 
                    <td><tt>-trailer=&lt;trailer&gt;</tt></td> 
                    <td>provide another make fragment meant to be
                      appended to the constituent's make fragment.</td> 
                  </tr> 
                  <tr> 
                    <td><tt>-dependencies</tt></td> 
                    <td>install the automatic generation of dependencies into the 
                      constituent's make fragment</td> 
                  </tr> 
            </table> 
          </p>
        </li>
      </ol> 

      <p>Once a fragment is installed and declared, it may be used by
      any <i>client</i> package (ie a package <i>using</i> the
      provider), and queried upon using the command</p>

      <cmt:code>
&gt; cmt show fragment &lt;fragment name&gt; </cmt:code>

      <p>which will show where this fragment is defined (ie. in which
      of the used packages).</p>

      <p>The <tt>cmt show fragments</tt> commands lists all declared
      fragments. </p>

      <p>If a package re-defines an already declared make fragment, ie
      it provides a new copy of the fragment (possibly with new copies
      of the header and the trailer), and declares it inside its
      requirements file, then this package becomes the new provider
      for the document style.</p>

      <p>For building a fragment, one may use pre-defined generic
      "templates" (which will be substituted when a fragment is copied
      into the final constituent's makefile).</p>

      <p>
        <center> 
          <table BORDER='1' COLS='2'> 

                <tr>
                  <td width="100"><tt>CONSTITUENT</tt></td>
                  <td width="400">the constituent name</td>
                </tr> 
                <tr>
                  <td><tt>CONSTITUENTSUFFIX</tt></td>
                  <td>the optional constituent's output suffix</td>
                </tr>              
                <tr>
                  <td><tt>FULLNAME</tt></td>
                  <td>the full source path name (including directory and suffix)</td>
                </tr> 
                <tr>
                  <td><tt>FILENAME</tt></td>
                  <td>the complete source file name (only including the suffix)</td>
                </tr> 
                <tr>
                  <td><tt>NAME</tt></td>
                  <td>the short source file name (without directory and suffix)</td>
                </tr> 
                <tr>
                  <td><tt>FILEPATH</tt></td>
                  <td>the source directory</td>
                </tr> 

                <tr>
                  <td><tt>SUFFIX</tt></td>
                  <td>the suffix provided in the -suffix option</td>
                </tr> 

                <tr>
                  <td><tt>OBJS</tt></td>
                  <td>(only available in headers) the list of
                    outputs, formed by a set of expressions :

		    <cmt:code>
$(${CONSTITUENT}_output)${NAME}${SUFFIX} </cmt:code>

                  </td>
                </tr> 

          </table> 
        </center> 
      </p>

      <p>Templates must be enclosed between <tt>${</tt> and <tt>}</tt> or between <tt>$(</tt> and
      <tt>)</tt> and will be substituted at the generation time. Thus, if a
      fragment contains the following text : </p>

      <cmt:code>
$(${CONSTITUENT}_output)${NAME}${SUFFIX}</cmt:code>

      <p>then, the expanded constituent's makefile will contain
      (refering to the "tex" example)</p>

      <cmt:code>
$(MyDoc_output)doc1.ps </cmt:code>

      <p>Which shows that make macros may be dynamically generated. </p>

      <cmt:image src="Images/DocumentGenerator.jpg" 
                 caption="The architecture of document generation."/>

    </cmt:section> 

    <cmt:section title="Examples">

      <ol> 

        <li> rootcint 

          <p>It generates C++ hubs for the Cint interpreter in Root. </p>

          <cmt:cmtcode>
========= rootcint ========================================= 
$(src)${NAME}.cc :: ${FULLNAME}   
	${rootcint} -f $(src)${NAME}.cc -c ${FULLNAME} 
============================================================ </cmt:cmtcode>
        </li>

        <li> agetocxx and agetocxx_header. 

          <p>It generates C++ source files (xxx.g files) from Atlas' AGE 
            description files. </p>

          <cmt:cmtcode>
========= agetocxx ========================================= 
output=$(${CONSTITUENT}_output) 

$(output)${NAME}.cxx : $(${NAME}_cxx_dependencies) 
	(echo '#line 1 "${FULLNAME}"'; cat ${FULLNAME}) > /tmp/${NAME}.gh.c 
	gcc -E -I$(output) $(use_includes) -D_GNU_SOURCE \ 
	  cd ${output}; $(agetocxx) -o ${NAME} -ohd ${FILEPATH} \
	  -ohp ${FILEPATH} /tmp/${NAME}.gh 
	rm -f /tmp/${NAME}.gh /tmp/${NAME}.gh.c 
	cd $(bin); $(cppcomp) $(use_cppflags) $(${CONSTITUENT}_cppflags) \
	  $(${NAME}_cppflags) ${ADDINCLUDE} $(output)${NAME}.cxx 
	cd $(bin); $(ar) $(${CONSTITUENT}lib) ${NAME}.o; /bin/rm -f ${NAME}.o 
============================================================ </cmt:cmtcode>

          <cmt:cmtcode>
========= agetocxx_header ================================== 
${CONSTITUENT}lib       = $(bin)lib${CONSTITUENT}.a 
${CONSTITUENT}stamp     = $(bin)${CONSTITUENT}.stamp 
${CONSTITUENT}shstamp   = $(bin)${CONSTITUENT}.shstamp 

${CONSTITUENT} :: dirs ${CONSTITUENT}LIB 
	@/bin/echo ${CONSTITUENT} ok 

${CONSTITUENT}LIB :: $(${CONSTITUENT}lib) $(${CONSTITUENT}shstamp) 
	@/bin/echo ${CONSTITUENT} : library ok 

$(${CONSTITUENT}lib) $(${CONSTITUENT}stamp) :: ${OBJS} 
	$(ranlib) $(${CONSTITUENT}lib) 
	cat /dev/null &gt;$(${CONSTITUENT}stamp) 

$(${CONSTITUENT}shstamp) :: $(${CONSTITUENT}stamp) 
	cd $(bin); $(make_shlib) $(tag) ${CONSTITUENT} \
	  $(${CONSTITUENT}shlibflags); \
	  cat /dev/null &gt;$(${CONSTITUENT}shstamp) 

============================================================ </cmt:cmtcode>

          It must be declared as follows : 

          <cmt:cmtcode>
make_fragment agetocxx -suffix=cxx -dependencies -header=agetocxx_header </cmt:cmtcode>

        </li>
      </ol> 

    </cmt:section> 

  </cmt:section>

  <cmt:section title="The tools provided by CMT">


        The set of conventions and tools provided by <tt>CMT</tt> is 
        mainly composed of : 

        <ul> 
          <li> 
            the syntax of the <tt>&CMTrequirements;</tt> file, 
          </li> 
          <li> 
            and the general <tt>cmt</tt> user interface, available in 
            the <tt>mgr</tt> branch of the <tt>CMT</tt> package. 
          </li> 
        </ul> 

        The <i>setup</i> script found in the <tt>CMT</tt> installation
        directory actually adds its location to the definition of the
        standard <tt>UNIX</tt> <tt>PATH</tt> environment variable in order to
        give direct access to the main <tt>cmt</tt> user interface.

        <p> 
          The sections below will detail the complete syntax of the 
          <tt>&CMTrequirements;</tt> file since it is the basis of most 
          information required to run the tools as well as the main 
          commands available through the <tt>cmt</tt> user interface. </p>

        <cmt:section title="The requirements file">

          <cmt:section title="The general requirements syntax">

            <ul>
              <li>
                A requirements file is made of <i>statements</i>, each describing
                one named configuration parameter.

                <p>Statements generally occupy one single line, but may be
                  split into several lines using the reverse-slash character
                  (in this case the reverse-slash character <i>must</i> be
                  the last character on the line or must be only followed
                  by space characters).</p>

                <p>Each statement is composed of words separated with spaces
                  or tabulations.</p>

                <p>The first word of a statement is the name of the
                  configuration parameter.</p>

                <p>The rest of the statement provides the value assigned
                  to the configuration parameter.</p>

              </li>

              <li>
                <p>Words composing a statement are separated with space or
                  tab characters. They may also be enclosed in quotes when
                  they have to include space or tab characters. Single or
                  double quotes may be freely used, as long as the same type
                  of quote is used on both sides of the word.</p>

                  <p>Special characters (tabs, carriage-return and
                    line-feed) may be inserted into the statements using an
                    XML-based convention:</p>

                    <center>
                      <table cols='2'>

                        <tr>
                          <td>
                            <tt>tabulation</tt>
                          </td>
                          <td>
                            <tt><tt>&lt;cmt:tab/&gt;</tt></tt>
                          </td>
                        </tr>

                        <tr>
                          <td>
                            <tt>carriage-return</tt>
                          </td>
                          <td>
                            <tt><tt>&lt;cmt:cr/&gt;</tt></tt>
                          </td>
                        </tr>

                        <tr>
                          <td>
                            <tt>line-feed</tt>
                          </td>
                          <td>
                            <tt><tt>&lt;cmt:lf/&gt;</tt></tt>
                          </td>
                        </tr>

                      </table>
                    </center>
                    <p></p>
              </li>

              <li> 
                <p>Comments : they start with the <tt>#</tt> character and 
                  extend up to the end of the current line. 
                  </p> 
              </li>

            </ul>

	    The complete  syntax specification is available in <a href="#The complete requirements syntax">Appendix</a>.

          </cmt:section> 

        </cmt:section>

        <cmt:section title="The concepts handled in the requirements file">

          <cmt:section title="The package structuring style ">

          </cmt:section>

          <cmt:section title="Meta-information : author, manager">

            The author and manager names 

          </cmt:section>

          <cmt:section title="package, version">

            The package name and version. These statements are purely
            informational.

          </cmt:section>

          <cmt:section title="Constituents : application, library, document">

            <p>Describe the composition of a constituent. Application
            and library correspond to the standard meaning of an
            application (an executable) and a library, while document
            provides for a quite generic and open mechanism for
            describing any type of document that can be generated from
            sources.</p>

            <p>Applications and libraries are assigned a name (which
            will correspond to a generated make fragment, and a
            dedicated make target).</p>

            <p>A document is first associated with a document type
            (which must correspond to a previously declared make
            fragment). The document name is then used to name a
            dedicated make fragment and a make target.</p>

            <p>Various options can be used when declaring a
            constituent:</p>

            <center>
              <table border='1' cols='3'>

                <tr>
                  <td width="250"><center><i>option</i></center></td>
                  <td width="150"><center><i>validity</i></center></td>
                  <td width="300"><center><i>usage</i></center></td>
                </tr>

                <tr>
                  <td><tt>-s=<i>directory</i></tt></td>
                  <td>any</td>
                  <td>switch to a new default directory <a href="#source selection and exclusion"><tt>(1)</tt></a></td>
                </tr>

                <tr>
                  <td><tt>-x=<i>regexp</i></tt></td>
                  <td>any</td>
                  <td>specify an exclusion regular expression to be applied to the sources <a href="#source selection and exclusion"><tt>(1)</tt></a></td>
                </tr>

                <tr>
                  <td><tt>-k=<i>regexp</i></tt></td>
                  <td>any</td>
                  <td>specify a finer selection regular expression to be applied to the sources <a href="#source selection and exclusion"><tt>(1)</tt></a></td>
                </tr>

                <tr>
                  <td><tt>-no_share</tt></td>
                  <td>libraries</td>
                  <td>do not generate the shared library</td>
                </tr>

                <tr>
                  <td><tt>-no_static</tt></td>
                  <td>libraries</td>
                  <td>do not generate the static library (<i>not yet implemented</i>)</td>
                </tr>

                <tr>
                  <td><tt>-prototypes</tt></td>
                  <td>applications, libraries</td>
                  <td>do generate the prototype header files</td>
                </tr>

                <tr>
                  <td><tt>-no_prototypes</tt></td>
                  <td>applications, libraries</td>
                  <td>do not generate the prototype header files</td>
                </tr>

                <tr>
                  <td><tt>-check</tt></td>
                  <td>applications</td>
                  <td>generate a check target meant to execute the rebuilt application</td>
                </tr>

                <tr>
                  <td><tt>-group=&lt;group-name&gt;</tt></td>
                  <td>any</td>
                  <td>install the constituent within this group target</td>
                </tr>

                <tr>
                  <td><tt>-suffix=&lt;suffix&gt;</tt></td>
                  <td>applications, libraries</td>
                  <td>provide a suffix to names of all object files generated for this constituent <a href="#suffix option"><tt>(2)</tt></a></td>
                </tr>

                <tr>
                  <td><tt>-import=&lt;package&gt;</tt></td>
                  <td>applications, libraries</td>
                  <td>explicitly import for this constituent the standard macros from a package that has the <tt>-no_auto_imports</tt> option set</td>
                </tr>

                <tr>
                  <td><tt>-target_tag</tt></td>
                  <td>any</td>
                  <td>construct a specific tag named
                  <tt>target_&lt;constituent&gt;</tt>. This tag will
                  only be active during the make session for this
                  constituent. <a href="#the target tag option"><tt>(4)</tt></a></td>
                </tr>

                <tr>
                  <td><tt>-windows</tt></td>
                  <td>applications</td>
                  <td>When used in a Windows environment, generates a GUI-based application (rather than a console application) </td>
                </tr>

                <tr>
                  <td><tt>&lt;var-name&gt;=&lt;var-value&gt;</tt></td>
                  <td>any</td>
                  <td>define a variable and its value to be given to the make fragment <a href="#variable-name option"><tt>(3)</tt></a></td>
                </tr>

              </table>
            </center>

            <ol>

              <li><a name="source selection and exclusion"></a>

                <p>The sources of the constituents are generally
                specified as a set of file names with their suffixes,
                and are by default expected from the <tt>../src</tt>
                directory</p>

                <cmt:cmtcode>
library A A.cxx B.cxx</cmt:cmtcode>

                <p>Then it is possible to change the default search
                location as well as to use a simplified wildcarding
                syntax:</p>

                <cmt:cmtcode>
library A -s=A *.cxx -s=B *.cxx</cmt:cmtcode>

                <ul>

                  <li><tt>-s=A</tt> means that next source files
                  should be taken searched from <tt>../src/A</tt></li>

                  <li><tt>-s=B</tt> means that next source files
                  should be taken searched from
                  <tt>../src/B</tt>. Note that this new specification
                  is <i>not</i> relative to the previous <tt>-s=A</tt>
                  but relative to the default search path
                  <tt>../src</tt></li>

                  <li><tt>*.cxx</tt> indicates that all files with a
                  <tt>.cxx</tt> suffix in the current search path
                  should be considered
                  </li>

                </ul>

                <p>It's also possible to select or exclude files using
                regular expressions from general wildcarding
                techniques:</p>

                <cmt:cmtcode>
library A -s=A -x=[0-9] *.cxx -s=B -k=^B *.cxx</cmt:cmtcode>

                <ul>

                  <li>The exclusion specification <tt>-x=[0-9]</tt>
                  added to the statement will exclude all files
                  from <tt>../src/A</tt> containing a <i>number</i> in their name.</li>

                  <li>The selection specification <tt>-k=^B</tt> added
                  to the statement will select files from
                  <tt>../src/B</tt> strictly starting with the
                  <tt>B</tt> letter.</li>

                </ul>

              <p></p></li>

              <li><a name="suffix option"></a>

                <p>When several constituents need to share source
                files, (a typical example is for building different
                libraries from the same sources but with different
                compiler options), it is possible to specify an
                optional output suffix with the
                <tt>-suffix=&lt;suffix&gt;</tt> option. With this
                option, every object file name will be automatically
                suffixed by the character string
                "<tt>&lt;suffix&gt;</tt>", avoiding name conflicts
                between the different targets, as in the following
                example:</p>

		<cmt:cmtcode>
library AXt  -suffix=Xt  *.cxx
library AXaw -suffix=Xaw *.cxx</cmt:cmtcode>

              </li>

              <li><a name="variable-name option"></a>

                <p>It's possible to specify in the list of parameters
                one or more pairs of
                <tt>variable-name</tt>=<tt>variable-value</tt> (without
                any space characters around the <tt><tt>"="</tt></tt>
                character), such as in the next example:</p>

		<cmt:cmtcode>
make_fragment doc_to_html                             (1)

document doc_to_html Foo output=FooA.html FooA.doc    (2) (3)</cmt:cmtcode>


                <ol>

                  <li>This makefile fragment is meant to contain some text
                  conversion actions and defines a <a href="#Defining a
                  document generator"> document type</a> named
                  <tt>doc_to_html</tt>.</li>

                  <li>This constituent exploits the document type
                  <tt>doc_to_html</tt> to convert the source <tt>FooA.doc</tt>
                  into an html file.</li>

                  <li>The user defined template variable named <tt>output</tt>
                  is specified and assigned the value <tt>FooA.html</tt>. If the
                  fragment <tt>doc_to_html</tt> contains the string
                  <tt>${output}</tt>, then it will be substituted to
                  this value.</li>

                </ol>

              <p></p></li>

              <li><a name="the target tag option"></a>

                <p>For any constituent that has the
                <tt>-target_tag</tt> option set, a dedicated
                <i>tag</i> named <tt>target_&lt;constituent&gt;</tt>
                is automatically constructed by CMT. This tag becomes
                active during the construction of this constituent
                when using <tt>make</tt>, and therefore can be used as
                any other tag to select symbol values, or other
                configuration parameters.</p>

              </li>

            </ol>

          </cmt:section>

          <cmt:section title="Groups">

            Groups permit the organization of the constituents that must
            be consistently built at the same development phases or with similar
            constraints.

            <p>Each group is associated with a make target (of the same
              name) which, when used in the make command, selectively
              rebuilds all constituents of this group.</p>

            <p>The default group (into which all constituents are
              installed by default) is named <tt>all</tt>, therefore,
              running make without argument, activates the default target
              (ie. <tt>all</tt>).</p>

            <p>As a typical usage of this mechanism, one may examplify the
              case in which one or several constituents are making use of
              one special facility (such as a database service, real-time
              features, graphical libraries) and therefore might require a
              controled re-build. This is especially useful for having these
              constituents only rebuilt on demand rather than rebuilt
              automatically when the default make command is run.</p>

            <p>One could, for instance specify within the requirements file :</p>

	    <cmt:cmtcode>
# Constituents belonging to the default <i>all</i> group

<i>... constituents without group specification ...</i>
library Foo *.cxx

# Constituents belonging to specific groups

library Foo-objy -group=objy &lt;<i>sources making use of Objectivity</i>&gt;

application FooGUI -group=graphics &lt;<i>sources making use of Qt</i>&gt;
application BarGUI -group=graphics &lt;<i>sources making use of Qt</i>&gt;
</cmt:cmtcode>

            <i>(Beware of the position of the -group option which must be
              located after the constituent name. Any other position will be
              misunderstood by CMT)</i>

            <p>Then, running <tt>gmake all</tt> would only rebuild the un-grouped
              constituents, whereas running</p>

	      <cmt:code>
&gt; gmake objy
&gt; gmake graphics</cmt:code>

            <p>in the context of the <tt>Foo</tt> package would rebuild <i>objy</i>
              related or <i>graphics</i> related constituents.</p>

          </cmt:section>

          <cmt:section title="Languages">

            Some computer languages are known by default by <tt>CMT</tt>
            (<tt>C</tt>, <tt>C</tt>++, <tt>Fortran77</tt>, <tt>Java</tt>,
            <tt>lex</tt>, <tt>yacc</tt>). However it is possible to extend
            this knowledge to any other langage.

            <p>We consider here languages that are able to produce object
              files from sources.</p>

            <p>Let's take an example. We would like to install support for
              Fortran90. We first have to <i>declare</i> this new language
              support to <tt>CMT</tt> within the <tt>requirements</tt> file of
              one of our packages (Notice that it's not at all required to
              modify <tt>CMT</tt> itself since all clients of the selected
              package will inherit the knowledge of this language).</p>

            <p>The language support is simply named <tt>fortran90</tt> and is
              declared by the following statement:</p>

	      <cmt:cmtcode>
language fortran90 \
  -suffix=f90 -suffix=F90 \             [1]
  -linker=$(f90link) \                  [2]
  -preprocessor_command=$(ppcmd)</cmt:cmtcode>

            <ol>

              <li>The recognized suffixes for source files will be <tt>f90</tt> and <tt>F90</tt></li>

              <li>The linker command used to build a Fortran90 application
              is described inside the macro named <tt>f90link</tt> (which
              must defined in this requirements file but which can also be
              overridden by clients)</li>

            </ol>

            <p>The language support being named <tt>fortran90</tt>, two
            associated make fragments are expected, one under the name
            <tt>fortran90</tt> (for building application modules), the
            other with the name <tt>fortran90_library</tt> (for modules
            meant to be archived), both without extension.</p>

            <p>These two fragments should be installed in the
            <tt>fragments</tt> sub-directory of the cmt branch of our
            package.</p>

            <p>Due to the similarity of the example to fortran77, we
            may easily provide the expected fragments simply by
            copying the f77 fragments found in <tt>CMT</tt> (thus the
            fragments <tt>${CMTROOT}/fragments/fortran</tt> and
            <tt>${CMTROOT}/fragments/fortran_library</tt></p>

            <p>These fragments make use of the <tt>fcomp</tt> macro,
            which holds the fortran77 compiler command (through the
            <tt>for</tt> macro).</p>

	    <cmt:cmtcode>
macro for             "f77" \
...
macro fcomp           "$(for) -c $(fincludes) $(fflags) $(pp_fflags)"</cmt:cmtcode>

            <p>We therefore simply replace these macros by new macros
            named <tt>f90comp</tt> and <tt>f90</tt>, defined as
            follows:</p>

	    <cmt:cmtcode>
macro f90             "f90"
...
macro f90comp         "$(f90) -c $(fincludes) $(fflags) $(pp_fflags)"</cmt:cmtcode>

            <p>Some languages (this has been seen for example in the
            IDL generators in Corba environments) do provide several
            object files from one unique source file. It is possible
            to specify this feature through the (repetitive)
            <tt>-extra_output_suffix</tt> option like in:</p>

	    <cmt:cmtcode>
language idl -suffix=idl -fragment=idl -extra_output_suffix=_skel</cmt:cmtcode>

            where, in this case, two object files are produced for each
            IDL source file, one named <tt>&lt;<i>name</i>&gt;.o</tt> the
            other named <tt>&lt;<i>name</i>&gt;_skel.o</tt>.

          </cmt:section>

          <cmt:section title="Symbols">

            <p>This is a generic concept supporting the notion of
            valued symbols. Several alternate semantics are
            implemented by these symbols, all specified using the
            same syntactic schema, but leading to different behaviours
            or interpretations by CMT:</p>

            <ul>

              <li>The <tt>set</tt> keyword is translated into an environment
              variable definition.</li>

              <li>The <tt>macro</tt> keyword is translated into a
              <tt>make</tt>'s macro definition.</li>

              <li>The <tt>path</tt> keyword is translated into a
              prioritized <i>path</i>-like environment variable, which
              is supposed to be composed of search paths separated
              with colon characters <tt>':'</tt> (on Unix) or semi-colon
              characters <tt>';'</tt> (on Windows). It is generally
              recommended to construct such a variable by iteratively
              concatenating individual items one by one using
              <tt>path_append</tt> or <tt>path_prepend</tt></li>

              <li>The <tt>action</tt> keyword is translated into a shell
              command definition, that can be activated using the
              <tt>cmt do &lt;action&gt;</tt> command or the associated
              <tt>make</tt> target.</li>

              <li>The <tt>alias</tt> keyword is translated into a shell alias
              definition, </li>

            </ul>

            <p>Variants of these keywords are also provided for
            modifying already defined symbols. This generally happens
            when a package needs to modify (append, prepend or
            subtract) an inherited symbol (ie. which has been already
            defined by a used package).</p>

            <p>The translations occur while running either the setup
              scripts (for alias, set or path) or the make command (for
              macro and actions).</p>

            <p>All these definitions follow the same pattern:</p>

	    <cmt:syntax name="symbol">
	      <cmt:rule name="symbol">
	        <cmt:alt>
		  <cmt:term name="symbol-type"/>
		  <cmt:term name="symbol-name"/>
		  <cmt:term name="default-value"/>
		  <cmt:optionseq>
		    <cmt:term name="tag-expr"/>
		    <cmt:term name="value"/>
		  </cmt:optionseq>
	        </cmt:alt>
	      </cmt:rule>
              <cmt:rule name="symbol-type">
                <cmt:alt><cmt:term name="definition"/></cmt:alt>
                <cmt:alt><cmt:term name="modification"/></cmt:alt>
              </cmt:rule>
              <cmt:rule name="definition">
                <cmt:alt><cmt:kwd name="macro"/></cmt:alt>
                <cmt:alt><cmt:kwd name="set"/></cmt:alt>
                <cmt:alt><cmt:kwd name="path"/></cmt:alt>
                <cmt:alt><cmt:kwd name="action"/></cmt:alt>
                <cmt:alt><cmt:kwd name="alias"/></cmt:alt>
              </cmt:rule>
              <cmt:rule name="modification">
                <cmt:alt><cmt:kwd name="macro_prepend"/></cmt:alt>
                <cmt:alt><cmt:kwd name="macro_append"/></cmt:alt>
                <cmt:alt><cmt:kwd name="macro_remove"/></cmt:alt>
                <cmt:alt><cmt:kwd name="macro_remove_regexp"/></cmt:alt>
                <cmt:alt><cmt:kwd name="macro_remove_all"/></cmt:alt>
                <cmt:alt><cmt:kwd name="macro_remove_all_regexp"/></cmt:alt>
                <cmt:alt><cmt:kwd name="set_prepend"/></cmt:alt>
                <cmt:alt><cmt:kwd name="set_append"/></cmt:alt>
                <cmt:alt><cmt:kwd name="set_remove"/></cmt:alt>
                <cmt:alt><cmt:kwd name="set_remove_regexp"/></cmt:alt>
                <cmt:alt><cmt:kwd name="path_prepend"/></cmt:alt>
                <cmt:alt><cmt:kwd name="path_append"/></cmt:alt>
                <cmt:alt><cmt:kwd name="path_remove"/></cmt:alt>
                <cmt:alt><cmt:kwd name="path_remove_regexp"/></cmt:alt>
              </cmt:rule>
              <cmt:rule name="tag-expr">
                <cmt:alt>
                  <cmt:term name="tag"/>
                  <cmt:optionseq>
		    <cmt:kwd name="&amp;"/>
		    <cmt:term name="tag"/>
		  </cmt:optionseq>
                </cmt:alt>
              </cmt:rule>
	    </cmt:syntax>

	    <p></p>

            <ul>

              <li>The symbol-name identifies the symbol.<p></p></li>

              <li>Values are generally quoted strings (using either
              simple or double quotes). They may be unquoted only if
              they are composed of one single non-empty word, since
              the general syntax parsing relies on space separated
              words.<p></p></li>

              <li> The default-value is mandatory (although it can be
              an empty string) optionally followed by a set of
              tag/value pairs, each representing an alternate value
              for this symbol.<p></p></li>

              <li>Each tag-value pair describes an alternate value to
              be used when the corresponding tag or tag-expression is
              active.<p></p></li>

              <li>When several alternate values are specified through
              several tag-value pairs the <i>first</i> matching
              condition is selected. Therefore one should always
              specify the most contraining condition first.<p></p></li>

              <li>The removal operations can be specified using either
              plain sub-strings or regular rexpressions. One should
              notice that even for the <tt>path_remove_regexp</tt>
              operation, full regular expression are expected rather
              than file-system wild carding syntaxes.<p></p></li>

              <li>The <tt>path_remove</tt> keyword is slightly
              specialized since it removes all individual search paths
              that <i>contain</i> the specified sub-string.<p></p></li>

            </ul>

            <p>Be aware that there is only one name space for
            all kinds of symbols. Therefore, if a symbol was originally
            defined using a <tt>macro</tt> statement, using
            <tt>set_append</tt> to modify it will produce an undefined
            result (and a warning message).</p>

            <p>The <a href="#tag, apply_tag">tag</a> expression is
            used to select one alternate value to replace the default
            value, using the following matching rule:</p>

            <ul>

              <li>The first matching condition in the ordered list of
              alternate values is selected, ignoring the following
              ones</li>

              <li>A tag expression matches when all tags in the
              expression are active.</li>

            </ul>

            <p>Examples of such definition are : </p>

	    <cmt:cmtcode>
package CMT 

macro cflags          "" \
      LynxOS-VGPW2    "-X" \
      insure          "-std1" \
      HP-UX           "+Z" \
      hp700_ux101     "-fpic -ansi" \
      alpha           "-std1" \
      alphat          "-std1" \
      SunOS           "-KPIC" \
      WIN32           '/nologo /DWIN32 /MD /W3 $(includes) /c'

macro pp_cflags       "" \
      LynxOS-VGPW2    "-DVGPW2" \
      HP-UX           "-D_HPUX_SOURCE" \
      alphat          "-DCTHREADS" \
      AIX             "-D_ALL_SOURCE -D_BSD" \
      Linux           "-Di586"

macro ccomp           "$(cc) -c $(includes) $(cdebugflags) $(cflags) $(pp_cflags)" \
      VisualC         "cl.exe $(cdebugflags) $(cflags) $(pp_cflags)"

macro clinkflags      ""

macro clink           "$(cc) $(clinkflags)" \
      VisualC         "link.exe /nologo /machine:IX86 "
</cmt:cmtcode>

            <cmt:section  title="actions">

              Actions are one of the possible symbols. Their
              definition as said previously follow the generic
              conventions for any symbol type, and they implement the
              concept of a generic shell command.

              <p>An example of a symple action:</p>

              <cmt:cmtcode>
action directory "ls $(dir_options)" WIN32 "dir $(dir_options)"</cmt:cmtcode>

              <p>Like other symbols, actions can be visualized using
              the <tt>cmt show actions</tt> or the <tt>cmt show action
              &lt;name&gt;</tt> command.</p>

              <p>Some specialized mechanims are available on actions,
              in order to execute in various ways the corresponding
              shell commands.</p>

              <p>Actually two operating modes are supported:</p>

              <ol>

                <li>Immediate mode

                  <p>This can be done via the <tt>cmt do</tt> command:</p>

                  <cmt:code>&gt; cmt &lt;action-name&gt;</cmt:code>

                  <p>or, when the action name conflicts with a native CMT keyword, </p>

                  <cmt:code>&gt; cmt do &lt;action-name&gt;</cmt:code>

                  <p>This mode immediately executes the specified
                  command, after locally setting all environment
                  variables known from the current package.</p>

                </li>

                <li>Through <tt>make</tt>

                  <cmt:code>
&gt; cmt make &lt;action-name&gt;</cmt:code>

                  <ul>

                    <li>Actions are always associated with a make
                    target of the same name</li>

                    <li>Action are always defined under a constituent
                    <a href="#Groups">group</a> named
                    <tt>cmt_actions</tt>. This means that action
                    targets are never activated by default. Instead
                    they must be explicitly called.
                    </li>

                    <li>Action targets can be made dependent to other
                    make targets (or vice versa), similarly to other
                    constituents (libraries, applications, documents),
                    using the <tt>&lt;name&gt;_dependencies</tt>
                    macro.

                    <p>Example 1</p>

                    <cmt:cmtcode>
library A ...
action B ...
macro B_dependencies " A "</cmt:cmtcode>

                    In this example when doing <tt>gmake B</tt>, the
                    library <tt>A</tt> will be rebuilt first.

                    <p>Example 2</p>

                    <cmt:cmtcode>
library A ...
action B ...
macro A_dependencies " B "</cmt:cmtcode>

                    In this example when doing <tt>gmake A</tt> (or
                    simply <tt>gmake</tt>), the action <tt>B</tt> will
                    be executed first.

                    </li>
                  </ul>

                </li>

              </ol>

            </cmt:section>

          </cmt:section>

          <cmt:section  title="use">

            <p>Describe the relationships with other packages; the
            generic syntax is :</p>

	    <cmt:cmtcode>
use &lt;package&gt; [ &lt;version&gt; [ &lt;offset&gt; ] ]</cmt:cmtcode>

            <p>Omitting the version specification means that the most
            recent version (ie. the one with highest ids) that can be
            found from the search path list will be automatically
            selected.</p>

            <p> The <i>offset</i> specification can be relative
            (i.e. on Unix it does not contain a leading '/'
            character). In this case, this offset is systematically
            considered when the package is looked for in the search
            path list. But it can also be absolute (ie. with a leading
            '/' character on Unix), in which case this path takes
            precedence over the standard search path list (see
            CMTPATH).</p>

            <p> Examples of such relationships are :</p>

	    <cmt:cmtcode>
use OnX v5r2 
use CSet v2r3 
use Gb v2r1 

# A package installed in a sub-directory one step below the root : 
use CS v3r1 virgo 

# Back to the default root : 
use Cm v7r3 

# Get the most recent version of CERNLIB
use CERNLIB</cmt:cmtcode>

            <p>By default, a set of standard macros, which are
            expected to be specified by used packages, is
            automatically imported from them (see the <A
            HREF="#Package customizing macros">detailed list</A> of
            these macros). This automatic feature can be discarded
            using the <tt>-no_auto_imports</tt> option to the use
            statement, or re-activated using the
            <tt>-auto_imports</tt>. When it is discarded, the macros
            will not be transparently inherited, but rather, each
            individual constituent willing to make use of them will
            have to explicitly import them using the
            <tt>-import=&lt;<i>package</i>&gt;</tt> <a
            href="#constituents">option</a>.</p>

            <p>When a <tt>use</tt> statement is in a <a href="#public, private"><tt>private</tt></a>
            section, the corresponding used package will only be
            reached if when <tt>CMT</tt> operations occur in the context
            of the holder package. Otherwise (ie if the operation
            occurs in some upper level client package), then this
            <i>privately</i> used package will be entirely
            hidden. (<i>This behaviour follows a very similar pattern
            to the private or public inheritance of C++</i>). Suppose
            we have the following organization:</p>

	    <cmt:cmtcode>
----------------
package A

use B v1
use D v1
----------------

----------------
package B

private
use C v1
use D v1
----------------
</cmt:cmtcode>

            <ul>
              <li> all operations done in the context of package B will <i>see</i> both packages C and D</li>
              <li> all operations done in the context of package A will <i>see</i> both packages B and D, but not package C</li>
            </ul>

          </cmt:section>

          <cmt:section title="patterns">

            <p>Often, similar configuration items are needed over a
            set of packages (sometimes over all packages of a
            project). This reflects either similarities between
            packages or generic conventions established by a project
            or a team.</p>

            <p>Typical examples are the definition of the search path
            for shared libraries (through the <tt>LD_LIBRARY_PATH</tt>
            environment variable), the systematic production of test
            applications, etc.</p>

            <p>The concept of pattern proposed here implements this
            genericity. Patterns may be either <i>global</i>, in which
            case they will be systematically applied onto every
            package, or <i>local</i> (the default) in which case they
            will be applied on demand only by each package.</p>

            <p>The general principle of a pattern is to associate a
            templated (set of) <tt>cmt</tt> statement(s) with the
            pattern name. Then every time the pattern is applied, its
            associated statements are applied as if they were directly
            specified in the requirements file, replacing the template
            with its current value. If several statements are to be
            associated with a given pattern, they will be separated
            with the <tt>" ; "</tt> separator pattern (beware of really
            enclosing the <tt>;</tt> character between two space
            characters).</p>

	    <p>The general syntax for defining a pattern in a
	    requirements file is:</p>

	    <cmt:syntax name="pattern">
	      <cmt:rule name="pattern">
                <cmt:alt>
	          <cmt:kwd/>
                  <cmt:option><cmt:kwd name="-global"/></cmt:option>
                  <cmt:term name="pattern-name"/>
                  <cmt:ruleref name="cmt-statement"/>
                </cmt:alt>
                <cmt:continuation>
                  <cmt:optionseq>
                  <cmt:kwd name=" ; "/>
                  <cmt:ruleref name="cmt-statement"/>
                  </cmt:optionseq>
                </cmt:continuation>
              </cmt:rule>
            </cmt:syntax>

            <p>Pattern templates are names enclosed between the
            <tt>&lt;</tt> and <tt>&gt;</tt> characters. A set of
            predefined templates are automatically provided by
            <tt>CMT</tt>:</p>

            <p>
              <center>
                <table BORDER='1' COLS='2'> 
                  <tr> 
                    <td width="80"><tt>package</tt></td> 
                    <td width="300">the name of the current package</td> 
                  </tr> 
                  <tr> 
                    <td><tt>PACKAGE</tt></td> 
                    <td>the name of the current package in upper case</td> 
                  </tr> 
                  <tr> 
                    <td><tt>version</tt></td> 
                    <td>the version tag of the current package</td> 
                  </tr> 
                  <tr> 
                    <td><tt>path</tt></td> 
                    <td>the access path of the current package</td> 
                  </tr> 
                  <tr> 
                    <td><tt>project</tt></td> 
                    <td>the project name of the current package</td> 
                  </tr> 
                </table>
              </center>
            </p>

            <p>Then, in addition, user defined templates can be installed
              within the pattern definitions. Their actual value will be
              provided as arguments to the apply_pattern statement.</p>

            <p>User defined templates that have not been assigned a
            value when the pattern is applied are simply ignored
            (ie. replaced with an empty string).</p>

            <p>Some examples:</p>

            <ol>
              <li>
                <p>Changing the standard include search path.</p>

                <p>The standard include path is set by default to
                  <tt>${&lt;package&gt;_root}/src</tt>. However, often projects
                  need to override this default convention, and typical
                  example is to set it to a branch named with the package
                  name. This convention is easily applied by defining a
                  pattern which will apply the include_path statement as
                  follows:</p>

		<cmt:cmtcode>
pattern -global include_path include_path ${&lt;package&gt;_root}/&lt;package&gt;/</cmt:cmtcode>

                <p>For instance, a package named <tt>PackA</tt> will expand this
                  pattern as follows:</p>

		<cmt:cmtcode>
include_path ${PackA_root}/PackA/</cmt:cmtcode>
              </li>
              <li>
                <p>Providing a value to the <tt>LD_LIBRARY_PATH</tt> environment variable</p>

                <p>On some operating systems (eg. Linux), shared library
                  paths must be explicited, through an environment
                  variable. The following pattern can automate this operation:</p>

		<cmt:cmtcode>
pattern ld_library_path \
  path_remove LD_LIBRARY_PATH "/&lt;package&gt;/" ; \
  path_append LD_LIBRARY_PATH ${&lt;PACKAGE&gt;ROOT}/${CMTCONFIG}</cmt:cmtcode>

                <p>In this example, the pattern was not set global, so
                  that only packages actually providing shared libraries
                  would be concerned. These packages will simply have to
                  apply the pattern as follows:</p>

		<cmt:cmtcode>
apply_pattern ld_library_path</cmt:cmtcode>

                <p>The schema installed by this pattern provides first a
                  cleanup of the <tt>LD_LIBRARY_PATH</tt> environment variable
                  and then the new assignment. This choice is useful in this
                  case to avoid conflicting definitions from two different
                  versions of the same package.</p>

              </li>

              <li>
                <p>Installing a systematic test application in all packages</p>

                <p>Quality assurance requirements might specify that every
                  package should provide a test program. One way to enforce
                  this is to build a global pattern declaring this
                  application. Then every make command would naturally
                  ensure its actual presence.</p>

		<cmt:cmtcode>
pattern quality_test application &lt;package&gt;test &lt;package&gt;test.cxx &lt;other_sources&gt;</cmt:cmtcode>

                <p>In this example, an additional pattern
                  (&lt;other_sources&gt;) permits the package to specify
                  extra source files to the test application (the pattern
                  assumes at least one source file &lt;package&gt;test.cxx).</p>

              </li>
            </ol>

            <cmt:section title="Applying a pattern">

              According to whether the <tt>-global</tt> qualifier was
              used in the pattern definition, the aplication mode will
              be completely different.

              <ol>

                <li><i>Normal patterns</i>

                  <p>Such patterns must be applied explicitly using
                  the <tt>apply_pattern</tt> construct</p>

                  <p>Doing so, it is possible to specify custmization
                  values for user defined template parameters</p>

                  <cmt:cmtcode>
pattern TA macro &lt;base&gt;AAA "AAA"

apply_pattern TA base=abc
apply_pattern TA base=def</cmt:cmtcode>

                  <p>In the <tt>apply_pattern</tt> syntax, it is even
                  possible to simply <i>ommit</i> the keyword itself,
                  and thus using the pattern name as a plain CMT
                  keyword. The previous example becomes: </p>

                  <cmt:cmtcode>
TA base=abc
TA base=def</cmt:cmtcode>

                  <p>This can be seen as a way to <i>extend</i> the
                  CMT language. Notice that there is a risk of a
                  conflict between the primary CMT keywords and
                  pattern names then. Suppose that a pattern name is
                  defined to be exactly a primary CMT keyword. In this
                  case, the syntax parser will always understand this
                  name as the CMT primary keyword, and thus won't
                  override the original syntax. When this (not
                  recommended) situation occurs, it is therefore
                  required to use the full notation with an explicit
                  <tt>apply_pattern</tt> keyword, so as to avoid any
                  possible ambiguity.</p>

                </li>

                <li><i>Global patterns</i> (ie when the <tt>-global</tt> qualifier is used

                  <p>In this case, the pattern is automatically applied
                  to <i>all</i> packages that effectively see the
                  pattern definition, which includes all clients of
                  the package defining the pattern.</p>

                  <p>Another consequence of the automatic application
                  of the pattern, is that it is not possible to give
                  values to parameters. Therefore it is not
                  recommended to design global patterns with user
                  defined parameters.</p>

                  <p>Conversely it is possible to inhibit the
                  automatic application of a global pattern in a
                  particular package by using the following
                  statement:</p>

                  <cmt:cmtcode>
ignore_pattern &lt;name&gt;</cmt:cmtcode>

                </li>

              </ol>

            </cmt:section>

          </cmt:section> 

          <cmt:section title="cmtpath_patterns">

	    <p>These patterns act quite similarly to the <i>global</i>
	    patterns previously described, ie they defines a set of
	    CMT statements to be applied in a generic way. The
	    difference is that instead of being applied to
	    <i>packages</i>, they are automatically applied to all
	    entries in the <tt>CMTPATH</tt> list.</p>

	    <p>Only few system parameters can be used here:

              <ul>

                <li><tt>&lt;path&gt;</tt> which stands for any entry
                in the CMTPATH list.</li>

                <li><tt>&lt;project&gt;</tt> which stands for the
                project name associated with an entry in the CMTPATH
                list.</li>

              </ul>

            </p>

	    <p>As an example suppose we define</p>

	    <cmt:cmtcode>
path        CMTPATH "/ProjectA"
path_append CMTPATH "/ProjectB"

cmtpath_pattern \
  macro_prepend pp_cppflags " -I&lt;path&gt;/InstallArea/include "</cmt:cmtcode>

	    <p>this will assemble one <tt>-I</tt> option (towards the
	    preprocessor) per entry in CMTPATH, implementing a
	    mechanism for a multiple installation area for header
	    files. In the example above the resulting macro will
	    be</p>

	    <cmt:code>
 -I/ProjectA/InstallArea/include -I/ProjectB/InstallArea/include </cmt:code>

	    <p>
	    This can be combined with the standard and 
	    <a href="#Generated macros">automatic macros</a>
	    (automatically setup for all used packages)

	    <cmt:cmtcode>
&lt;package&gt;_cmtpath
&lt;package&gt;_offset</cmt:cmtcode>

	    which provide the CMTPATH entry and the directory offset
	    in this CMTPATH for all used packages.

	    </p>

          </cmt:section>

          <cmt:section title="branches">

            <p>Describe the specific directory branches to be added while
              configuring the package.</p>

	    <cmt:cmtcode>
branches &lt;branch-name&gt; ... </cmt:cmtcode>

            <p> These branches will be created (if needed) at the same
              level as the <tt>cmt</tt> branch. Typical examples of such
              required branches may be <tt>include</tt>, <tt>test</tt> or
              <tt>data</tt>.</p>

          </cmt:section> 

           <cmt:section title="Strategy specifications">
 
            <p>Users can control the behaviour of <tt>CMT</tt> through a
            set of strategy specifications. The current implementation
            provides such control over several aspects :</p>
 
            <ol>

              <li>

	        <p>The build strategy</p>

                <p>This controls some aspects of the building
                process. </p>

                <p>The following keywords are available:</p>

                <p>
                  <center>
                    <table BORDER='1' COLS='2'> 
                      <tr> 
                        <td width="80"><tt>prototypes</tt></td> 

                        <td width="500">C source files will
                        automatically produce a header file containing
                        a prototype of all global entry points</td>

                      </tr> 

                      <tr> 
                        <td width="80"><tt>no_prototypes</tt></td> 

                        <td width="500">No production of automatic
                        prototype header files for C sources</td>

                      </tr> 

                      <tr> 
                        <td width="80"><tt>with_installarea</tt></td> 

                        <td width="500">The installation area
                        mechanisms are activated. This implies
                        applying the cmtpath_patterns that may be
                        defined (eg in CMT itself)</td>

                      </tr> 

                      <tr> 
                        <td width="80"><tt>without_installarea</tt></td> 

                        <td width="500">The installation area
                        mechanisms are inhibited</td>

                      </tr> 

                    </table>
                  </center>
                </p>

              </li>

              <li>
	        <p>The setup strategy</p>

		<p>This controls various actions that may be performed
		during the sourcing of the setup scripts.</p>

                <p>The following keywords are available:</p>

                <p>
                  <center>
                    <table BORDER='1' COLS='2'> 

                      <tr> 
                        <td width="80"><tt>config</tt></td> 

                        <td width="500">An environment variable
                        &lt;PACKAGE&gt;CONFIG will be generated for all
                        packages in the dependency chain</td>

                      </tr> 

                      <tr> 
                        <td width="80"><tt>no_config</tt></td> 

                        <td width="500">The &lt;PACKAGE&gt;CONFIG
                        environment variable is not generated </td>

                      </tr> 

                      <tr> 
                        <td width="80"><tt>root</tt></td> 

                        <td width="500">An environment variable
                        &lt;PACKAGE&gt;ROOT will be generated for all
                        packages in the dependency chain</td>

                      </tr> 

                      <tr> 
                        <td width="80"><tt>no_root</tt></td> 

                        <td width="500">The &lt;PACKAGE&gt;ROOT
                        environment variable is not generated </td>

                      </tr> 

                      <tr> 
                        <td width="80"><tt>cleanup</tt></td> 

                        <td width="500">The automatic cleanup
                        operation to the current installation
                        area is launched</td>

                      </tr> 

                      <tr> 
                        <td width="80"><tt>no_cleanup</tt></td> 

                        <td width="500">The automatic cleanup
                        operation to the current installation
                        area is not launched</td>

                      </tr> 

                    </table>
                  </center>
                </p>

	      </li>

            </ol>

            <p>The strategy specifications are setup on a per-project
            basis. This means that they are generally applicable to
            all packages of a given sub-project, and can be oerridden
            in other sub-projecs of the same software base.</p>

            <p>Every strategy setting defines two mutually exclusive
            tags and activates one of them.</p>

              <cmt:cmtcode>
&lt;project&gt;_&lt;have_item&gt; 
&lt;project&gt;_&lt;have_not_item&gt; </cmt:cmtcode>

            Examples 

            <cmt:cmtcode>
&lt;project&gt;_prototypes
&lt;project&gt;_no_prototypes
&lt;project&gt;_with_install_area
&lt;project&gt;_without_install_area
&lt;project&gt;_config
&lt;project&gt;_no_config
&lt;project&gt;_root
&lt;project&gt;_no_root
&lt;project&gt;_cleanup
&lt;project&gt;_no_cleanup</cmt:cmtcode>

          </cmt:section> 

          <cmt:section title="setup_script, cleanup_script">

            <p>Specify user defined configuration scripts, which will be
              activated together with the execution of the main
              <tt>setup</tt> and <tt>cleanup</tt> scripts.</p>

            <p> The script names may be specified without any access path
              specification, in this case, they are looked for in the
              <tt>cmt</tt> or <tt>mgr</tt> branch of the package
              itself. They may also be specified without any <tt>.csh</tt>
              or <tt>.sh</tt> suffix, the appropriate suffix will be
              appended accordingly when needed. Therefore, when such a user
              configuration script is specified, <tt>CMT</tt> expects that
              the corresponding shell scripts actually exist in the
              appropriate directory (the <tt>cmt</tt> branch by default) and
              is provided in whatever format is appropriate (thus suffixed
              by <tt>.csh</tt> and/or <tt>.sh</tt>).</p>

          </cmt:section> 

          <cmt:section title="include_path">

            <p>Override the specification for the default include search
              path, which is internally set to<br />
              <tt>${&lt;<i>package</i>&gt;_root}/src</tt>.</p>

            <p>Specifying the value <tt><i>none</i></tt> (a reserved
            CMT keyword) means that no default include search path is
            expected from CMT, and thus no <tt>-I</tt> compiler option
            will be generated by default (generally this means that
            user include search paths should be specified via explicit
            <tt>include_dirs</tt> instead).</p>

          </cmt:section> 

          <cmt:section title="include_dirs">

            <p>Add explicit specifications for include access paths.</p>

          </cmt:section> 

          <cmt:section title="make_fragment">

            <p>This statement specifies a specialized makefile fragment,
              used as a building brick to construct the final makefile
              fragment dedicated to build the constituents.</p>

            <p>There are basically three categories of such fragments :
              <ol>
                <li>some are provided by <tt>CMT</tt> itself (they
                  correspond to its        internal behaviour)</li> 
                <li>others handle the language support</li>
                <li>and the        last serve as specialized document generators.</li>
              </ol>
            </p>

            <p>The fragments defined in <tt>CMT</tt> can be:</p>

            <ul>

              <li> those used to construct the application or library
                constituents. Their semantic is 
                standardized (they are all associated with a
                <tt>language</tt> statement in the CMT requirements
                file).

                <cmt:blockquote>
                  <i>
                    c c_library cpp cpp_library lex lex_library fortran
                    fortran_library yacc yacc_library jar jar_header
                    java java_copy java_header check_java cleanup_java
                  </i>
                </cmt:blockquote>

              </li>

              <li> those used internally by CMT as primary building
                blocks for assembling the makefile. (Generally developers
                should not see them). 

                <cmt:blockquote>
                  <i>
                    cleanup_objects application
                    constituent application_header constituents_header
                    buildproto protos_header os9_header dependencies
                    check_application dependencies_and_triggers
                    check_application_header document_header library
                    cleanup library_header cleanup_application
                    library_no_share cleanup_header make_header
                    cleanup_library
                  </i>
                </cmt:blockquote>

              </li>

              <li> some document generators which <i>may</i> be used if
                needed, but are not mandatory:
                <cmt:blockquote>
                  <i>
                    installer installer_header readme readme_header
                    readme_trailer readme_use dvi tex generator
                    generator_header
                  </i>
                </cmt:blockquote>

              </li>

              <li> those used to generate configuration files for MSVisualC++:
                <cmt:blockquote>
                  <i>
                    dsp_windows_header dsw_all_project
                    dsw_all_project_dependency dsw_all_project_header
                    dsw_all_project_trailer dsw_header dsw_project
                    dsw_trailer dsp_all dsp_application_header
                    dsp_contents dsp_library_header
                    dsp_shared_library_header dsp_trailer
                  </i>
                </cmt:blockquote>

              </li>

            </ul>

            <p>Language fragments should provide two forms, one for the
              applications (in which case they are named exactly after the
              language name eg c, cpp, fortran) and the other for the
              libraries (in which case they have the <tt>_library</tt>
              suffix (eg. c_library, cpp_library, fortran_library). A set
              of language definitions (C, C++, Fortran, Java, Lex, Yacc)
              is provided by CMT itself but it is expected that projects
              add new languages according to their needs. Event if the
              make fragment meant to be the implementation of a language
              support is declared, the language support itself must be
              declared too, using the <tt>language statement</tt> </p>

            <p>All make fragments are provided as (suffixless) files
              which must be located in the <tt>fragments</tt>
              sub-directory inside the cmt/mgr branch of one
              package. They must also be declared in the requirements
              file (through the <tt>make_fragment</tt> statement) so as to
              be visible.</p>

            <p>A package declaring, and implementing a make fragment may
              override a fragment of the same name when it is already
              declared by a used package. This implies in particular that
              any package <tt>may</tt> freely override any make fragment
              provided by <tt>CMT</tt> itself (although in this case a deep
              understanding of what the original fragment does is
              recommended).</p>

            <p>Makefile fragments may take any form convenient to the
              document style, and some special pre-built templates (see
              the <A HREF="#Standard templates for makefile
                     fragments">appendix</A>) can be used in their body to
              represent running values, meant to be
              properly expanded at actual generation time :</p>

            <p><table BORDER='1' COLS='2'> 
                 <tr> 
                   <td width="150"><tt>CONSTITUENT</tt></td> 
                   <td width="400">the constituent name</td> 
                 </tr> 
                 <tr> 
                   <td><tt>FULLNAME</tt></td> 
                   <td>the full source path</td> 
                 </tr> 
                 <tr> 
                   <td><tt>FILENAME</tt></td> 
                   <td>the source file name without its path</td> 
                 </tr> 
                 <tr> 
                   <td><tt>NAME</tt></td> 
                   <td>the source file name without its path and suffix</td> 
                 </tr> 
                 <tr> 
                   <td><tt>FILESUFFIX</tt></td> 
                   <td>the dotted file suffix</td> 
                 </tr> 
                 <tr> 
                   <td><tt>FILEPATH</tt></td> 
                   <td>the output path</td> 
                 </tr> 
                 <tr> 
                   <td><tt>SUFFIX</tt></td> 
                   <td>the default suffix for output files</td> 
                 </tr> 
               </table>
            </p>

          </cmt:section>

          <cmt:section title="public, private">

            <p>The <tt>public</tt> or <tt>private</tt> keywords
            introduce sections containing <i>public</i> or
            <i>private</i> statements. This concerns:</p>

            <ul>

              <li>the definition of symbols</li>

              <li>the specification of use relationships</li>

              <li>the declaration of make fragments</li>

              <li>the declaration of patterns</li>

            </ul>

	    <p>Public definitions are meant to be exported to any
	    client of the package whereas private ones are only
	    available for the package <i>developper</i> ie. when the
	    current directory is within the package itself.</p>

	    <p>Public use relationships expose the complete sub-tree
	    to the package clients, whereas private ones entirely hide
	    the sub-tree, expanding it only when the operator really
	    acts from within the context of the package. It should be
	    noticed that private use relationships are completely
	    unvisible from clients, which implies that none of the
	    definitions (not only symbols) will be set.</p>

	    <p>However, the <tt>cmt broadcast</tt> and <tt>cmt show
	    uses</tt> commands are configured to always ignore the
	    private specification and therefore will always traverse
	    the sub-trees whether they are public or private (in order
	    to ensure the hierarchy dependencies)</p>

            <cmt:section title="Scoping sections">

              By using the <tt>public</tt> or <tt>private</tt> keywords,
              one defines <i>scoping</i> sections. This sections
              continues until:

              <ul>

                <li>another scoping statement is found, which simply
                switch to this new mode <p></p></li>

                <li>an <tt>end_private</tt> or <tt>end_public</tt>
                keyword is found, in which case the scoping mode is
                reset to the state prior to the previous matching
                <tt>private</tt> or <tt>public</tt> statement. This
                latter mechanisms permits in particular to define
                autonomous scoping sections within <a
                href="#patterns"><tt>pattern</tt>s</a>.  <p></p></li>

              </ul>

              <p>By default <tt>cmt</tt> commands operate according to
              the scoping specifications found in the requirements
              files of the reachable packages. Ie. in the current
              package all statements are considered whether being
              prublic or private, while in used packages, only public
              statements are considered.</p>

              <p>This standard behaviour though is not applied when
              running <tt>cmt broadcast</tt> or <tt>cmt show
              uses</tt>, and in this case all statements public or
              private, are always considered, even in used
              packages.</p>

              <p>However it is always possible to override the default
              behaviours by using the <tt>-private</tt> or
              <tt>-public</tt> modifier to the <tt>cmt</tt>
              command:</p>

              <ul>

                <li><tt>-private</tt><p>Force the command to consider
                all definitions even those installed in private
                sections</p><p></p></li>

                <li><tt>-public</tt><p>Force the command to really
                mask the private sections</p><p></p></li>

              </ul>

            </cmt:section>

          </cmt:section>

          <cmt:section title="tag, apply_tag">

            <p>The <tt>tag</tt> keyword provides tag definitions,
            while the <tt>apply_tag</tt> keyword <i>activates</i> a tag.</p>

            <p> A tag is a token which can be used to select
            particular values of symbols.</p>

            <p> Some tags are automatically constructed by CMT
            according to its knowledge of the context (see this <a
            href="#Selecting a specific configuration">section</a> for
            more details), but they may be also defined within a <a
            HREF="#The requirements file">requirements</a> file as
            follows :</p>

<cmt:cmtcode>
tag Foo                [1]
tag Bar Foo FooA FooB  [2]
apply_tag Bar          [3]</cmt:cmtcode>

            <ol>

              <li>This simply declares a tag. This does not
              activate it by default<p></p></li>

              <li>This construct declares that the tags <tt>Foo</tt>,
              <tt>FooA</tt> and <tt>FooB</tt> will become active if
              <tt>Bar</tt> becomes active. Note that this statement
              implicitly <i>declares</i> <tt>FooA</tt> and
              <tt>FooB</tt><p></p></li>

              <li>This activates the <tt>Bar</tt> tag. Tags that have
              been associated with it (in [2]), will all become active
              as well.<p></p></li>

            </ol>

            <p>Running the setup script (through the <i>source
            setup.[c]sh</i> or <i>call setup.bat</i> command ) can
            also receive tag specifications using the
            <i>-tag=tag-list</i> options.</p>

          </cmt:section>

        </cmt:section>

        <cmt:section title="The general cmt user interface">

          This utility (a shell script combined with a <tt>C++</tt> 
          application) provides a centralised access to various commands 
          to the <tt>CMT</tt> system. The first way to use <tt>cmt</tt> is 
          to run it without argument, this will print a minimal help text 
          showing the basic commands and their syntax : 

<cmt:code>
&amp;gt; cmt command [option...]
<i><font face="courier new, courier" COLOR="#000077"> command :
   none
   awk
   broadcast [-select=list] [-exclude=list] [-local] [-global] [-begin=pattern] [-depth=n] &amp;lt;command&gt; : 
        apply a command to [some of] the used packages
   build &amp;lt;option&gt;          : build actions. (Try cmt help build)
   build constituent_makefile &amp;lt;constituent&gt;  : generate constituent Makefile fragment
   build constituents_makefile : generate constituents.make
   build dependencies      : generate dependencies
   build library_links     : build symbolic links towards all imported libraries
   build make_setup        : build a compiled version of setup scripts
   build msdev             : generate MSDEV files
   build CMT_pacman        : generate PACMAN manifest file for CMT
   build vsnet             : generate VS.NET files
   build os9_makefile      : generate Makefile for OS9
   build prototype         : generate prototype file
   build readme            : generate README.html
   build tag_makefile      : generate tag specific Makefile
   build temporary_name    : generate a name for a temprary file
   build triggers &amp;lt;constituent&gt; : generate library trigger file
   build windefs &amp;lt;library_name&gt; : generate def file for Windows shared libraries
   check &amp;lt;option&gt;          : check actions. (Try cmt help check)
   check configuration     : check configuration
   check files &amp;lt;old&gt; &lt;new&gt; : compare two files and overrides &lt;old&gt; by &lt;new&gt; if different
   check version &amp;lt;name&gt;    : check if a name follows a version tag syntax 
   co | checkout           : perform a cvs checkout over a CMT package
   cleanup [-csh|-sh|-bat] : generate a cleanup script
   config                  : generate setup and cleanup scripts
   create &amp;lt;package&gt; &lt;version&gt; [&lt;path&gt;] : create and configure a new package
   create_project &amp;lt;project&gt; &lt;name&gt; [&lt;path&gt;] : create and configure a new project
   cvsbranches &amp;lt;module&gt;      : display the subdirectories for a module
   cvssubpackagess &amp;lt;module&gt;  : display the subpackages for a module
   cvstags &amp;lt;module&gt;          : display the CVS tags for a module
   do &amp;lt;action&gt; [&lt;param&gt;=&lt;value&gt;] ... : Execute an action
   expand model &amp;lt;model&gt;    : 
   filter &amp;lt;in&gt; &lt;out&gt;       : filter a file against CMT macros and env. variables
   help | -help | --help   : display this help
   load
   lock [&amp;lt;p&gt; &lt;v&gt; [&lt;path&gt;]] : lock a package
   remove &amp;lt;package&gt; &lt;version&gt; [&lt;path&gt;] : remove a package version
   remove library_links    : remove symbolic links towards all imported libraries
   run '&amp;lt;command&gt;'         : apply a command
   run_sequence &amp;lt;sequence file&gt; : execute a cmt equence file
   set version &amp;lt;version&gt;   : generate a version file in the current package
   set versions            : generate version files into packages
   setup [-csh|-sh|-bat]   : generate a setup script
   show &amp;lt;option&gt;           : query actions. (Try cmt help show)
   show  action &amp;lt;name&gt;     :  a formatted action definition
   show  action_value &amp;lt;name&gt; :  a raw action definition
   show  action_names      :  all action names
   show  actions           :  all action definitions
   show  all_tags          :  all defined tags
   show  applied_patterns  :  all patterns actually applied
   show  author            :  package author
   show  branches          :  added branches
   show  clients           :  package clients
   show  cmtpath_patterns  :  cmtpath_patterns
   show  constituent &amp;lt;name&gt;:  constituent definition
   show  constituent_names :  constituent names
   show  constituents      :  constituent definitions
   show  cycles            :  cycles in the use graph
   show  fragment &amp;lt;name&gt;   :  one fragment definition
   show  fragments         :  fragment definitions
   show  groups            :  group definitions
   show  include_dirs      :  
   show  language &amp;lt;name&gt;   :  language definition
   show  languages         :  language definitions
   show  macro &amp;lt;name&gt;      :  a formatted macro definition
   show  macro_value &amp;lt;name&gt;  :  a raw macro definition
   show  macro_names       :  all macro names
   show  macros            :  all macro definitions
   show  manager           :  package manager
   show  packages          :  packages reachable from the current context
   show  path              :  the package search list
   show  pattern &amp;lt;name&gt;    :  the pattern definition and usages
   show  pattern_names     :  pattern names
   show  patterns          :  the pattern definitions
   show  projects          :  project definitions
   show  setup             :  setup definitions
   show  pwd               :  filtered current directory
   show  set &amp;lt;name&gt;        :  a formatted set definition
   show  set_names         :  set names
   show  set_value &amp;lt;name&gt;  :  a raw set definition
   show  sets              :  set definitions
   show  strategies        :  all strategies (build &amp; version)
   show  tags              :  all currently active tags
   show  use_paths &amp;lt;pack&gt;  :  all paths to the used package
   show  uses              :  used packages
   show  version           :  version of the current package
   show  versions &amp;lt;name&gt;   :  visible versions of the selected package
   system                  : display the system tag
   unlock [&amp;lt;p&gt; &lt;v&gt; [&lt;path&gt;]] : unlock a package
   version                 : version of CMT
 global options :
   -quiet                  : don't print errors
   -use=&amp;lt;p&gt;:&lt;v&gt;:&lt;path&gt;     : set package version path
   -pack=&amp;lt;package&gt;         : set package
   -version=&amp;lt;version&gt;      : set version
   -path=&amp;lt;path&gt;            : set root path
   -f=&amp;lt;requirement-file&gt;   : set input file
   -e=&amp;lt;statement&gt;          : add a one line statement
   -tag=&amp;lt;tag-list&gt;         : select a new tag-set
   -tag_add=&amp;lt;tag-list&gt;     : add specific comma-separated tag(s)
   -tag_remove=&amp;lt;tag-list&gt;  : remove specific comma-separated tag(s)
   -with_version_directory : reset to default structuring style
   -without_version_directory : switch structuring style
   -cleanup                : activate install area cleanup
   -no_cleanup             : inhibit install area cleanup</font></i></cmt:code>

          <p>The following sections present the detail of each available command. </p>

          <cmt:section title="cmt broadcast">

            This command tries to repeatedly execute a shell command in the 
            context of each of the used package of the current package. The 
            used packages are listed using the <tt>cmt show uses</tt> 
            command, which also indicates in which order the broadcast is 
            performed. When the <tt>all_packages</tt> option, the set of
            packages reached by the broadcast is rather the same as the one shown
            by the <tt>cmt show packages</tt> command, ie all <tt>CMT</tt> packages
            and versions available throught the current <tt>CMTPATH</tt> list.

            <p>Typical uses of this <i>broadcast</i> operation could be:</p>

<cmt:code>
csh&gt; cmt broadcast cmt config
csh&gt; cmt broadcast - gmake 
csh&gt; cmt broadcast '(cd ../; cvs -n update)' </cmt:code>

            <p>The loop over used packages will stop at the first error
              occurence in the application of the command, except if the
              command was preceded by a '-' (minus) sign (similarly to the
              make convention).</p>

            <p>It is possible to specify a list of selection or
              exclusion criteria set onto the package path, using the
              following options, right after the <tt>broadcast</tt>
              keyword. These selection criteria may be combined (eg one
              may combine the <i>begin</i> and <i>select</i>
              modifiers)</p>

<cmt:code>
sh&gt; cmt broadcast -begin=Cm gmake                 (1)
sh&gt; cmt broadcast -select=Cm gmake                (2)
sh&gt; cmt broadcast -select='/Cm/ /CSet/' gmake     (3)
sh&gt; cmt broadcast -select=Cm -exclude=Cmo gmake   (4)
sh&gt; cmt broadcast -local gmake                    (5)
sh&gt; cmt broadcast -depth=&lt;n&gt; gmake                (6)
sh&gt; cmt broadcast -global gmake                   (7)
sh&gt; cmt broadcast -all_packages gmake             (8)</cmt:code>

            <p>According to the option, the loop will only operate onto:</p>

            <ol>
              <li>the first package which path contains the string
              <tt>"Cm"</tt>, and then all other reachable packages (in
              case other specifiers are used)</li>

              <li>the packages which path contains the string <tt>"Cm"</tt></li>

              <li>the packages which path contains either the string
              <tt>"/Cm/"</tt> or the string <tt>"/CSet/"</tt></li>

              <li>the packages which path contains the string <tt>"Cm"</tt>,
              but which does not contain the string <tt>"Cmo"</tt></li>

              <li>the packages at the same level as the current package</li>

              <li>the packages at the same level as the current package or
              among the &lt;n&gt; first entries in the <tt>CMTPATH</tt> list</li>

              <li>the packages at any level of the CMTPATH search list</li>

              <li>all the packages and versions currently available
              through the <tt>CMTPATH</tt> list</li>
            </ol>

	    <cmt:section title="Specifying the shell command">

	    <p>A priori any Unix or DOS shell command can be specified
	    in a boadcast command. However, it's important to
	    understand the order of the various parsing actions:</p>

	    <ol>
	      <li>The current shell first parses the complete command line</li>
	      <li>CMT catches all possible options given to the broadcast command itself</li>
	      <li>CMT then gets the rest of the command line and makes it the shell command to be executed during the broadcast scan.</li>
	      <li>This command line may be subject to template substitution (see below) by CMT</li>
	      <li>Eventually the command line is passed to the local shell (which may then perform additional parsing actions)</li>
	    </ol>

	    <p>Considering this complex sequence of parsing, it may be
	    appropriate to selectively enclose the shell command
	    passed to the broadcast action into quotes. It may even be
	    sometimes useful to have two levels of quotes</p>

	    </cmt:section>

	    <cmt:section title="Templates in the shell command">

	    <p>Similarly to what exists in the <a
	    href="#patterns">pattern</a> mechanism, some standard
	    <i>templated</i> values can be embedded inside the
	    command to be executed by the broadcast action. They take
	    a standard form of
	    <i><tt>&lt;template-name&gt;</tt></i>. These templates acquire
	    their value on each package effectively reached during the
	    broadcast scan, and the effective value is substituted
	    before launching the command. The possible templates are:</p>

	    <table>

	      <tr>
	        <td><tt>&lt;package_cmtpath&gt;</tt></td>
	        <td>The element in the CMTPATH search list where the package has been found</td>
	      </tr>

	      <tr>
	        <td><tt>&lt;package_offset&gt;</tt></td>
	        <td>The directory offset to cmtpath</td>
	      </tr>

	      <tr>
	        <td><tt>&lt;package&gt;</tt></td>
	        <td>The package name</td>
	      </tr>

	      <tr>
	        <td><tt>&lt;version&gt;</tt></td>
	        <td>The version of the package</td>
	      </tr>

	    </table>

	    <p>The next example shows a typical broadcast command listing the
	    header files as expected in the conventional location
	    <tt>../&lt;package&gt;</tt> :</p>

	    <cmt:code>
&gt; cmt broadcast 'ls ../&lt;package&gt;'
<i><font face="courier new, courier" COLOR="#000077">[...]
#--------------------------------------------------------------
# Now trying [ ls ../GenzModuleEvent] in /.../GenzModuleEvent/.../cmt (149/609)
#--------------------------------------------------------------
CVS  KineHepMcmap.h
#--------------------------------------------------------------
# Now trying [ ls ../Tauola_i] in /.../Tauola_i/.../cmt (150/609)
#--------------------------------------------------------------
CVS     Jaki.icc        Tauola_i.h    Taurad.h    config.h    rn_tau.h
Jaki.h  ReadPDGtable.h  Tauola_i.icc  Taurad.icc  polhep.inc  tauola_cblk.inc
#--------------------------------------------------------------
# Now trying [ ls ../NavigationEvent] in /.../NavigationEvent/.../cmt (151/609)
#--------------------------------------------------------------
CVS  INavigable.h  INavigationCondition.h  INavigationSelector.h
INavigationToken.h  NavigationToken.h
[...]</font></i></cmt:code>

	    <cmt:blockquote>
	    One should note that when templates are used in a
	    broadcast command, it's important to enclose the command
	    in quotes so as to inhibit any possible parsing of the
	    <tt>&lt; &gt;</tt> syntax by the shell.
	    </cmt:blockquote>

	    </cmt:section>

          </cmt:section> 

          <cmt:section title="cmt build &lt;option&gt;">

	    <p>The actions associated with the build options are
            generally meant for internal use only, and users will
            rarely (if ever!) apply them manually</p>

	    <p>All build commands are generally meant to change the
            current package (some file or set of files is
            generated). Therefore a check against conflicting locks
            (ie. a lock owned by another user) is performed by all
            these commands prior to execute it.</p>

            <ul> 
              <li><tt>[-nmake] constituent_makefile &lt;<i>constituent-name</i>&gt;</tt> 
 
                <p>This command is internally used by <tt>CMT</tt> in the standard 
                  Makefile.header fragment. It generates a specific makefile 
                  fragment (named &lt;<i>constituent-name</i>&gt;.make) 
                  which is used to re-build this fragment. </p>

                <p>All such constituent fragments are automatically 
                  included from the main Makefile. </p>

                <p>Although this command is meant to be used internally 
                  (and transparently) by <tt>CMT</tt> when the make command is run, a 
                  developer may find useful in very rare cases to manually 
                  re-generate the constituent fragment, using this command.</p>

                <p>The <tt>-nmake</tt> option (which must precede the
                  command) provides exactly the same features but in a
                  Windows/nmake context. In this case, all generated
                  makefiles are suffixed by <tt>.nmake</tt> instead of
                  <tt>.make</tt> for Unix environments. The main makefile is
                  expected to be named <tt>NMake</tt> and the standard header
                  is named <tt>NMakefile.header</tt></p>

              </li> 

              <li><tt>[-nmake] constituents_makefile</tt>

                <p>This command is internally (and transparently) used by 
                  <tt>CMT</tt> in the standard Makefile.header fragment, and when the 
                  make command is run, to generate a specialized make 
                  fragment containing all "cmt build constituent_makefile" 
                  commands for a given package. </p>

                <p>The <tt>-nmake</tt> option (which must precede the
                  command) provides exactly the same feature but in a
                  Windows/nmake context. In this case, all generated
                  makefiles are suffixed by <tt>.nmake</tt> instead of
                  <tt>.make</tt> for Unix environments. The main makefile is
                  expected to be named <tt>NMake</tt> and the standard header
                  is named <tt>NMakefile.header</tt></p>

              </li>

              <li><tt>dependencies</tt>

                <p>This command is internally (and transparently) used by 
                  <tt>CMT</tt> from the constituent specific fragment, and when the 
                  make command is run, to generate a fragment containing the 
                  dependencies required by a source file. </p>

                <p>This fragment contains a set of macro definitions (one 
                  per constituent source file), each containing the set of 
                  found dependencies. </p>

              </li> 

              <li><tt>library_links</tt>

                <p>This command builds a local symbolic link towards all
                  exported libraries from the used packages. A package
                  exports its libraries through the
                  <tt>&lt;<i>package</i>&gt;_libraries</tt> macro which should
                  contain the list of constituent names corresponding to
                  libraries that must be exported.</p>

<cmt:cmtcode>
library Foo ...
library Foo-utils ...
...
macro Foo_libraries "Foo Foo-utils"</cmt:cmtcode>

                The corresponding <tt>cmt remove library_links</tt> command
                will remove all these links.

              </li>

              <li><tt>msdev</tt> 

                <p>This command generates workspace (.dsw) and project 
                  (.dsp) files required for the MSDev tool. </p>

              </li>

              <li><tt>vsnet</tt> 

                <p>This command generates workspace and project files
                required for the Visual.net tool. </p>

              </li>

              <li><tt>os9_makefile</tt>

                <p>This command generates external dedicated
                  <i>makefile</i> fragments for each individual component of
                  the package (ie. libraries or executable applications) to
                  be used in OS9 context. It generates specific syntaxes for
                  the <tt>OS9</tt> operating systems.</p>

                <p>The output of this tool is a set of files (named with
                  the components' name and suffixed by <tt>.os9make</tt>) that
                  are meant to be <i>included</i> within the main
                  <tt>Makefile</tt> that the developer has to write anyhow.</p>

                <p>The syntax of the <tt>cmt build os9_makefile</tt> utility 
                  is as follows : </p>

<cmt:code>
sh&gt; cmt build os9_makefile &lt;package&gt; </cmt:code>

              </li>

              <li><tt>prototype &lt;source-file-name&gt;</tt> 

                <p>This command is internally (and transparently) used by 
                  <tt>CMT</tt> from the constituent specific fragment, and when the 
                  make command is run, to generate prototype header files 
                  from C source files. </p>

                <p>The prototype header files (named &lt;file-name&gt;.ph) 
                  will contain prototype definitions for every global entry 
                  point defined in the corresponding C source file. </p>

                <p>The effective activation of this feature is controled 
                  by the build strategy of <tt>CMT</tt>. The build strategy may be 
                  freely and globally overridden from any &CMTrequirements; file, 
                  using the <tt>build_strategy</tt> cmt statement, providing 
                  either the "prototypes" or the "no_prototypes" values. </p>

                <p>In addition, any constituent may locally override this 
                  strategy using the "-prototypes" or "-no_prototypes" 
                  modifiers. </p>

              </li>

              <li><tt>readme</tt> 

                <p>This command generates a README.html file into the cmt 
                  branch of the referenced package. This html file will 
                  include  </p>

                <ul> 

                  <li>a table containing URLs to equivalent pages for 
                    all used packages,  </li>

                  <li>a copy of the local README file (if it exists). </li>

                </ul> 

              </li>

              <li><tt>tag_makefile</tt> 

                <p> This command produces onto the standard output, the
                  exhaustive list of all macros controled by <tt>CMT</tt>,
                  ie. those defined in the requirements files as well as the
                  standard macros internally built by <tt>CMT</tt>, taking
                  into account all used packages.</p>

              </li>

            </ul> 

          </cmt:section> 

          <cmt:section title="cmt check configuration">

            This command reads the hierarchy of requirements files 
            referenced by a package, check them, and signals syntax 
            errors, version conflicts or other configuration problems. 

            <p>An empty output means that everything is fine. </p>

          </cmt:section> 

          <cmt:section title="cmt check files &lt;reference-file&gt; &lt;new-file&gt;">

            This command compares the reference file to the new file, and 
            substitues the reference file by the new one if they are 
            different. 

            <p>If substitution is performed, a copy (with additional 
              extension <tt>sav</tt>) is produced. </p>

          </cmt:section> 

          <cmt:section title="cmt checkout ...">

            See the <a href="#Using cvs together with CMT">paragraph</a>
            on how to use cvs together with <tt>CMT</tt>, and more specifically the
            details on <a href="#Checking a package out from a cvs repository">checkout oprations</a>.

          </cmt:section> 

          <cmt:section title="cmt co ...">

            This is simply a short cut to the <tt>cmt checkout</tt> command. 

          </cmt:section> 

          <cmt:section title="cmt cleanup [-csh|-sh]">

            This command generates (to the standard output) a set of shell 
            commands (either for csh or sh shell families) meant to unset 
            all environment variables specified in the &CMTrequirements; files 
            of the used packages. 

            <p>This command is internally used in the cleanup.[c]sh shell 
              script, itself generated by the <tt>cmt config</tt> command. </p>

          </cmt:section> 

          <cmt:section title="cmt config">

            <p>This command (re-)generates the setup scripts and the
              manimal Makefile (when it does not exist yet or have been lost).</p>

<cmt:code>
csh&gt; cd ~/Packages/Foo/v1/cmt 
csh&gt; cmt config </cmt:code>

            <p>To be properly operated, one must <i>already</i> be in
              the <tt>cmt</tt> or <tt>mgr</tt> branch of a package (where the
              &CMTrequirements; file can
              be found).</p>

            <p>This command also performs some cleanup operations
              (eg. removing all makefile fragments previously
              generated). Generally speaking, one may say that this
              command restores the CMT-related files to their original state (ie
              before any document generation) </p>

            <p>The situations in which it is useful to run this command are:</p>

            <ul>

              <li>When the setup or cleanup scripts have been lost</li>

              <li>When the minimal Makefile have been lost</li>

              <li>When the version of <tt>CMT</tt> is changed</li>

              <li>After restoring a package from CVS</li>

              <li>After having manually changed the directory structure
                of a package (using a manual copy operation, or renaming
                one of its parent directory, such as the version
                directory)</li>

            </ul>

            <p>It should be noted however that when using
            <i>actions</i>, such as the one defined by default to
            launch <tt>make</tt> tools neither <tt>cmt config</tt> nor
            <tt>source setup</tt> are required any longer.</p>

          </cmt:section> 

          <cmt:section title="cmt create &lt;package&gt; &lt;version&gt; [&lt;area&gt;]">

            <p>
              This command creates a new package or a new version of a package</p>

<cmt:code>
csh&gt; cmt create Foo v1 </cmt:code>

            or:

<cmt:code>
csh&gt; cmt create Foo v1 ~/dev</cmt:code>

            <p>In the first mode (ie. without the <i>area</i> argument)
              the package will be created in the default path.</p>

            <p>The second mode explicitly provides an alternate path.</p>

            <p>A minimal configuration is installed for this new package:</p>

            <ul>

              <li>A <tt>src</tt> and a <tt>cmt</tt> branch</li>

              <li>A very minimal requirements file</li>

              <li>The setup and cleanup shell scripts</li>

              <li>The minimal Makefile</li>

            </ul>

          </cmt:section> 

          <cmt:section title="cmt expand model [-strict] &lt;model-string&gt;">

            This command produces on the standard output an
            <i>expansion</i> of the model string given in the
            argument.

            <p>The expansion consists in:</p>

            <ul>

              <li>Expanding macros referenced in the model string
              using the standard notations <tt>$()</tt> or
              <tt>${}</tt> or <tt>%%</tt>

                <cmt:code>
&gt; cmt expand model "abcd $(CMTVERSION) efgh"
<i><font face="courier new, courier" COLOR="#000077">abcd &CMTVersion; efgh</font></i></cmt:code>
              </li>

              <li><i>Recursively</i> expanding text files with
              parameters. The model string must then take a
              conventional XML-based syntax:

                <cmt:code>
&gt; cmt expand model "<i>text</i> &lt;<i>file-name</i> <i>parameter</i>=<i>value</i> ... /&gt; <i>text</i> ..."</cmt:code>

                or

                <cmt:code>
&gt; cmt expand model -strict "<i>text</i> &lt;cmts:<i>file-name</i> <i>parameter</i>='<i>value</i>' ... /&gt; <i>text</i> ..."</cmt:code>

                or

                <cmt:code>
&gt; cmt expand model -strict "<i>text</i> &lt;cmtv:<i>file-name</i> <i>parameter</i>='<i>v1 v2 v3 ...</i>' ... /&gt; <i>text</i> ..."</cmt:code>

                Where:

                <ul>
                  <li><i>file-name</i> is the name of a file declared
                  using the <tt>make_fragment</tt> statement</li>

                  <li><tt><i>parameter</i>=<i>value</i></tt> specifies
                  the value of a parameter that will be substituted in
                  the file when referenced using the
                  <tt>$(<i>parameter</i>)</tt> notation. Several such
                  values may be specified in one model string</li>

                  <li>the <tt>-strict</tt> form is useful to handle
                  XML files, and file names must be prefixed
                  (<i>namespaced</i>) by a special keyword
                  <tt>cmts:</tt> or <tt>cmtv:</tt> . 

                  <table>
                    <tr><td><tt>cmts:</tt></td><td>Perform a unique substitution over one copy of the file</td></tr>
                    <tr><td><tt>cmtv:</tt></td><td>Perform a multiple substitution over N copies of the file, taking the N space-separated values specified for the parameters</td></tr>
                  </table>

                  </li>

                </ul>

                The following examples will explain some of the mechanisms.

                <p>We consider <tt>A</tt> containing:</p>

                <cmt:code>
A$(P1)B$(P2)C</cmt:code>

                <p>And <tt>B</tt> containing:</p>

                <cmt:code>
i&lt;cmts:A P1='j' P2='${P2}'/&gt;k</cmt:code>


                <cmt:code>
&gt; cmt expand model "abcd &lt;A P1=XXX/&gt; efgh"                                      [1]
<i><font face="courier new, courier" COLOR="#000077">abcd AXXXBC efgh</font></i>
&gt; cmt expand model -strict "abcd &lt;cmts:A P1='XXX' P2='YYY'/&gt; efgh"              [2]
<i><font face="courier new, courier" COLOR="#000077">abcd AXXXBYYYC efgh</font></i>
&gt; cmt expand model -strict "abcd &lt;cmts:A P1='XXX'/&gt; &lt;cmts:B P2='YYY'/&gt; efgh"    [3]
<i><font face="courier new, courier" COLOR="#000077">abcd AXXXBC iAjBYYYCk efgh</font></i>
&gt; cmt expand model -strict "abcd &lt;cmtv:A P1='X Y Z' P2='YYY'/&gt; efgh"            [4]
<i><font face="courier new, courier" COLOR="#000077">abcd AXBYYYCAYBCAZBC efgh</font></i>
&gt; cmt expand model -strict "abcd &lt;cmtv:A P1='X Y Z' P2='\"\" &lt;cmt:null/&gt; ZZZ'/&gt; efgh"  [5]
<i><font face="courier new, courier" COLOR="#000077">abcd AXBCAYBCAZBZZZC efgh</font></i>
...</cmt:code>

                <ol>

                  <li>A simple expansion using the non-strict model
                  syntax. <tt>P1</tt> is substituted, but
                  <tt>$(P2)</tt> becomes empty
                  </li>

                  <li> The same using the strict model. Here P2 is valued.
                  </li>

                  <li>A more complex model, using a recursive
                  expansion described in <tt>B</tt> showing how
                  parameter values are transmitted</li>

                  <li>A model showing the multiple expansion. Here
                  <tt>P1</tt> receives 3 values. <tt>P2</tt> has only
                  one value. The largest vector (3 values) dictates
                  the number of copies. smaller vectors are completed
                  by empty values.</li>

                  <li>A model showing the multiple expansion with
                  empty values in a vector. Here <tt>P1</tt> receives
                  3 values. <tt>P2</tt> has also 3 values, but only
                  one non-empty. This examples show the two possible
                  means of specifying empty vector values: using
                  either <tt>\"\"</tt> or the reserved keyword
                  <tt>&lt;cmt:null/&gt;</tt>.</li>

                </ol>

                <p></p>
              </li>

              <li>The file expansion is recursive. This means that
              files specified in model elements will themselves be
              considered as model texts (ie following the same
              syntax), and be expanded in turn. This processus is
              entirely recursive, with no limit to the depth. The
              <i>-strict</i> option, when selected is propagated
              during the recursion.</li>

            </ul>

          </cmt:section> 

          <cmt:section title="cmt filter &lt;in-file&gt; &lt;out-file&gt;">

            This command reads &lt;in-file&gt;, substitutes all occurences 
            of macro references (taking either the form 
            <tt>$(<i>macro-name</i>)</tt> or <tt>${<i>macro-name</i>}</tt> 
            ) by values deduced from corresponding macro specifications 
            found in the &CMTrequirements; files, and writes the result into 
            &lt;out-file&gt;. 

            <p>This mechanism is widely internally used by <tt>CMT</tt>, especially 
              for instanciating make fragments. Then, users may use it for 
              any kind of document, including maual generation of MSDev 
              configuration files, etc... </p>

          </cmt:section> 

          <cmt:section title="cmt help | --help">

            This command shows the list of options of the <tt>cmt</tt> driver. 

          </cmt:section> 

          <cmt:section title="cmt lock [ &lt;package&gt; &lt;version&gt; [&lt;area&gt;] ]">

            This command tries to set a lock onto the current package (or onto the
            specified package). This consists in the following operations:

            <p></p>

            <ol>

              <li>Check if a conflicting lock is already set onto this
                package (ie. a lock owned by another user).</li>

              <p></p>

              <li>If not, then install a small text file named <tt>lock.cmt</tt> into the
                <tt>cmt/mgr</tt> branch of the package, containing the following text: 

<cmt:code>
locked by &lt;user-name&gt; date &lt;now&gt;</cmt:code>

                <p></p>
              </li>

              <li>Run a shell command described in the macro named <tt>lock_command</tt> meant to install physical locks onto all files for this version of this package. A typical definition for this macro could be:

<cmt:cmtcode>
macro lock_command   "chmod -R a-w ../*" \
      WIN32          "attrib /S /D +R ../*"</cmt:cmtcode>

              </li>

            </ol>

          </cmt:section> 

          <cmt:section title="cmt remove &lt;package&gt; &lt;version&gt; [&lt;area&gt;]">

            This command removes one version of the specified package. If
            the package does not contain a conflicting lock, and if the user is
            granted enough access rights to remove files, <i>all</i> files below
            the version directory will be definitively removed. Therefore
            this command should be used with as much care as possible.

            <p>The arguments needed to reach the package version to be
              removed are the same as the ones whic had been used to create it.</p>

            <p>If the removed version is the last version of this package,
              (and only if its directory is really empty) the package directory itself
              will be deleted.</p>

          </cmt:section> 

          <cmt:section title="cmt remove library_links">

            This command removes symbolic links towards all imported
            libraries which had been installed using the <tt>
            <a href="#build">cmt build library_links</a></tt>
            command. This command is generally transparently executed
            when one runs <tt>gmake clean</tt>

          </cmt:section> 

          <cmt:section title="cmt run [shell-command]">

            This command runs any shell command, in the context of the 
            current package.  

            <p>In particular all environment variables defined in
            requirements file are first set before running the
            command. This may be seen as a generic application
            launcher.</p>

	    <p>This may be combined with the global options
	    <tt>-pack=<i>package</i></tt>,
	    <tt>-version=<i>version</i></tt>,
	    <tt>-path=<i>access-path</i></tt>, to give a direct access
	    to any package context. </p>

          </cmt:section> 

          <cmt:section title="cmt set version &lt;version&gt;">

            This command creates and/or fills in the
            <tt>version.cmt</tt> file for a package structured without
            the version directory.

	    <p>This command has no effect when run in the context of a
	    package structured <i>with</i> the version directory</p>

	    <p>This command must be run while being in the context of
	    one CMT package.</p>

          </cmt:section>

          <cmt:section title="cmt set versions">

            This command applies recursively the <tt>cmt set version
            ...</tt> command onto all used packages using a broadcast operation.

	    <p>Packages reached during the broadcast scan acquire
	    their version from the original use statement. This is
	    this specified version which will be stored inside the
	    <tt>version.cmt</tt> files</p>

          </cmt:section>

          <cmt:section title="cmt setup [-csh|-sh|-bat]">

            This command generates (to the standard output) a set of shell
            commands (either for csh, sh or bat shell families) meant to
            set all environment variables specified in the 
            <a HREF="#The requirements file">requirements</a> files of the used
            packages.

            <p>This command is internally used in the
            <tt>setup.[c]sh</tt> or <tt>setup.bat</tt> shell script,
            itself generated by the <tt>cmt config</tt> command.</p>

          </cmt:section> 

          <cmt:section title="cmt show &lt;option&gt;">

            <ul> 
              <li><tt>all_tags</tt> </li>

                <p>This command displays all currently defined tags,
		  even when not currenty active</p>

              <li><tt>applied_patterns</tt> </li>

                <p>This command displays all patterns actually applied
                in the current package</p>

              <li><tt>author</tt> <p></p></li>

              <li><tt>branches</tt> <p></p></li>

              <li><tt>clients &lt;package&gt; [ &lt;version&gt; ]</tt> 

                <p>This command displays all packages that express an
                  explicit <strong>use</strong> statement onto the specified
                  package. If no version is specified on the argument list,
                  then all uses of that package are displayed.</p>

                <p>Note that the search on clients is <i>not</i>
                performed recusively. Thus only clients explicitly
                using the specified package will be displayed.</p>

                <p></p>
              </li>

              <li><tt>constituent_names</tt> <p></p></li>

              <li><tt>constituents</tt> <p></p></li>

              <li><tt>cycles</tt>

                <p>This command displays all cycles in the use graph
                of the current package. Although CMT smoothly accepts
                such cycles, it is generally a bad practice to have
                cycles in a use graph, because CMT can never decide on
                the prefered entry point in the cycle, leading to
                somewhat unpredictable results, eg in constructing the
                <tt>use_linkopts</tt> macro.</p>

              <p></p></li>

              <li><tt>fragment &lt;name&gt;</tt> 

                <p>This command displays the actual location where the
                  specified make fragment is currently found by <tt>CMT</tt>,
                  taking into account possible overridden definitions.</p>

              <li><tt>fragments</tt> 
                <p>Display the effective location of all declared make fragments </p>
                <p></p>
              </li>

              <li><tt>groups</tt> 

                <p>This command displays all groups possibly defined
                in constituents of the current package (using the
                <tt>-group=&lt;<i>group-name</i>&gt;</tt> option).</p>

                <p></p>
              </li>

              <li><tt>languages</tt>
                <p>Display al languages declared using the <tt>language</tt> keyword</p>
                <p></p>
              </li>

              <li><tt>macro &lt;name&gt;</tt> <br /> <tt>set &lt;name&gt;</tt> <br /> <tt>action &lt;name&gt;</tt>

                <p>This set of commands displays a quite detailed
                explanation on the value assigned to the symbol
                (macro, set or action) specified as the additional
                argument. It presents in particular each intermediate
                assignments made to this symbol by the hierarchy of
                used statements, as well as the final result of these
                assignment operations. </p>

                <p>By adding a <tt>-tag=&lt;tag&gt;</tt> option to this
                command, it is possible to simulate the behaviour of
                this command in another context, without actually
                going to a machine or an operating system where this
                configuration is defined. </p>

                <p></p>
              </li>

              <li><tt>macro_value &lt;name&gt;</tt> <br /> <tt>set_value &lt;name&gt;</tt> <br /> <tt>action_value &lt;name&gt;</tt> 

                <p>This set of commands displays the raw value
                assigned to the symbol (macro, set or action)
                specified as the additional argument. It only presents
                the final result of the assignment operations
                performed by used packages. </p>

                <p>By adding a <tt>-tag=&lt;tag></tt> option to this
                command, it is possible to simulate the behaviour of
                this command in another context, without actually
                going to a machine or an operating system where this
                configuration is defined.</p>

                <p>The typical usage of the <tt>show macro_value</tt>
                command is to get at the shell level (rather than
                within a <tt>Makefile</tt>) the value of a macro
                definition, providing means of accessing them (quite
                similarly to an environment variable) : </p>

                <cmt:code>
csh&gt; set compiler=`cmt show macro_value cppcomp` 
csh&gt; ${compiler} .... </cmt:code>

              </li>

              <li><tt>macros</tt> <br /> <tt>sets</tt> <br /> <tt>actions</tt>

                <p>This set of commands extracts from the
                <tt>&CMTrequirements;</tt> file(s) the complete set of
                symbol (macro, set or action) definitions, selects the
                appropriate <i>tag</i> definition (or uses the one
                provided in the <tt>-tag=&lt;tag&gt;</tt> option) and
                displays the effective symbol values corresponding to
                this tag. </p>

                <p>This command is typically used to show the
                effective list of macros used when running make and
                can be also used to build, as an argument list, the
                make command as follows : </p>

                <cmt:code>
csh&gt; eval make `cmt show macros` </cmt:code>

                <p>This use of <tt>cmt show macros</tt> is directly
                installed within the default target provided in the
                standard <tt>Makefile.header</tt> file.  Therefore if
                this file is included into the package's
                <tt>Makefile</tt>, macro definitions provided in the
                &CMTrequirements; files (the one of the currently
                built package as well as the ones of the used
                packages) will be expanded and provided as arguments
                to make. </p>

                <p>By adding a <tt>-tag=&lt;tag&gt;</tt> option to this
                command, it is possible to simulate the behaviour of
                this command in another context, without atcually
                going to a machine or an operating system where this
                configuration is defined. </p>

              </li>

              <li><tt>manager</tt> <p></p></li>

              <li><tt>packages</tt> 

                <p>This command displays all packages (and all
                versions of them) currently reachable through the
                current <a href="#Localizing a package">access
                path</a> definition (which can be displayed using the
                <tt>cmt show path</tt> command).</p> <p></p>

              </li>

              <li><tt>path</tt> 

                <p>This command displays the complete and effective <a
                href="#Localizing a package">access path</a> currently
                defined using any possible alternate way.</p>

              </li>

              <li><tt>pattern &lt;name&gt;</tt> 

                <p>This command displays how and where the specified
                pattern is defined, and which packages do apply
                it.</p></li>

              </li>

              <li><tt>patterns</tt> 

                <p>This command displays all pattern definitions.</p>

              </li>

              <li><tt>projects</tt>

                <p>This command displays the current knowledge of
                sub-project definitions and settings. It shows the
                project names and their location (ie the corresponding
                item in <tt>CMTPATH</tt></p>

                <cmt:code>
&gt; cmt show projects
<i><font face="courier new, courier" COLOR="#000077">PA (in C:\Arnault\test\tprojects\PC) (current)
Project1 (in C:\Arnault\test\tprojects\PB)
PA (in C:\Arnault\test\tprojects\PA\1.1)
Project2 (in C:\Arnault\test\tprojects\P0)
CMT (in C:\Arnault)</font></i></cmt:code>

                <p></p>
              </li>

              <li><tt>pwd</tt> 

                <p>This command displays a filtered version of the
                  standard <tt>pwd</tt> unix command. The applied filter takes
                  into account the set of aliases installed in the standard
                  configuration file located in
                  <tt>${CMTROOT}/mgr/cmt_mount_filter</tt>.</p>

                <p>This configuration file contains a set of path aliases
                  (one per line) each proposing a translation for
                  non-portable file paths (imposed by mount constraints on
                  some contexts).</p>

              </li>

              <li><tt>setup</tt> 
                <p>This command combines in one go the output of:</p>

                <cmt:code>
&gt; cmt show uses
&gt; cmt show tags
&gt; cmt show path</cmt:code>

              <p></p></li>

              <li><tt>strategies</tt> <p></p></li>

              <li><tt>tags</tt> </li>

	        <p>This command displays all currently <i>active</i>
		  tags, and what part of the configuration actually
		  activates them</p>

              <li><tt>uses</tt>

                 <p>This command displays the use graph fo the current
                 package. Private sections of used packages are
                 reached and considered. This behavior can be changed
                 to effectively hide the private sections in used
                 packages by using the <tt>-public</tt> modifier</p>

                 <cmt:code>
&gt; cmt -public show uses</cmt:code>

                 <p>A typical output produced by this command is:</p>

                 <cmt:code>
&gt; cmt show uses 
<i><font face="courier new, courier" COLOR="#000077"># use GaudiPolicy v*                             [1]
# use GaudiKernel v* 
#   use GaudiPolicy v5r*                         [2]
# use CLHEP v*  (native_version=1.8.2.0)         [3]
#   use ExternalLibs v4r* 
#
# Selection :                                    [4]
use CMT &CMTVersion; (/afs/cern.ch/sw/contrib)
use ExternalLibs v4r2p0  (/afs/cern.ch/atlas/offline/external/Gaudi/0.12.1.5)    [5]
use CLHEP v2r1820p0  (/afs/cern.ch/atlas/offline/external/Gaudi/0.12.1.5)
use GaudiPolicy v5r11p2  (/afs/cern.ch/atlas/offline/external/Gaudi/0.12.1.5)
use GaudiKernel v13r5p1  (/afs/cern.ch/atlas/offline/external/Gaudi/0.12.1.5)</font></i></cmt:code>

                 <ol>

                   <li>The first section of the display (up to the
                   <tt>Selection</tt> keyword) displays the
                   hierarchical use graph.

                   <p>Use statements as specified in the requirements
                   files are displayed, rather than the result of the
                   effective selection performed by CMT</p>
                   <p></p></li>

                   <li>Sub-uses are expanded only once and indented
                   according to the depth in the graph<p></p></li>

                   <li>Various precisions on the use statements are
                   shown in the first section, such as the scoping
                   section, the <tt>-no_auto_imports</tt> modifier,
                   and the <i>native version</i> of this package, (when
                   a <tt>&lt;package&gt;_native_version</tt> macro has
                   been defined)<p></p></li>

                   <li>The second section shows the effective ordered
                   set of use statements resolved by CMT according to
                   the combined use specifications.<p></p></li>

                   <li>On every line the effective location of the
                   found package is displayed.<p></p></li>

                 </ol>

                <p>The <tt>-quiet</tt> option may be used to remove the
                first section from the output so as to only display a
                simple list of used packages, starting from the
                deepest uses.</p>

              <p></p></li>

              <li><tt>use_paths &lt;target-package&gt;</tt> </li>

                <p>This command displays all possible paths between
                the current package and the specified used target
                package.</p>

                <p>In particular this will detect if a package has no
                access to another one, due to private use
                statements</p>


              <li><tt>version</tt> 

                <p>This command displays the version tag of the current package.</p>

              </li>

              <li><tt>versions &lt;name&gt;</tt> 

                <p>This command displays the reachable versions of the
                  specified package, looking at the current access paths.</p>

              </li>

            </ul> 

          </cmt:section>

          <cmt:section title="cmt system">

            This command displays the current value assigned by default to 
            the <tt>CMTCONFIG</tt> environment variable. 

          </cmt:section>

          <cmt:section title="cmt unlock [ &lt;package&gt; &lt;version&gt; [&lt;area&gt;] ]">

            This command tries to remove a lock from the current package (or from the
            specified package). This consists in the following operations:

            <p>
              <ol>

                <li>Check if a conflicting lock is already set onto this
                  package (ie. a lock owned by another user).
                </li>

                <li>If not, then remove the text file named <tt>lock.cmt</tt> from the
                  <tt>cmt/mgr</tt> branch of the package.

                </li>

                <li>Run a shell command described in the macro named <tt>unlock_command</tt> meant to remove physical locks from all files for this version of this package. A typical definition for this macro could be:

<cmt:cmtcode>
macro unlock_command "chmod -R g+w ../*" \
      WIN32          "attrib /S /D -R ../*"</cmt:cmtcode>
                </li>
              </ol>
            </p>

          </cmt:section>

          <cmt:section title="cmt version | --version">

            This command shows the current verion of <tt>CMT</tt>, including (if 
            applicable) the actual patch level. This always corresponds to 
            the corresponding CVS tag assigned to <tt>CMT</tt> sources. 

          </cmt:section>

          <cmt:section title="cmt cvstags &lt;module&gt;">

            (see the section on <i>how tu use </i><tt>CVS</tt><i>together 
                                                              with CMT</i> for more details on this command) 

          </cmt:section>

          <cmt:section title="cmt cvsbranches &lt;module&gt;">

          </cmt:section>

          <cmt:section title="cmt cvssubpackages &lt;module&gt;">

          </cmt:section>

        </cmt:section> 

        <cmt:section title="The setup and cleanup scripts">

          They are produced by the <tt>cmt config</tt> command and their 
          contents is built according to the specifications stored in the 
          <tt>&CMTrequirements;</tt> file. 

          <p>One flavour of these scripts is generated per shell family
            (<tt>csh</tt>, <tt>sh</tt> and <tt>bat</tt>), yielding the following
            scripts :</p>

          <cmt:code>
setup.csh 
setup.sh 
setup.bat
cleanup.csh 
cleanup.sh </cmt:code>

          <p>The main sections installed within a setup script are : </p>

          <ol> 
            <li> 
              Connection to the current version of the <tt>CMT</tt> package. 
            </li> 

            <li> Setting the set of user defined public variables
            specified in the &CMTrequirements; file (including those
            defined by all used packages). This is achieved by running
            the <tt>cmt setup</tt> utility into a temporary file and
            running this temporary file.  </li>

            <li> 
              Activation of the user defined setup and cleanup scripts 
              (those specified using the <tt>setup_script</tt> and 
              <tt>cleanup_script</tt> statements). 
            </li> 
          </ol> 

          It should be noted that these setup scripts do <i>not</i> 
          contain machine specific information (due to the online use of 
          the <tt>cmt setup</tt> command).  Therefore, it is perfectly 
          possible to use the same setup script on various platforms (as 
          soon as they share the directories) and this also shows that the 
          configuration operation (the <tt>cmt config</tt> command) is 
          required only once for a set of multiple platforms sharing a 
          development area. 

        </cmt:section> 

        <cmt:section title="cmt build prototype">

          This command is only provided for development of <tt>C</tt> 
          modules. It generates a <tt>C</tt> header file containing the 
          set of prototype statements for all public functions of a given 
          module. Its output is a file with the same name as the input 
          source (given as the argument) and suffixed with <tt>.ph</tt>. 

          <p>The generated prototype header file is meant to be included 
            whereever it is needed (in the module file itself for instance). </p>

          <p>A typical example of the use of <tt>cmt build prototype</tt> 
            could be : </p>

<cmt:code>
csh&gt; cd ../src 
csh&gt; cmt build prototype FooA.c 
<i><font face="courier new, courier" COLOR="#000077">Building FooA.ph </font></i></cmt:code>

          <p>Running <tt>cmt build prototype</tt> will only produce a new 
            prototype header file if the output is actually different from 
            the existing one (if it exists) in order to avoid confusing 
            <i>make</i> checks. </p>

          <p>The effective use of this facility (which may not be
            appropriate in all projects) is controlled by one option of the
            build strategy, which can take one of the two values:</p>

<cmt:cmtcode>
build_strategy prototypes
build_strategy no_prototypes</cmt:cmtcode>

          <p>In addition to this global strategy specification, each
            application or library may individually override it using the
            <tt>-prototypes</tt> or <tt>-no_prototypes</tt> options.</p>

          <p>Lastly, the actual behaviour of the prototype generator is
            defined in the standard make macro <tt>build_prototype</tt> (which
            default to call the <tt>cmt build prototype</tt> command, allowing
            a user defined behavious to this feature)</p>

        </cmt:section> 
</cmt:section> 

<cmt:section title="Using cvs together with CMT">

  <p>Nothing special is apriori required by <tt>CMT</tt> with respect to
  the use of <tt>CVS</tt>.  Nevertheless, one may advertize some well
  tested conventions and practices which turned out to ensure a good
  level of consistency between the two utilities.</p>

  <p>Although none of these are required, the <tt>cmt</tt> general
  command provides a few utilities so as to simplify the use of these
  practices. It should be noted that the added features provided by
  cmt rely on the possibility to <i>query</i> CVS about the existing
  <tt>CMT</tt> packages and the possible tags setup for these
  packages. CVS does not by default permit such query operations
  (since they require to scan the physical CVS repository). Therefore
  <tt>CMT</tt> provides a hook to CVS (based upon standard CVS features
  - not patches) for this. This hook can be installed following a
  recipe explained in the dedicated 
  <a href="#The internal mechanism of cmt cvs operations">appendix</a>.</p>

  <cmt:section title="Importing a package into a cvs repository">

    <p>Generally, everything composing a package (below the
    <i>version</i> directory and besides the <i>binary</i>
    directories) is relevant to be imported.  Then choosing a
    <tt>cvs</tt> <i>module</i> name is generally done on the basis of
    the package name. Taking the previous examples, one could import
    the <tt>Foo</tt> package as follows :</p>
          
    <cmt:code>
csh&gt; cd ...../Foo/v1 
csh&gt; cvs import -m "First import" -I alpha -I hp9000s700 Foo LAL v1 </cmt:code>
          
    <p>In this example, </p>

    <ul> 
      <li> 
        we have ignored the currently existing binary directories 
        (here <tt>alpha</tt> and <tt>hp9000s700</tt>) 
      </li> 
      <li> 
        the <tt>cvs</tt> module name is identical to the package 
        name (<tt>Foo</tt>) 
      </li> 
      <li> 
        the original symbolic insertion tag is identical to the 
        version identifier (<tt>v1</tt>) 
      </li> 
    </ul> 
          
    <p>The choice of the module name can generally be identical to the
    package name. However, some site specific management issues may
    lead to different choices (typically, a top directory where groups
    of packages are gathered may be inserted).</p>
          
    <p>Conversely, using symbolic tags identical to version
    identifiers appears to be a very good practice. The only
    constraint induced by <tt>cvs</tt> is that the symbolic tags may not
    contain <i>dot</i> characters (<tt>'.'</tt>), whereas no restriction
    exist from <tt>CMT</tt> itself. Thus version identifiers like
    <tt>v3r2</tt> will be preferred to the <tt>v3.2</tt> form. </p>

  </cmt:section>

  <cmt:section title="Checking a package out from a cvs repository">

    <p>Assuming the previous conventions on module name and version
    identifier have been selected when importing a package, the
    following operations will naturally intervene when one need to
    check a package out (typically to work on it or to install it on
    some platform) : </p>
          
    <cmt:code>
csh&gt; cd &lt;some root&gt;            (1) 
csh&gt; mkdir Foo                 (2) 
csh&gt; cd Foo 
csh&gt; cvs checkout -d v1 Foo    (3) 
csh&gt; cd v1/cmt 
csh&gt; cmt config                (4) 
csh&gt; source setup.csh          (5) 
csh&gt; [g]make                   (6) </cmt:code>
                                                        
    <ol> 
      <li> 
        one always have to select a root directory where to settle 
        down this copy of the extracted package. This may either be 
        the so-called <i>default root</i> or any other appropriate 
        directory. In both cases, the next <tt>cmt config</tt> 
        operation will automatically take care of this effective 
        location. 
      </li> 
      <li> 
        creating a base directory with the package name is mandatory 
        here, and is <i>not</i> taken into account by <tt>cvs</tt> 
        during the <i>chaeckout</i> operation since one wants to 
        insert the <i>version</i> branch in between. 
      </li> 
      <li> 
        the package is checked out into a directory named with the 
        expected version identifier exactly corresponding to the 
        version currently stored in the <tt>cvs</tt> 
        repository. 
      </li> 
      <li> 
        then using the <tt>cmt config</tt> command (from the 
        <tt>cmt</tt> branch) will update the setup scripts against 
        the <tt><a HREF="#The requirements file">requirements</a></tt> file and the effective current 
        package location. 
      </li> 
      <li> 
        using this updated version of the setup script provides the 
        appropriate set of environment variables 
      </li> 
      <li> lastly, rebuilding the entire package is possible simply
        using the <tt>[g]make</tt> command.
      </li>

    </ol> 

          
    <p>The actions decribed just above (from number 2 to number 4
    included) can also be performed using the <tt>cmt checkout</tt>
    command. </p>
          
    <cmt:code>
&gt; cd &lt;some work area&gt; 
&gt; cmt checkout [modifier ...] &lt;package&gt; ... 
<i><font face="courier new, courier" COLOR="#000077">                  
modifier :
-l        Do not process used packages (default).
-R        Process used packages recursively.
-r rev    Check out version tag. (is sticky)
-d dir    Check out into dir instead of module name.
-o offset Offset in the CVS repository
-n        Simulation mode on
-v        Verbose mode on
-help     Print this help</font></i></cmt:code>
          
    Thus the previous example would become:
          
    <cmt:code>
csh&gt; cd &lt;some root&gt;
csh&gt; cmt checkout Foo
csh&gt; cd Foo/v1/cmt 
csh&gt; source setup.csh
csh&gt; [g]make</cmt:code>
          
  </cmt:section>

  <cmt:section title="Querying CVS about some important infos">

    It is possible, using the commands :
          
    <ul> 
      <li> 
        <tt>cmt cvstags &lt;module&gt;</tt> 
      </li> 
      <li> 
        <tt>cmt cvsbranches &lt;module&gt;</tt> 
      </li> 
      <li> 
        <tt>cmt cvssubpackages &lt;module&gt;</tt> 
      </li> 
    </ul> 
          
    <p> to query the <tt>CVS</tt> repository about the existing tags
    installed onto a given <tt>CVS</tt> module, the subdirectories and
    the subpackages (in the <tt>CMT</tt> meaning, i.e. when a <tt><a
    HREF="#The requirements file">requirements</a></tt> file
    exists). </p>
          
    <cmt:code>
&gt; cmt cvstags Cm 
<i><font face="courier new, courier" COLOR="#000077">v7r6 v7r5 v7r4 v7r3 v7r1 v7 </font></i>
&gt; cmt cvstags Co 
<i><font face="courier new, courier" COLOR="#000077">v3r7 v3r6 v3 </font></i></cmt:code>
          
    <p>One should notice here that the <tt>cvstags</tt> command can give
    informations about any type of module, even if it is not managed
    in the <tt>CMT</tt> environment. </p>
          
    <p>However, in order to let this mechanism operate, it is required
    to install some elements into the physical <tt>CVS</tt> repository
    (<i> which may require some access rights into it</i>). This
    installation procedure (to be done only once in the life of the
    repositiory) can be achieved through the following command:</p>
          
    <cmt:code>
sh&gt; (cd ${CMTROOT}/mgr; gmake installcvs)</cmt:code>
          
    <p>However, the details of the procedure is listed below (this
    section is preferably reserved for system managers and can easily
    be skipped by standard users):</p>
          
    <ol> 

      <li> copy the <tt>cmt_buildcvsinfos2.sh</tt> shell script into the
      management directory <tt>${CVSROOT}/CVSROOT</tt> as follows :

        <cmt:code>
sh&gt; cp ${CMTROOT}/mgr/cmt_buildcvsinfos2.sh ${CVSROOT}/CVSROOT </cmt:code>
      </li> 
            
      <li> install one special statement in the <tt>loginfo</tt>
      administrative file as follows :
              
        <cmt:code>
sh&gt; cd ... 
sh&gt; cvs checkout CVSROOT 
sh&gt; cd CVSROOT 
sh&gt; vi loginfo 
... 
.cmtcvsinfos $CVSROOT/CVSROOT/cmt_buildcvsinfos2.sh 
sh&gt; cvs commit -m "set up commitinfo for CMT" </cmt:code>
      </li> 
    </ol> 
          
  </cmt:section>

  <cmt:section title="Working on a package, creating a new release">
        
    <p>This section presents the way to instanciate a new release of
    a given package, which happens when the foreseen modifications
    will yield additions or changes to the application programming
    interface of the package. </p>
          
    <p>Then the version tag is supposed to be moved forward, either
    increasing its minor identifier (in case of simple additions) or
    its major identifier (in case of changes). </p>
          
    <p>The following actions should be undertaken then : </p>
          
    <ol> 
      <li> 
        understand what is the latest version tag (typically by 
        using the <tt>cmt cvstags</tt> command). Let's call it 
        <tt>old-tag</tt>. 
        <p></p>
      </li> 
      <li> 
        select (according to the foreseen amount of changes) what 
        will be the next version tag. Let's call it 
        <tt>new-tag</tt>. 
        <p></p>
      </li> 
      <li> 
        check the most recent version of the package in your 
        development area : 
            
        <cmt:code>
sh&gt; cd &lt;development area&gt; 
sh&gt; cvs checkout -d &lt;new-tag&gt; &lt;package&gt; </cmt:code>
      </li> 
      <li> 
        configure this new release, and rebuild it : 
              
        <cmt:code>
sh&gt; cd &lt;new-tag&gt;/cmt 
sh&gt; cmt config 
sh&gt; source setup.csh 
sh&gt; [g]make </cmt:code>
      </li> 
    </ol> 
          
  </cmt:section>

  <cmt:section title="Getting a particular tagged version out of CVS">
        
    <p>The previous example presented the standard case where one gets
      the <i>most recent</i> version of a given package. The procedure
      is only slightly modified when one wants to extract a previously
      tagged version. Let's imagine that the <tt>Foo</tt> package has
      evolved by several iterations, leading to several tagged
      releases in the <tt>cvs</tt> repository (say <tt>v2</tt> and
      <tt>v3</tt>). If the <tt>v2</tt> release is to be used (e.g. for
      understanding and fixing a problem discovered in the running
      version) one will operate as follows :</p>
          
    <cmt:code>
csh&gt; cd &lt;some root&gt; 
csh&gt; mkdir Foo 
csh&gt; cd Foo 
csh&gt; cvs checkout -d v2 -r v2 Foo
csh&gt; cd v2/cmt 
csh&gt; cmt config 
csh&gt; source setup.csh 
csh&gt; make </cmt:code>

  </cmt:section>

</cmt:section>

<cmt:section title="Interfacing an external package with CMT">

  <p>Very often, external packages (typically commercial products, or
  third party software) are to be used by packages developped in the
  context of the <tt>CMT</tt> environment. Although this can obviously
  done simply by specifying compiler or linker options internally to
  the client packages, it can be quite powerful to interface these
  so-called <i>external</i> packages to <tt>CMT</tt> by defining a
  <i>glue</i> package, where configuration specifications for this
  external package are detailed.</p>

  <p>Using this approach, one may : </p>

        <ul> 
          <li> 
            provide a <i>nickname</i> for this external package, 
          </li> 
          <li> 
            adapt the version tag convention consistently to the
            project, hiding the version tag specificities of
            eg. commercial packages.
          </li> 
          <li> 
            provide compiler options using the the standard make macros 
            <tt>&lt;package>_cflags</tt>, <tt>&lt;package>_cppflags</tt> 
            or <tt>&lt;package>_fflags</tt>, 
          </li> 
          <li> 
            specify a set of search paths for the include files, using 
            the <tt>include_dirs</tt> statement, 
          </li> 
          <li> 
            provide linker options using the the standard make macros 
            <tt>&lt;package>_linkopts</tt> 
          </li> 
        </ul> 

        Let's consider the example of the <tt>OPACS</tt> package. This 
        package is provided outside of the <tt>CMT</tt> 
        environment. Providing a directory tree following the 
        <tt>CMT</tt> conventions (ie. a branch named after the version 
        identifier, then an <tt>cmt</tt> branch) then a 
        <tt>&CMTrequirements;</tt> file, containing (among other statements 
        not shown for the sake of clarity) : 

<cmt:cmtcode>
package OPACS 

include_dirs ${Wo_root}/include ${Co_root}/include ${Xx_root}/include \
${Ho_root}/include ${Go_root}/include ${Xo_root}/include 

public 
macro OPACS_cflags      "-DHAS_XO -DHAS_XM" 
macro OPACS_cppflags    " $(OPACS_cflags) " 

macro OPACS_linkopts    "$(Wo_linkopts) $(Xo_linkopts) $(Go_linkopts) \
$(Glo_linkopts) $(Xx_linkopts) $(Ho_linkopts) $(Htmlo_linkopts) \
$(W3o_linkopts) $(Co_linkopts) $(X_linkopts)" </cmt:cmtcode>

        <p>Then every package or application, client of this 
          <tt>OPACS</tt> package would have just to provide a use 
          statement like : </p>

<cmt:cmtcode>
use OPACS v3 </cmt:cmtcode>

        <p>This procedure gives the complete benefit of the use 
          relationships between packages (a client application 
          transparently inherits all configuration specifications) while 
          keeping unchanged the original referenced package, allowing to 
          apply this approach even to commercial products so that they 
          may be integrated in resource usage surveys similarly to local 
          packages. </p>

</cmt:section> 

<cmt:section title="The installation area mechanism">

  <p>CMT proposes and implements a flexible architecture for
  installation areas, meant to group the results of the build process
  or any other information belonging to packages into shared disk
  spaces. The typical usage of such installation areas is classical
  and expect to make only visible to the clients of a given
  (sub-)project the results of the build process while hiding the
  details of the package sources.</p>

  <p>the basics of the mechanisms supported by CMT are the following:</p>
      
  <ol>

    <li><p></p>All mechanisms are customizable on a per-project basis,
    so as to easily follow the project specific conventions</li>

    <li><p></p>However CMT proposes a minimal default behaviour based on the
    concrete experience in large projects, as well as frequently met
    practices</li>

    <li><p></p>A typical well supported convention is to map the set of
    installation areas onto the set of CMTPATH entries, associating the
    concept of CMTPATH splitting with the sub-project
    organization</li>

    <li><p></p>A typical consequence of this approach is that many
    configuration parameters need to be set according to the list of
    CMTPATH items. Eg on a Unix system, if one expects to find shared
    libraries in every installation area, each of them being created
    in a corresponding CMTPATH entry, one also expects to have
    LD_LIBRARY_PATH entries accordingly. The mechanism of
    <tt>cmtpath_pattern</tt> is exactly designed for that.</li>

    <li><p></p>The mechanism easily supports the extension for installing
    binary files (libraries, applications, java classes), runtime
    files, documentation and header files.</li>
        
  </ol>

  <cmt:section title="The default implementation"> 

    <p>It is provided in terms of</p>

    <ol>

      <li>

        <p></p>
        A set of <tt>cmtpath_pattern</tt>s defined in the CMT requirements
        file. This can be displayed using the command

	<cmt:code>
&gt; cmt show cmtpath_patterns</cmt:code>

      </li>

      <li>

        <p></p>
        A consistent set of actions added to the following make_fragments

	<table>
	  <tr><td>application</td><td>applications</td></tr>
	  <tr><td>library</td><td>shared libraries</td></tr>
	  <tr><td>library_no_share</td><td>static libraries</td></tr>
	  <tr><td>java_header</td><td>Java applications</td></tr>
	  <tr><td>jar</td><td>Java libraries</td></tr>
	</table>

      </li>

      <li>
        <p></p>
        <p>One shell script for installing or uninstalling files or directories</p>

	<cmt:code>
${CMTROOT}/mgr/cmt_install_action.sh
${CMTROOT}/mgr/cmt_uninstall_action.sh
${CMTROOT}/mgr/cmt_install_action.bat
${CMTROOT}/mgr/cmt_uninstall_action.bat</cmt:code>

      </li>

      <p>The default architecture of this installation scheme is by
      default set for each CMTPATH entry to:</p>

      <cmt:code>
&lt;path&gt;/InstallationArea/$(tag)/bin/...                [1]
                       /$(tag)/lib/...                [2]
                       /include/&lt;package&gt;/...         [3]
                       /share/bin/...                 [4]
                       /share/lib/...                 [5]
                             /...                     [6]
                       /doc/&lt;package&gt;/...             [7]
                           /...                       [8]</cmt:code>

      <ol>
        <li>Platform dependent executables</li>
        <li>Platform dependent libraries</li>
        <li>Public header files </li>
        <li>Platform independent applications (eg Java applications)</li>
        <li>Platform independent libraries (eg Java libraries)</li>
        <li>other platform independent files</li>
        <li>package specific documentations</li>
        <li>project-wide documentation</li>
      </ol>

    </ol>

    <p>The cmtpath_patterns are designed in this implementation for
    constructing a proper and consistent sequence of system specific
    environment variables (eg PATH, LD_LIBRARY_PATH, CLASSPATH) as
    well as compiler or linker options so as to transparently refer to
    the installation area only when it is appropriate to ovverride the
    local patterns.</p>

  </cmt:section> 
     
  <cmt:section title="Tuning the installation area mechanisms">

    <p>First of all every individual sub-project may activate or
    inhibit the installation area mechanisms using the
    <tt>build_strategy</tt> statement, with either
    <tt>with_installarea</tt> or <tt>without_installarea</tt>
    option.</p>

    <p>Then a dedicated tag materializes the selected strategy:
    <tt>&lt;project&gt;_with_installarea</tt> or
    <tt>&lt;project&gt;_without_installarea</tt></p>

    <p>This tag set will be used in various macro or set definitions
    to produce or not the appropriate values</p>

    <p>CMT manipulate some standard macros or environment variables
    according to the effective strategy:</p>

    <table border="1">
      <tr>
        <td><center><i>name</i></center></td>
        <td><center><i>purpose</i></center></td>
        <td><center><i>default</i></center></td>
      </tr>

      <tr>
        <td><tt>cmt_installarea_prefix</tt></td>
        <td>The default prefix for all projects</td>
        <td><tt>InstallArea</tt></td>
      </tr>

      <tr>
        <td><tt>&lt;project&gt;_installarea_prefix</tt></td>
        <td>The prefix for a given sub-project</td>
        <td><tt>$(cmt_installarea_prefix)</tt></td>
      </tr>

      <tr>
        <td><tt>&lt;project&gt;_installarea_prefix_remove</tt></td>
        <td>The regexp pattern to cleanup symbols</td>
        <td><tt>$(&lt;project&gt;_installarea_prefix)</tt></td>
      </tr>

      <tr>
        <td><tt>cmt_installarea_linkopts</tt></td>
        <td>Implicit linker options due to the installation area</td>
        <td>...</td>
      </tr>

      <tr>
        <td><tt>PATH</tt></td>
        <td>Accessing the executables in the installation area</td>
        <td>...</td>
      </tr>

      <tr>
        <td><tt>LD_LIBRARY_PATH</tt></td>
        <td>Accessing the shared libraries in the installation area</td>
        <td>...</td>
      </tr>

      <tr>
        <td><tt>CLASSPATH</tt></td>
        <td>Accessing the jar files in the installation area</td>
        <td>...</td>
      </tr>

<!--
      <tr>
        <td><tt></tt></td>
        <td></td>
        <td></td>
      </tr>
-->

    </table>

    <p></p>

  </cmt:section> 

</cmt:section>

<cmt:section title="Installing CMT for the first time">

        <P>These sections are of interest only if <tt>CMT</tt> is not yet 
          installed on your site, of if you need a private 
          installation. </P> 

        <P>The first question you need to answer is the location where 
          to install <tt>CMT</tt>. This location is typically a disk area where 
          most of packages managed in your project will be located. </P> 

        <P>Then, you have to fetch the distribution kit from the Web at 
	  <A HREF="http://www.cmtsite.org">http://www.cmtsite.org</A>. You 
          must get at least the primary distribution kit containing the 
          basic configuration information and the <tt>CMT</tt> sources. This 
          operation results in a set of directories hanging below the <tt>CMT</tt> 
          root and the version directory. The src branch contains the 
          sources of <tt>CMT</tt>, the fragments branch contains the makefile 
          fragments and the mgr branch contains the scripts needed to build 
          or operate <tt>CMT</tt>. </P> 

        <cmt:section title="Installing CMT on your Unix site">

          <P>The very first operation after dowloading <tt>CMT</tt>
          consists in running the <tt>INSTALL</tt> shell script. This
          will build the setup scripts required by any <tt>CMT</tt>
          user. </P>
            <P>Then you may either decide to build <tt>CMT</tt> by yourself or fetch 
            a pre-built binary from the same Web location. The prebuilt 
            binary versions may not exist for the actual platform you are 
            working on. You will see on the distribution page the precise 
            configurations used for building those binaries. </P> 

          <P>In case you have to build <tt>CMT</tt> yourself, you need a C++ 
            compiler capable of handling templates (although the support for 
            STL is not required). There is a Makefile provided in the 
            distribution kit which takes g++ by default as the compiler. If 
            you need a specific C++ compiler you will override the cpp macro 
            as follows: </P> 

<cmt:code>
sh&gt; gmake cpp=CC </cmt:code>

          <P>The <tt>cppflags</tt> macro can also be used to override the
            behaviour of the compilation. </P>

          <P>Another important concern is the way <tt>CMT</tt> will identify the 
            platform. <tt>CMT</tt> builds a configuration tag per each type of 
            platform, and uses this tag for naming the directory where all 
            binary files will be stored. As such this tag has to be defined 
            prior to even build <tt>CMT</tt> itself. </P> 

          <P><tt>CMT</tt> builds the default configuration by running the 
            cmt_system.sh script found in the mgr branch of <tt>CMT</tt>. Run it 
            manually to see what is the default value provided by this 
            script. You might consider changing its algorithm for your own 
            convenience. </P> 

          <p>A distribution kit may be obtained at the following URL : </p>

<cmt:code>
http://www.cmtsite.org</cmt:code>

          <p>Once the <tt>tar</tt> file has been downloaded, the 
            following operations must be achieved : </p>

          <ol> 
            <li> 
              Select a root directory where to install 
              <tt>CMT</tt>. Typically this will correspond to a 
              development area or a public distribution area. 
            </li> 
            <li> 
              Import the distribution kit mentioned above. 
            </li> 
            <li> 
              Uncompress and untar it. 
            </li> 
            <li> 
              Configure <tt>CMT</tt>. 
            </li> 
            <li> 
              CMT is ready to be used for developing packages. 
            </li> 
          </ol> 

          <p>A typical corresponding session could look like : </p>

<cmt:code>
csh&gt; cd /Packages 
csh&gt; &lt;get the tar file from the Web&gt; 
csh&gt; tar xzf CMT&CMTVersion;.tar.gz 
csh&gt; cd CMT/&CMTVersion;/mgr 
csh&gt; ./INSTALL 
csh&gt; source setup.csh 
csh&gt; gmake</cmt:code>

        </cmt:section> 

        <cmt:section title="Installing CMT on a Windows or Windows NT site">

          <p>You first have to fetch the distribution kit from the Web at 
            <A 
              HREF="http://www.cmtsite.org">http://www.cmtsite.org</A>. You 
            must get at least the primary distribution kit containing the 
            basic configuration information and the <tt>CMT</tt> sources. This 
            operation results in a set of directories hanging below the <tt>CMT</tt> 
            root and the version directory. The binary kit provided for 
            Windows environments will generally fit your needs. </p> 

          <p>You should consider getting the pre-compiled (for a Windows
            environment) applications, and especially the
            <tt>..\VisualC\install.exe</tt> application, which interactively
            configures the registry entries as described in the
            next paragraph.</p>

          <p>The next operation consists in defining a few registries
            (typically using the standard RegEdit facility or the
            <tt>install.exe</tt> special application): </p>

          <UL> 

            <li>HKEY_LOCAL_MACHINE/Software/CMT/root will contain the root 
              directory where <tt>CMT</tt> is installed (eg. "e:"). </li> 

            <li>HKEY_LOCAL_MACHINE/Software/CMT/version will contain the 
              current version tag of <tt>CMT</tt> ("&CMTVersion;" for this version). </li> 

            <li>HKEY_LOCAL_MACHINE/Software/CMT/path/ may optionally 
              contain a set of text values corresponding to the different 
              package global access paths. </li> 

            <li>HKEY_LOCAL_MACHINE/Software/CMT/site will contain the 
              conventional site name. </li> 

            <li>HKEY_CURRENT_USER/Software/CMT/path/ may contain a set of 
              text of text values corresponding to the different package 
              private access paths. </li> 
          </UL> 

          <p>CMT can also be configured to run on DOS-based environments
            using the <tt>nmake</tt> facility. In this case, the installation
            procedure is very similar to the Unix one:</p>

          <p>A typical corresponding session could look like : 

<cmt:code>
dos&gt; cd Packages 
dos&gt; &lt;get the tar file from the Web&gt; 
dos&gt; cd CMT\&CMTVersion;\mgr 
dos&gt; call INSTALL 
dos&gt; call setup.bat
dos&gt; nmake /f nmake</cmt:code>

          </p>

        </cmt:section> 

</cmt:section> 

<cmt:section title="Appendices">

<cmt:section title='Copyright'>

<center><b>Copyright LAL and Christian Arnault LAL-Orsay CNRS</b></center>

<center><tt>arnault@lal.in2p3.fr</tt></center>

<p>This software is a computer program whose purpose is to describe and
manage software configuration activities.</p>

<p>This software is governed by the CeCILL  license under French law and
abiding by the rules of distribution of free software.  You can  use, 
modify and/ or redistribute the software under the terms of the CeCILL
license as circulated by CEA, CNRS and INRIA at the following URL
<center><a href="http://www.cecill.info"><cmt:code>http://www.cecill.info</cmt:code></a></center> </p>

<p>As a counterpart to the access to the source code and  rights to copy,
modify and redistribute granted by the license, users are provided only
with a limited warranty  and the software's author,  the holder of the
economic rights,  and the successive licensors  have only  limited
liability. </p>

<p>In this respect, the user's attention is drawn to the risks associated
with loading,  using,  modifying and/or developing or reproducing the
software by the user in light of its specific status of free software,
that may mean  that it is complicated to manipulate,  and  that  also
therefore means  that it is reserved for developers  and  experienced
professionals having in-depth computer knowledge. Users are therefore
encouraged to load and test the software's suitability as regards their
requirements in conditions enabling the security of their systems and/or 
data to be ensured and,  more generally, to use and operate it in the 
same conditions as regards security. </p>

<p>The fact that you are presently reading this means that you have had
knowledge of the CeCILL license and that you accept its terms.</p>


</cmt:section>

<cmt:section title="Standard make targets predefined in CMT">

  <p>These targets can always be listed through the following command : </p>

  <cmt:code>
sh&gt; gmake help </cmt:code>

  <p> 
    <table BORDER='1' COLS='2'> 
      <tr> 
        <td width="200"> 
          <center><i>target</i></center> 
        </td> 
        <td width="500"> 
          <center><i>usage</i></center> 
        </td> 
      </tr> 
      <tr> 
        <td><tt>help</tt></td> 
        <td >Get the list of possible make target for this package.</td> 
      </tr> 
      <tr> 
        <td><tt>all</tt></td> 
        <td >build all components of this package.</td> 
      </tr> 
      <tr> 
        <td><tt>clean</tt></td> 
        <td>remove everything that can be rebuilt by make</td> 
      </tr> 
      <tr> 
        <td><tt>binclean</tt></td> 
        <td>completely remove the <tt>../$(tag)</tt> binary directory</td> 
      </tr> 
      <tr> 
        <td><tt>configclean</tt></td> 
        <td>remove all intermediate makefile fragments</td> 
      </tr> 
      <tr> 
        <td><tt>install</tt></td> 
        <td>install binaries of this package to the current installation area</td> 
      </tr> 
      <tr> 
        <td><tt>uninstall</tt></td> 
        <td>uninstall binaries of this package from the current installation area</td> 
      </tr> 
      <tr> 
        <td><tt>check</tt></td> 
        <td>run all applications defined with the -check option</td> 
      </tr> 
      <tr> 
        <td><i>component-name</i></td>
        <td>only build this 
          particular component (as opposed to the <tt>all</tt> 
          target that tries to build all components of this 
          package)</td> 
      </tr> 
      <tr>
        <td><i>group-name</i></td>
        <td>build all constituents
                belonging to this group (ie. those defined using the same
                -group=&lt;group-name&gt; option)</td>
      </tr>
    </table> 
  </p>
  <p>These targets have to be specified as follows : </p>

  <cmt:code>
sh&gt; gmake clean 
sh&gt; gmake Foo </cmt:code>

</cmt:section> 

<cmt:section title="Standard macros predefined in CMT">

  <cmt:section title="CMT static macros">

    These macros provide static data about CMT itself. They cannot be
    modified by the user.

    <p>
      <table BORDER='1' COLS='3'> 
        <tr> 
          <td width="150"> 
            <center><i>macro</i></center> 
          </td> 
          <td width="300"> 
            <center><i>usage</i></center> 
          </td> 
          <td width="200"> 
            <center><i>default value</i></center> 
          </td> 
        </tr> 
        <tr> 
          <td><tt>CMTrelease</tt></td> 
          <td>gives the current release number of CMT</td> 
          <td><tt>&CMTrelease;</tt></td> 
        </tr> 
        <tr> 
          <td><tt>CMTVERSION</tt></td> 
          <td>gives the current complete version tag of CMT</td> 
          <td><tt>&CMTVersion;</tt></td> 
        </tr> 
      </table> 
    </p>

  </cmt:section>

  <cmt:section title="Structural macros">

    These macros describe the structural conventions followed by
    <tt>CMT</tt>. They receive a conventional default value from the
    <tt>CMT</tt> requirements file. However, they can be overridden in
    any package for its own needs.

    <p>
      <table BORDER='1' COLS='3'> 
        <tr> 
          <td width="150"> 
            <center><i>macro</i></center> 
          </td> 
          <td width="300"> 
            <center><i>usage</i></center> 
          </td> 
          <td width="200"> 
            <center><i>default value</i></center> 
          </td> 
        </tr> 
        <tr> 
          <td><tt>tag</tt></td> 
          <td>gives the binary tag</td> 
          <td><tt>${CMTCONFIG}</tt></td> 
        </tr> 
        <tr> 
          <td><tt>src</tt></td>
          <td>the src branch</td> 
          <td><tt>../src/</tt></td> 
        </tr> 
        <tr> 
          <td><tt>inc</tt></td> 
          <td>the include branch</td> 
          <td><tt>../src/</tt></td> 
        </tr> 
        <tr> 
          <td><tt>mgr</tt></td> 
          <td>the cmt or mgr branch</td> 
          <td><tt>../cmt/</tt> or <tt>../mgr/</tt></td> 
        </tr> 
        <tr> 
          <td><tt>bin</tt></td> 
          <td>the branch for binaries</td> 
          <td><tt>../$(&lt;package&gt;_tag)/</tt></td> 
        </tr> 
        <tr> 
          <td><tt>javabin</tt></td> 
          <td>the branch for java classes</td> 
          <td><tt>../classes/</tt></td> 
        </tr> 
        <tr> 
          <td><tt>doc</tt></td> 
          <td>the doc branch</td> 
          <td><tt>../doc/</tt></td> 
        </tr> 
        <tr> 
          <td><tt>cmt_hardware</tt></td> 
          <td>the description of the current hardware</td> 
          <td><tt>&lt;none&gt;</tt></td> 
        </tr> 
        <tr> 
          <td><tt>cmt_system_version</tt></td> 
          <td>the version of the current OS</td> 
          <td><tt>&lt;none&gt;</tt></td> 
        </tr> 
        <tr> 
          <td><tt>cmt_compiler_version</tt></td> 
          <td>the version of the currently visible C++ compiler </td> 
          <td><tt>&lt;none&gt;</tt></td> 
        </tr> 
      </table> 
    </p>

  </cmt:section>

  <cmt:section title="Language related macros">

    These macros are purely conventional. They are expected in the
    various make fragments available from <tt>CMT</tt> itself for
    providing the various building actions.

    <p>During the mechanism of new language declaration and definition
    available in the <tt>CMT</tt> syntax, developers are expected to
    define similar conventions for corresponding actions.</p>

    <p> Their default values are originally defined inside the
    &CMTrequirements; file of the <tt>CMT</tt> package itself but can be
    <i>redefined</i> by providing a new definition in the package's
    requirements file using the <tt>macro</tt> statement. The original
    definition can be <i>completed</i> using the <tt>macro_append</tt>
    or <tt>macro_prepend</tt> statements.</p>

    <p> 
      <table BORDER='1' COLS='3'> 
        <tr> 
          <td width="150"> 
            <center><i>macro</i></center> 
          </td> 
          <td width="300"> 
            <center><i>usage</i></center> 
          </td> 
          <td width="200"> 
            <center><i>default value</i></center> 
          </td> 
        </tr> 
        <tr> 
          <td><tt>cc</tt></td> 
          <td>The C compiler</td> 
          <td><tt>cc</tt></td> 
        </tr> 
        <tr> 
          <td><tt>ccomp</tt></td> 
          <td>The C compiling command</td> 
          <td><tt>$(cc) -c -I$(inc) $(includes) $(cflags)</tt></td> 
        </tr> 
        <tr> 
          <td><tt>clink</tt></td> 
          <td>The C linking command</td> 
          <td><tt>$(cc) $(clinkflags)</tt></td> 
        </tr> 
        <tr> 
          <td><tt>cflags</tt></td> 
          <td>The C compilation flags</td> 
          <td><i>none</i> </td> 
        </tr> 
        <tr> 
          <td><tt>pp_cflags</tt></td> 
          <td>The preprocessor flags for C</td> 
          <td><i>none</i> </td> 
        </tr> 
        <tr> 
          <td><tt>clinkflags</tt></td> 
          <td>The C link flags</td> 
          <td><i>none</i> </td> 
        </tr> 
      </table> 
    </p>
    <p> 
      <table BORDER='1' COLS='3'> 
        <tr> 
          <td width="150"><tt>cpp</tt></td> 
          <td width="300">The C++ compiler</td> 
          <td width="200"><tt>g++</tt></td> 
        </tr> 
        <tr> 
          <td width="150"><tt>preproc</tt></td> 
          <td width="300">The C++ preprocessor</td> 
          <td width="200"><tt>g++ -MD -c </tt></td> 
        </tr> 
        <tr> 
          <td><tt>cppcomp</tt></td> 
          <td>The C++ compiling command</td> 
          <td><tt>$(cpp) -c -I$(inc) $(includes) $(cppflags)</tt></td> 
        </tr> 
        <tr> 
          <td><tt>cpplink</tt></td> 
          <td>The C++ linking command</td> 
          <td><tt>$(cpp) $(cpplinkflags)</tt></td> 
        </tr> 
        <tr> 
          <td><tt>cppflags</tt></td> 
          <td>The C++ compilation flags</td> 
          <td><i>none</i> </td> 
        </tr> 
        <tr> 
          <td><tt>pp_cppflags</tt></td> 
          <td>The preprocessor flags for C++</td> 
          <td><i>none</i> </td> 
        </tr> 
        <tr> 
          <td><tt>cpplinkflags</tt></td> 
          <td>The C++ link flags</td> 
          <td><i>none</i> </td> 
        </tr> 
      </table> 
    </p>
    <p> 
      <table BORDER='1' COLS='3'> 
        <tr> 
          <td width="150"><tt>for</tt></td> 
          <td width="300">The Fortran compiler</td> 
          <td width="200"><tt>f77</tt></td> 
        </tr> 
        <tr> 
          <td><tt>fcomp</tt></td> 
          <td>The Fortran compiling command</td> 
          <td><tt>$(for) -c -I$(inc) $(includes) $(fflags)</tt></td> 
        </tr> 
        <tr> 
          <td><tt>flink</tt></td> 
          <td>The Fortran linking command</td> 
          <td><tt>$(for) $(clinkflags)</tt></td> 
        </tr> 
        <tr> 
          <td><tt>fflags</tt></td> 
          <td>The Fortran compilation flags</td> 
          <td><i>none</i> </td> 
        </tr> 
        <tr> 
          <td><tt>pp_fflags</tt></td> 
          <td>The preprocessor flags for fortran</td> 
          <td><i>none</i> </td> 
        </tr> 
        <tr> 
          <td><tt>flinkflags</tt></td> 
          <td>The Fortran link flags</td> 
          <td><i>none</i> </td> 
        </tr> 
        <tr> 
          <td><tt>ppcmd</tt></td> 
          <td>The include file command for Fortran</td> 
          <td><tt>-I</tt></td> 
        </tr> 
      </table> 
    </p>
    <p> 
      <table BORDER='1' COLS='3'> 
        <tr> 
          <td width="150"><tt>javacomp</tt></td> 
          <td width="300">The java compiling command</td> 
          <td width="200"><tt>javac</tt></td> 
        </tr> 
        <tr> 
          <td width="150"><tt>jar</tt></td> 
          <td>The java archiver command</td> 
          <td><tt>jar</tt></td> 
        </tr> 
      </table> 
    </p>
    <p> 
      <table BORDER='1' COLS='3'> 
        <tr> 
          <td width="150"><tt>lex</tt></td> 
          <td width="300">The Lex command</td> 
          <td width="200"><tt>lex $(lexflags)</tt></td> 
        </tr> 
        <tr> 
          <td><tt>lexflags</tt></td> 
          <td>The Lex flags</td> 
          <td><i>none</i> </td> 
        </tr> 
        <tr> 
          <td><tt>yacc</tt></td> 
          <td>The Yacc command</td> 
          <td><tt>yacc $(yaccflags)</tt></td> 
        </tr> 
        <tr> 
          <td><tt>yaccflags</tt></td> 
          <td>The Yacc flags</td> 
          <td><i>none</i> </td> 
        </tr> 
        <tr> 
          <td><tt>ar</tt></td> 
          <td>The archive command</td> 
          <td><tt>ar -clr</tt></td> 
        </tr> 
        <tr> 
          <td><tt>ranlib</tt></td> 
          <td>The ranlib command</td> 
          <td>r<tt>anlib</tt></td> 
        </tr> 
      </table> 
    </p>

  </cmt:section>

  <cmt:section title="Package customizing macros">

    These macros do not receive default values. They are all prefixed
    by the package name. They are meant to provide specific variant to
    the corresponding generic language related macros.

    <p>They are automatically and by default concatenated by
    <tt>CMT</tt> to fill in the corresponding global <i>use</i> macros
    (see appendix on <A HREF="#Generated macros">generated
    macros</A>). However, this concatenation mechanism is discarded
    when the <tt>-no_auto_imports</tt> option is specified in the
    corresponding use statement.</p>

    <p> 
      <table BORDER='1' COLS='2'> 
        <tr> 
          <td width="250"> 
            <center><i>macro</i></center> 
          </td> 
          <td width="400"> 
            <center><i>usage</i></center> 
          </td> 
        </tr>
        <tr> 
          <td><tt>&lt;<i>package</i>&gt;_cflags</tt></td> 
          <td>specific C flags</td> 
        </tr> 
        <tr> 
          <td><tt>&lt;<i>package</i>&gt;_pp_cflags</tt></td> 
          <td>specific C preprocessor flags</td> 
        </tr> 
        <tr> 
          <td><tt>&lt;<i>package</i>&gt;_cppflags</tt></td> 
          <td>specific C++ flags</td> 
        </tr> 
        <tr> 
          <td><tt>&lt;<i>package</i>&gt;_pp_cppflags</tt></td> 
          <td>specific C++ preprocessor flags</td> 
        </tr> 
        <tr> 
          <td><tt>&lt;<i>package</i>&gt;_fflags</tt></td> 
          <td>specific Fortran flags</td> 
        </tr> 
        <tr> 
          <td><tt>&lt;<i>package</i>&gt;_pp_fflags</tt></td> 
          <td>specific Fortran preprocessor flags</td> 
        </tr> 
        <tr> 
          <td><tt>&lt;<i>package</i>&gt;_libraries</tt></td> 
          <td>
            gives the (space separated) list of library names exported by this
            package. This list is typically used in the 
            <tt>cmt build library_links</tt> command.
          </td>
        </tr> 
        <tr> 
          <td><tt>&lt;<i>package</i>&gt;_linkopts</tt></td> 
          <td>
            provide the linker options required by any application willing to 
            access the different libraries offered by the 
            package. This may include support for several libraries 
            per package. 

            <p> 
              A typical example of how to define such a macro could be : </p>

            <cmt:cmtcode>
macro Cm_linkopts "-L$(CMROOT)/$(Cm_tag) -lCm -lm" </cmt:cmtcode>

          </td>
        </tr> 
        <tr> 
          <td><tt>&lt;<i>package</i>&gt;_stamps</tt></td> 
          <td>

            may contain a list of <i>stamp</i> file names (or make
            targets). Whenever a library is modified, one dedicated
            stamp file is re-created, simply to mark the
            reconstruction date. The name of this stamp file is
            conventionally <tt>&lt;<i>library</i>&gt;.stamp</tt>.  Thus,
            a typical definition for this macro could be :

            <cmt:cmtcode>
macro Cm_stamps "$(Cm_root)/$(Cm_tag)/Cm.stamp" </cmt:cmtcode>

            <p>Then, these stamp file references are accumulated
              into the standard macro named <tt>use_stamps</tt> which is
              always installed within the dependency list for
              applications, so that whenever one of the libraries used
              from the hierarchy of used packages changes, the
              application will be automatically rebuilt.</p>
           </td>
        </tr> 
      </table>
    </p>

    <p>The following macros are not subject to automatic concatenation
    (and therefore are not hidden by the <tt>-no_auto_imports</tt>
    modifier).</p>

    <p> 
      <table BORDER='1' COLS='2'> 
        <tr> 
          <td width="250"> 
            <center><i>macro</i></center> 
          </td> 
          <td width="400"> 
            <center><i>usage</i></center> 
          </td> 
        </tr>

        <tr> 
          <td><tt>&lt;<i>package</i>&gt;_native_version</tt></td> 

          <td>specifies the native version of the external package
          referenced by this <i>interface</i> package.<br/>When this
          macro is provided, its value is displayed by the <tt>cmt show
          uses</tt> command</td>

        </tr>

        <tr> 
          <td><tt>&lt;<i>package</i>&gt;_export_paths</tt></td> 
          <td>specifies the list of files or directories that
          should be exported during the deployment process for
          this package. Generally this is only useful for glue
          packages refering to external software</td>

        </tr>
        <tr> 

          <td><tt>&lt;<i>package</i>&gt;_home</tt></td> 

          <td>specifies the base location for external software
          described in glue packages. This macro is generally used to
          specify the previous one</td>

        </tr>
      </table>
    </p>

  </cmt:section>

  <cmt:section title="Constituent specific customizing macros">

    These macros do not receive any default values (ie they are empty
    by default). They are meant to provide for each constituent,
    specific variants to the corresponding generic language related
    macros.

    <p>By convention, they are all prefixed by the constituent
    name. But macros used for defining compiler options are in
    addition prefixed by the constituent type (either <tt>lib_</tt>,
    <tt>app_</tt> or <tt>doc_</tt>).</p>

    <p>They are used in the various make fragments for fine
    customization of the build command parameters.</p>

    <p> 
      <table BORDER='1' COLS='2'> 
        <tr> 
          <td><tt>&lt;<i>type</i>&gt;_&lt;<i>constituent</i>&gt;_cflags</tt></td> 
          <td WIDTH="400">specific C flags</td>
        </tr> 
        <tr> 
          <td><tt>&lt;<i>type</i>&gt;_&lt;<i>constituent</i>&gt;_pp_cflags</tt></td> 
          <td>specific C preprocessor flags</td>
        </tr> 
        <tr> 
          <td><tt>&lt;<i>type</i>&gt;_&lt;<i>constituent</i>&gt;_cppflags</tt></td> 
          <td>specific C++ flags</td>
        </tr> 
        <tr> 
          <td><tt>&lt;<i>type</i>&gt;_&lt;<i>constituent</i>&gt;_pp_cppflags</tt></td> 
          <td>specific C++ preprocessor flags</td>
        </tr> 
        <tr> 
          <td><tt>&lt;<i>type</i>&gt;_&lt;<i>constituent</i>&gt;_fflags</tt></td> 
          <td>specific Fortran flags</td>
        </tr> 
        <tr> 
          <td><tt>&lt;<i>type</i>&gt;_&lt;<i>constituent</i>&gt;_pp_fflags</tt></td> 
          <td>specific Fortran preprocessor flags</td>
        </tr> 
        <tr> 
          <td><tt>&lt;<i>constituent</i>&gt;linkopts</tt></td> 
          <td>
            provides additional linker options to the application. It is
            complementary to - and should not be confused with - the
            <tt>&lt;<i>package</i>&gt;_linkopts</tt> macro, which
            provides exported linker options required by clients
            packages to use the package libraries.
          </td>
        </tr> 
        <tr> 
          <td><tt>&lt;<i>constituent</i>&gt;_shlibflags</tt></td> 
          <td>
            provides additional linker options used when building a
            shared library. Generally, a simple shared library does
            not need any external reference to be resolved at build
            time (it is in this case supposed to get its unresolved
            references from other shared libraries). However,
            (typically when one builds a dynamic loading capable
            component) it might be desired to statically link it
            with other libraries (making them somewhat private).
          </td>
        </tr> 
        <tr> 
          <td><tt>&lt;<i>constituent</i>&gt;_dependencies</tt></td> 
          <td>
            provides user defined dependency specifications for each
            constituent. The typical use of this macro is fill it
            with the name of the list of some other constituents
            which <i>have</i> to be rebuilt first (since each
            constituent is associated with a target with the same
            name). This is especially needed when one want to use
            the parallel gmake (ie. the -j option of gmake).
          </td>
        </tr> 
        <tr> 
          <td><tt>&lt;<i>group</i>&gt;_dependencies</tt></td> 
          <td>
            provides user defined dependency specifications for each
            group. The typical use of this macro is fill it
            with the name of the list of some other constituents
            which <i>have</i> to be rebuilt first (since each
            constituent is associated with a target with the same
            name). This is especially needed when one want to use
            the parallel gmake (ie. the -j option of gmake).
          </td>
        </tr> 
      </table> 
    </p>

  </cmt:section>

  <cmt:section title="Source specific customizing macros">

    These macros do not receive any default values (ie they are empty
    by default). They are meant to provide for each source file,
    specific variants to the corresponding generic language related
    macros.

    <p>By convention, they are all prefixed by the source file name
    followed by the source file suffix (either <tt>_c</tt>, <tt>_cxx</tt>,
    <tt>_f</tt>, etc.)</p>

    <p>They are used in the various make fragments for fine
    customization of the build command parameters.</p>

    <p> 
      <table BORDER='1' COLS='2'> 
        <tr> 
          <td WIDTH="300"><tt>&lt;<i>constituent</i>&gt;_&lt;<i>suffix</i>&gt;_cflags</tt></td> 
          <td WIDTH="300">specific C flags</td>
        </tr> 
        <tr> 
          <td><tt>&lt;<i>constituent</i>&gt;_&lt;<i>suffix</i>&gt;_cppflags</tt></td> 
          <td>specific C++ flags</td>
        </tr> 
        <tr> 
          <td><tt>&lt;<i>constituent</i>&gt;_&lt;<i>suffix</i>&gt;_fflags</tt></td> 
          <td>specific Fortran flags</td>
        </tr> 
      </table> 
    </p>

  </cmt:section>

  <cmt:section title="Generated macros">

    <p> These macros are automatically <i>generated</i> when any cmt
    connand is run (and thus when <tt>make</tt> is run).</p>

    <p>The first set of them provide constant values corresponding to
    <tt>CMT</tt> based information. They are not meant to be overridden
    by the user, since they serve as a communication mean between
    <tt>CMT</tt> and the user.</p>

    <p>
      <table BORDER='1' COLS='2'> 
        <tr> 
          <td width="200"><tt>&lt;<i>PACKAGE</i>&gt;ROOT</tt></td> 
          <td width="400">The access path of the package (including the version branch)</td> 
        </tr> 
        <tr> 
          <td><tt>&lt;<i>package</i>&gt;_root</tt></td> 

          <td>The access path of the package (including the
          version branch). This macro is very similar to the
          <tt>&lt;<i>PACKAGE</i>&gt;ROOT</tt> macro except that
          it tries to use a relative path instead of an
          absolute one. </td>
         </tr> 
        <tr> 
          <td><tt>&lt;<i>PACKAGE</i>&gt;VERSION</tt></td>
          <td>The used version of the package</td> 
        </tr> 
        <tr> 
          <td><tt>PACKAGE_ROOT</tt></td> 
          <td>The access path of the current package (including the version branch)</td> 
        </tr> 
        <tr> 
          <td><tt>package</tt></td> 
          <td>The name of the current package</td> 
        </tr> 
        <tr> 
          <td><tt>version</tt></td> 
          <td>The version tag of the current package</td> 
        </tr> 
        <tr> 
          <td><tt>package_offset</tt></td> 
          <td>The directory offset of the current package</td> 
        </tr> 
        <tr> 
          <td><tt>package_cmtpath</tt></td> 
          <td>The package area where the current package has been found</td> 
        </tr> 
        <tr> 
          <td><tt>&lt;<i>package</i>&gt;_project</tt></td> 
          <td>The project name to which the corresponding package belongs</td> 
        </tr> 
        <tr> 
          <td><tt>&lt;<i>package</i>&gt;_cmtpath</tt></td> 
          <td>The package area where the corresponding package has been found</td> 
        </tr> 
        <tr> 
          <td><tt>&lt;<i>package</i>&gt;_offset</tt></td> 
          <td>The directory offset of the corresponding package</td> 
        </tr> 
      </table> 
    </p>
    <p>The second set is deduced from the context and from the
      requirements file of the package. They can be overridden by
      the user so as to customize the <tt>CMT</tt> behaviour.</p>
    <p>
      <table BORDER='1' COLS='2'> 
        <tr> 
          <td><tt>&lt;<i>package</i>&gt;_tag</tt></td> 
          <td width="400">The specific configuration tag for the package. By default it is set to $(tag) but can be freely overridden</td> 
        </tr> 
        <tr> 
          <td><tt>constituents</tt></td> 
          <td>The ordered set of constituents declared without any group option</td> 
        </tr> 
        <tr> 
          <td><tt><i>&lt;group-name&gt;</i>_constituents</tt></td> 
          <td>The ordered set of all constituents declared using a group=&lt;group-name&gt; option</td> 
        </tr> 
      </table> 
    </p>

    <p>The third set of generated macros are the <i>global use
    macros</i>.  They correspond to the concatenation of the
    corresponding package specific customizing options that can be
    deduced from the ordered set of <i>use</i> statements found in the
    requirements file (taking into account the complete hierarchy of
    used packages with the exception of those specified with the
    <br/><tt>-no_auto_imports</tt> option in their use statement) :</p>

    <p>
      <table BORDER='1' COLS='2'> 
        <tr> 
          <td width="150"><tt>use_cflags</tt></td> 
          <td width="400">C compiler flags</td> 
        </tr> 
        <tr> 
          <td><tt>use_pp_cflags</tt></td> 
          <td>Preprocessor flags for the C language</td> 
        </tr> 
        <tr> 
          <td><tt>use_cppflags</tt></td> 
          <td>C++ compiler flags</td> 
        </tr> 
        <tr> 
          <td><tt>use_pp_cppflags</tt></td> 
          <td>Preprocessor flags for the C++ language</td> 
        </tr> 
        <tr> 
          <td><tt>use_fflags</tt></td> 
          <td>Fortran compiler flags</td> 
        </tr> 
        <tr> 
          <td><tt>use_pp_fflags</tt></td> 
          <td>Preprocessor flags for the Fortran language</td> 
        </tr> 
        <tr> 
          <td><tt>use_libraries</tt></td> 
          <td>List of library names</td> 
        </tr> 
        <tr> 
          <td><tt>use_linkopts</tt></td> 
          <td>Linker options</td> 
        </tr> 
        <tr> 
          <td><tt>use_stamps</tt></td> 
          <td>Dependency stamps</td> 
        </tr> 
        <tr> 
          <td><tt>use_requirements</tt></td> 
          <td>The set of used requirements</td> 
        </tr> 
        <tr> 
          <td><tt>use_includes</tt></td> 
          <td>The set of include search paths options for the preprocessor from the used packages</td> 
        </tr> 
        <tr> 
          <td><tt>use_fincludes</tt></td> 
          <td>The set of include search paths options for the fortran preprocessor from the used packages</td> 
        </tr> 
        <tr> 
          <td><tt>includes</tt></td> 
          <td>The overall set of include search paths for the preprocessor</td> 
        </tr> 
        <tr> 
          <td><tt>fincludes</tt></td> 
          <td>The overall set of include search paths options for the fortran preprocessor</td> 
        </tr> 
      </table> 
    </p>

  </cmt:section> 

  <cmt:section title="Macros related with the installation area mechanisms">

    These macros contain the parameterisation of the installation area
    mechanisms.

    <p><font size="-10">
      <table BORDER='1' COLS='2'> 
        <tr> 
          <td width="250"> 
            <center><i>macro</i></center> 
          </td> 
          <td width="20"> 
            <center><i>usage</i></center> 
          </td> 
          <td width="300"> 
            <center><i>default value</i></center> 
          </td> 
        </tr>
         <tr> 
          <td><tt>cmt_installarea_command</tt></td> 
          <td>&nbsp;</td> 
          <td>&nbsp;</td> 
        </tr> 
        <tr> 
          <td><tt>cmt_uninstallarea_command</tt></td> 
          <td>&nbsp;</td> 
          <td>&nbsp;</td> 
        </tr> 
        <tr> 
          <td><tt>cmt_install_action</tt></td> 
          <td>&nbsp;</td> 
          <td><tt>$(CMTROOT)\mgr\cmt_install_action.bat</tt></td> 
        </tr> 
        <tr> 
          <td><tt>cmt_installdir_action</tt></td> 
          <td>&nbsp;</td>
          <td><tt>$(CMTROOT)\mgr\cmt_installdir_action.bat</tt></td>
        </tr> 
        <tr> 
          <td><tt>cmt_uninstall_action</tt></td> 
          <td>&nbsp;</td> 
          <td><tt>$(CMTROOT)\mgr\cmt_uninstall_action.bat</tt></td>
        </tr> 
        <tr> 
          <td><tt>cmt_uninstalldir_action</tt></td> 
          <td>&nbsp;</td> 
          <td><tt>$(CMTROOT)\mgr\cmt_uninstalldir_action.bat</tt></td>
        </tr> 
        <tr> 
          <td><tt>cmt_installdir_excludes</tt></td> 
          <td>&nbsp;</td> 
          <td><tt>$(CMTROOT)\mgr\cmt_installdir_excludes.txt</tt></td>
        </tr> 
        <tr> 
          <td><tt>cmt_installarea_prefix</tt></td> 
          <td>&nbsp;</td> 
          <td><tt>InstallArea</tt></td>
        </tr> 
        <tr> 
          <td><tt>&lt;project&gt;_installarea_prefix</tt></td> 
          <td>&nbsp;</td> 
          <td><tt>$(cmt_installarea_prefix)</tt></td>
        </tr> 
        <tr> 
          <td><tt>CMTINSTALLAREA</tt></td> 
          <td>&nbsp;</td> 
          <td><tt>C:\Arnault\test\tprojects\PC\InstallArea</tt></td>
        </tr> 
        <tr> 
          <td><tt>cmt_installarea_paths</tt></td> 
          <td>&nbsp;</td> 
          <td><tt>&nbsp;</tt></td> 
        </tr> 
        <tr> 
          <td><tt>cmt_installarea_linkopts</tt></td> 
          <td>&nbsp;</td> 
          <td><tt>&nbsp;</tt></td> 
        </tr> 

<!--

        <tr> 
          <td><tt></tt></td> 
          <td>&nbsp;</td> 
          <td><tt>&nbsp;</tt></td> 
        </tr> 
-->

      </table> 
    </font></p>

  </cmt:section> 

  <cmt:section title="Utility macros">

    These macros are used to specify the behaviour of various actions
    in CMT.

    <p>
      <table BORDER='1' COLS='2'> 
        <tr> 
          <td width="150"><center><i>macro</i></center></td> 
          <td width="250"><center><i>usage</i></center></td> 
          <td width="200"><center><i>default on Unix</i></center></td> 
        </tr> 
        <tr> 
          <td><tt>X11_cflags</tt></td> 
          <td>compilation flags for X11</td> 
          <td><tt>-I/usr/include</tt></td>
        </tr> 
        <tr> 
          <td><tt>Xm_cflags</tt></td> 
          <td>compilation flags for Motif</td> 
          <td><tt>-I/usr/include</tt></td>
        </tr> 
        <tr> 
          <td><tt>X_linkopts</tt></td> 
          <td>Link options for XWindows (and Motif)</td> 
          <td>&nbsp;</td>
        </tr> 
        <tr> 
          <td><tt>make_shlib</tt></td> 
          <td>The command used to generate the shared library from the static one</td> 
          <td><tt>${CMTROOT}/mgr/cmt_make_shlib_common.sh extract</tt></td>
        </tr> 
        <tr> 
          <td><tt>shlibsuffix</tt></td> 
          <td>The system dependent suffix for shared libraries</td> 
          <td><tt>so</tt></td>
        </tr> 
        <tr> 
          <td><tt>shlibbuilder</tt></td> 
          <td>The loader used to build the shared library</td> 
          <td><tt>g++</tt></td>
        </tr> 
        <tr> 
          <td><tt>shlibflags</tt></td> 
          <td>The additional options given to the shared library builder</td> 
          <td><tt>-shared</tt></td>
        </tr> 

        <tr> 
          <td><tt>application_suffix</tt></td> 
          <td>The default extension for applications</td>
          <td><tt>.exe</tt></td>
        </tr> 
        <tr> 
          <td><tt>library_prefix</tt></td> 
          <td>The default name prefix of libraries</td> 
          <td><tt>lib</tt></td>
        </tr> 
        <tr> 
          <td><tt>library_suffix</tt></td> 
          <td>The default name suffix of libraries</td> 
          <td>&nbsp;</td>
        </tr> 
        <tr> 
          <td><tt>symlink</tt></td> 
          <td>The command used to install a symbolic link</td> 
          <td><tt>/bin/ln -fs</tt></td>
        </tr> 
        <tr> 
          <td><tt></tt></td> 
          <td>The command used to remove a symbolic link</td> 
          <td><tt>/bin/rm -f </tt></td>
        </tr> 
        <tr> 
          <td><tt>build_prototype</tt></td> 
          <td>The command used to generate the C prototype header file (default to the internal cmt dedicated command)</td> 
          <td><tt>$(cmtexe) build prototype</tt></td>
        </tr> 
        <tr> 
          <td><tt>build_dependencies</tt></td> 
          <td>The command used to generate dependencies (default to the internal cmt dedicated command)</td> 
          <td><tt>$(cmtexe) -quiet -tag=$(tags) build dependencies</tt></td>
        </tr> 
        <tr> 
          <td><tt>lock_command</tt></td> 
          <td>The command used to physically lock a package</td> 
          <td><tt>chmod -R a-w ../*</tt></td>
        </tr> 
        <tr> 
          <td><tt>unlock_command</tt></td> 
          <td>The command used to physically unlock a package</td> 
          <td><tt>chmod -R g+w ../*</tt></td>
        </tr> 
        <tr> 
          <td><tt>make_hosts</tt></td> 
          <td>The list of remote host names which exactly require the <tt>make</tt> command</td> 
          <td>&nbsp;</td>
        </tr> 
        <tr> 
          <td><tt>gmake_hosts</tt></td> 
          <td>The list of remote host names which exactly require the <tt>gmake</tt> command</td> 
          <td>&nbsp;</td>
        </tr> 

<!--
        <tr> 
          <td><tt></tt></td> 
          <td></td> 
          <td>&nbsp;</td>
        </tr> 
-->

      </table> 
    </p>

  </cmt:section> 

</cmt:section> 

<cmt:section title="Standard tags generated by CMT">

  <p>
    <table BORDER='1' COLS='3'> 
      <tr>
        <td width="150"><center><i>tag name</i></center></td>
        <td width="400"><center><i>usage</i></center></td>
      </tr>

      <tr>
        <td><tt>CMTv&lt;n&gt;</tt></td>
        <td>Primary version id of CMT</td>
      </tr>
      <tr>
        <td><tt>CMTr&lt;n&gt;</tt></td>
        <td>Secondary version id of CMT</td>
      </tr>
      <tr>
        <td><tt>CMTp&lt;n&gt;</tt></td>
        <td>Patch id of CMT</td>
      </tr>
      <tr>
        <td><tt>`uname`</tt></td>
        <td>The basic platform id</td>
      </tr>
      <tr>
        <td><tt>&lt;project-name&gt;</tt></td>
        <td>The current project name</td>
      </tr>
      <tr>
        <td>
          <table>
            <tr><td><tt>&lt;project&gt;_prototypes</tt></td></tr>
            <tr><td><tt>&lt;project&gt;_no_prototypes</tt></td></tr>
          </table>
        </td>
        <td>The prototypes strategy for each project</td>
      </tr>
      <tr>
        <td>
          <table>
            <tr><td><tt>&lt;project&gt;_with_installarea</tt></td></tr>
            <tr><td><tt>&lt;project&gt;_without_installarea</tt></td></tr>
          </table>
        </td>
        <td>The installation area strategy for each project</td>
      </tr>
      <tr>
        <td>
          <table>
            <tr><td><tt>&lt;project&gt;_setup_config</tt></td></tr>
            <tr><td><tt>&lt;project&gt;_setup_no_config</tt></td></tr>
          </table>
        </td>
        <td>The strategy for generating <tt>&lt;P&gt;CONFIG</tt> for each project</td>
      </tr>
      <tr>
        <td>
          <table>
            <tr><td><tt>&lt;project&gt;_setup_root</tt></td></tr>
            <tr><td><tt>&lt;project&gt;_setup_no_root</tt></td></tr>
          </table>
        </td>
        <td>The strategy for generating <tt>&lt;P&gt;ROOT</tt> for each project</td>
      </tr>
      <tr>
        <td>
          <table>
            <tr><td><tt>&lt;project&gt;_setup_cleanup</tt></td></tr>
            <tr><td><tt>&lt;project&gt;_setup_no_cleanup</tt></td></tr>
          </table>
        </td>
        <td>The installation area cleanup strategy for each project</td>
      </tr>


<!--

      <tr>
        <td><tt>&nbsp;</tt></td>
        <td>&nbsp;</td>
      </tr>

-->

    </table> 
  </p>

</cmt:section> 

<cmt:section title="Standard templates for makefile fragments">

  <p>
    <table BORDER='1' COLS='3'> 
      <tr>
        <td width="150"><center><i>template name</i></center></td>
        <td width="200"><center><i>usage</i></center></td>
        <td width="400"><center><i>used in fragment</i></center></td>
      </tr>
      <tr>
        <td>ADDINCLUDE</td>
        <td>additional include path</td>
        <td>&lt;<i>language</i>&gt; java</td>
      </tr>
      <tr>
        <td>CONSTITUENT</td>
        <td>name of the constituent</td>
        <td>&lt;<i>language</i>&gt; java jar make_header jar_header java_header library_header application_header protos_header library_no_share library application dependencies cleanup_header cleanup_library cleanup_application check_application document_header &lt;document&gt; trailer dsw_all_project_dependency dsw_project dsp_library_header dsp_shared_library_header dsp_windows_header dsp_application_header dsp_trailer constituent check_application_header</td>
      </tr>
      <tr>
        <td>DATE</td>
        <td>now</td>
        <td>make_header</td>
      </tr>
      <tr>
        <td>FILENAME</td>
        <td>file name without path</td>
        <td>buildproto &lt;<i>language</i>&gt; &lt;<i>document</i>&gt;</td>
      </tr>
      <tr>
        <td>FILEPATH</td>
        <td>file path</td>
        <td>buildproto &lt;<i>language</i>&gt; &lt;<i>document</i>&gt;</td>
      </tr>
      <tr>
        <td>FILESUFFIX</td>
        <td>file suffix (without dot)</td>
        <td>&lt;<i>language</i>&gt;</td>
      </tr>
      <tr>
        <td>FILESUFFIX</td>
        <td>file suffix (with dot)</td>
        <td>&lt;<i>document</i>&gt;</td>
      </tr>
      <tr>
        <td>FULLNAME</td>
        <td>complete file path and name</td>
        <td>&lt;<i>language</i>&gt; cleanup &lt;<i>document</i>&gt; dsp_contents</td>
      </tr>
      <tr>
        <td>GROUP</td>
        <td>group name</td>
        <td>constituents_header</td>
      </tr>
      <tr>
        <td>LINE</td>
        <td>source files</td>
        <td>&lt;<i>language</i>&gt; dependencies constituent</td>
      </tr>
      <tr>
        <td>LINKMACRO</td>
        <td>link macro</td>
        <td>application</td>
      </tr>
      <tr>
        <td>NAME</td>
        <td>file name without path and suffix</td>
        <td>buildproto &lt;<i>language</i>&gt; java &lt;<i>document</i>&gt;</td>
      </tr>
      <tr>
        <td>OBJS</td>
        <td>object files</td>
        <td>jar_header java_header jar library_no_share library application cleanup_java document_header trailer</td>
      </tr>
      <tr>
        <td>OUTPUTNAME</td>
        <td>output file name</td>
        <td>java</td>
      </tr>
      <tr>
        <td>PACKAGE</td>
        <td>current package name</td>
        <td>&lt;<i>language</i>&gt; dsw_header dsw_all_project dsw_all_project_trailer dsw_trailer dsp_all readme_header readme readme_use readme_trailer</td>
      </tr>
      <tr> 
        <td>PACKAGEPATH</td>
        <td>current package location</td>
        <td>readme_use</td>
      </tr>
      <tr>
        <td>PROTOSTAMPS</td>
        <td>prototype stamp files</td>
        <td>protos_header</td>
      </tr>
      <tr>
        <td>PROTOTARGET</td>
        <td>prototype target name</td>
        <td>library_header application_header</td>
      </tr>
      <tr>
        <td>SUFFIX</td>
        <td>document suffix</td>
        <td>&lt;<i>document</i>&gt;</td>
      </tr>
      <tr>
        <td>TITLE</td>
        <td>title for make header</td>
        <td>make_header</td>
      </tr>
      <tr>
        <td>USER</td>
        <td>user name</td>
        <td>make_header</td>
      </tr>
      <tr>
        <td>VERSION</td>
        <td>current package version tag</td>
        <td>readme_header readme readme_use</td>
      </tr>
    </table>
  </p>

</cmt:section>

<cmt:section title="Makefile generation sequences">

  <cmt:blockquote> 

    This section describes the various makefile generation sequences
    provided by <tt>CMT</tt>. Each sequence description shows the
    precise set of <a href="#make_fragment">make fragments</a> used
    during the operation.

  </cmt:blockquote> 

  <p>
    <table border='1' cols='3'>

      <tr>
        <td width="200"><center><i>Generated makefile</i></center></td>
        <td width="250"><center><i>description</i></center></td>
        <td width="350"><center><i>used make fragments</i></center></td> 
      </tr>
       <tr>
        <td><tt>constituents.make</tt></td>
        <td>the main entry point point for all constituent targets</td>
        <td>
          <ol>
            <li>constituents_header</li>
            <li>constituent</li>
            <li>check_application_header</li>
          </ol>
        </td>
      </tr>
       <tr>
        <td><tt>&lt;<i>constituent</i>&gt;.make</tt></td>
        <td>application or library specific make fragment</td>
        <td>
          <ol>
            <li>make_header</li>
            <li>java_header | jar_header | library_header | application_header</li>
            <li>protos_header</li>
            <li>buildproto</li>
            <li>jar | library | library_no_share | application</li>
            <li>dependencies</li>
            <li>&lt;language&gt; | &lt;language&gt;_library | java</li>
            <li>cleanup_header</li>
            <li>cleanup</li>
            <li>cleanup_application</li>
            <li>cleanup_objects</li>
            <li>cleanup_java</li>
            <li>cleanup_library</li>
            <li>check_application</li>
          </ol>
        </td>
      </tr>
       <tr>
        <td><tt>&lt;<i>constituent</i>&gt;.make</tt></td>
        <td>document specific make fragment</td>
        <td>
          <ol>
            <li>make_header</li>
            <li>document_header</li>
            <li>dependencies</li>
            <li>&lt;document&gt;</li>
            <li>&lt;document-trailer&gt;</li>
            <li>cleanup_header</li>
          </ol>
        </td>
      </tr>
        <tr>
        <td><tt>&lt;package&gt;.dsw</tt></td>
        <td>Visual workspace configuration files</td>
        <td>
          <ol>
            <li>dsw_header</li>
            <li>dsw_all_project_header</li>
            <li>dsw_all_project_dependency</li>
            <li>dsw_all_project_trailer</li>
            <li>dsw_project</li>
            <li>dsw_trailer</li>
            <li>dsp_all</li>
          </ol>
        </td>
      </tr>
        <tr>
        <td><tt>&lt;constituent&gt;.dsp</tt></td>
        <td>Visual project configuration files</td>
        <td>
          <ol>
            <li>dsp_library_header | dsp_shared_library_header | dsp_windows_header | dsp_application_header</li>
            <li>dsp_contents</li>
            <li>dsp_trailer</li>
          </ol>
        </td>
      </tr>
        <tr>
        <td><tt>README</tt></td>
        <td>.</td>
        <td>
          <ol>
            <li>readme_header</li>
            <li>readme</li>
            <li>readme_use</li>
            <li>readme_trailer</li>
          </ol>
        </td>
      </tr>
    </table>
  </p>

</cmt:section>

<cmt:section title="The complete requirements syntax">

  The syntax of specification statements that can be installed in a
  <tt>requirements</tt> file are :

<cmt:syntax rule-width="220" name="CMT">
  <cmt:rule name="cmt-statement">
    <cmt:alt><cmt:ruleref name="application"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="apply_pattern"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="apply_tag"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="author"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="branches"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="build_strategy"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="cleanup_script"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="cmtpath_pattern"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="document"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="ignore_pattern"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="include_dirs"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="include_path"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="language"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="library"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="make_fragment"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="manager"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="package"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="pattern"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="private"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="public"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="setup_script"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="setup_strategy"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="symbol"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="tag"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="tag_exclude"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="use"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="version"/></cmt:alt>
  </cmt:rule>
  <cmt:rule name="alias">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="alias-name"/>
      <cmt:term name="default-value"/>
      <cmt:optionseq>
        <cmt:ruleref name="tag-expr"/>
        <cmt:term name="value"/>
      </cmt:optionseq>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="application">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="application-name"/>
      <cmt:optionseq>
        <cmt:ruleref name="constituent-option"/>
      </cmt:optionseq>
    </cmt:alt>
    <cmt:continuation>
      <cmt:optionseq>
        <cmt:ruleref name="source"/>
      </cmt:optionseq>
    </cmt:continuation>
  </cmt:rule>
  <cmt:rule name="constituent-option">
    <cmt:alt><cmt:kwd name="-no_share"/></cmt:alt>
    <cmt:alt><cmt:kwd name="-no_static"/></cmt:alt>
    <cmt:alt><cmt:kwd name="-prototypes"/></cmt:alt>
    <cmt:alt><cmt:kwd name="-no_prototypes"/></cmt:alt>
    <cmt:alt><cmt:kwd name="-check"/></cmt:alt>
    <cmt:alt><cmt:kwd name="-target_tag"/></cmt:alt>
    <cmt:alt><cmt:kwd name="-group" value="group-name"/></cmt:alt>
    <cmt:alt><cmt:kwd name="-suffix" value="output-suffix"/></cmt:alt>
    <cmt:alt><cmt:kwd name="-import" value="package-name"/></cmt:alt>
    <cmt:alt>
      <cmt:term name="variable-name"/>
      <cmt:kwd name="="/>
      <cmt:term name="variable-value"/>
    </cmt:alt>
    <cmt:alt><cmt:kwd name="-OS9"/></cmt:alt>
    <cmt:alt><cmt:kwd name="-windows"/></cmt:alt>
  </cmt:rule>
  <cmt:rule name="source">
    <cmt:alt><cmt:term name="name.suffix"/></cmt:alt>
    <cmt:alt><cmt:term name="*.suffix"/></cmt:alt>
    <cmt:alt><cmt:term name="*.*"/></cmt:alt>
    <cmt:alt>
      <cmt:kwd name="-s" value="new-search-path"/>
    </cmt:alt>
    <cmt:alt>
      <cmt:kwd name="-k" value="selection-regexp"/>
    </cmt:alt>
    <cmt:alt>
      <cmt:kwd name="-x" value="exclusion-regexp"/>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="apply_pattern">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="pattern-name"/>
      <cmt:optionseq>
        <cmt:term name="template-name"/>
	<cmt:kwd name="="/>
        <cmt:term name="value"/>
      </cmt:optionseq>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="apply_tag">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="tag-name"/>
      <cmt:optionseq>
        <cmt:term name="tag-name"/>
      </cmt:optionseq>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="author">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="author-name"/>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="branches">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:seq><cmt:term name="branch-name"/></cmt:seq>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="build_strategy">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="build-strategy-name"/>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="build-strategy-name">
    <cmt:alt><cmt:kwd name="prototypes"/></cmt:alt>
    <cmt:alt><cmt:kwd name="no_prototypes"/></cmt:alt>
    <cmt:alt><cmt:kwd name="with_installarea"/></cmt:alt>
    <cmt:alt><cmt:kwd name="without_installarea"/></cmt:alt>
  </cmt:rule>
  <cmt:rule name="cleanup_script">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="script-name"/>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="cmtpath_pattern">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:ruleref name="cmt-statement"/>
    </cmt:alt>
    <cmt:continuation>
      <cmt:optionseq>
        <cmt:kwd name=" ; "/>
        <cmt:ruleref name="cmt-statement"/>
      </cmt:optionseq>
    </cmt:continuation>
  </cmt:rule>
  <cmt:rule name="document">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="document-name"/>
      <cmt:optionseq>
        <cmt:ruleref name="constituent-option"/>
      </cmt:optionseq>
    </cmt:alt>
    <cmt:continuation>
      <cmt:optionseq>
        <cmt:ruleref name="source"/>
      </cmt:optionseq>
    </cmt:continuation>
  </cmt:rule>
  <cmt:rule name="ignore_pattern">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="pattern-name"/>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="include_dirs">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="search-path"/>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="include_path">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="search-path"/>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="language">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="language-name"/>
      <cmt:optionseq>
        <cmt:ruleref name="language-option"/>
      </cmt:optionseq>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="language-option">
    <cmt:alt><cmt:kwd name="-suffix" value="suffix"/></cmt:alt>
    <cmt:alt><cmt:kwd name="-linker" value="linker-command"/></cmt:alt>
    <cmt:alt><cmt:kwd name="-prototypes"/></cmt:alt>
    <cmt:alt><cmt:kwd name="-preprocessor_command" value="preprocessor_command"/></cmt:alt>
    <cmt:alt><cmt:kwd name="-fragment" value="fragment"/></cmt:alt>
    <cmt:alt><cmt:kwd name="-output_suffix" value="output-suffix"/></cmt:alt>
    <cmt:alt><cmt:kwd name="-extra_output_suffix" value="extra-output-suffix"/></cmt:alt>
  </cmt:rule>
  <cmt:rule name="library">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="library-name"/>
      <cmt:optionseq>
        <cmt:ruleref name="constituent-option"/>
      </cmt:optionseq>
    </cmt:alt>
    <cmt:continuation>
      <cmt:optionseq>
        <cmt:ruleref name="source"/>
      </cmt:optionseq>
    </cmt:continuation>
  </cmt:rule>
  <cmt:rule name="action">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="action-name"/>
      <cmt:optionseq>
        <cmt:ruleref name="tag-expr"/>
        <cmt:term name="value"/>
      </cmt:optionseq>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="macro">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="macro-name"/>
      <cmt:optionseq>
        <cmt:ruleref name="tag-expr"/>
        <cmt:term name="value"/>
      </cmt:optionseq>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="macro_append">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="macro-name"/>
      <cmt:optionseq>
        <cmt:ruleref name="tag-expr"/>
        <cmt:term name="value"/>
      </cmt:optionseq>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="macro_prepend">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="macro-name"/>
      <cmt:optionseq>
        <cmt:ruleref name="tag-expr"/>
        <cmt:term name="value"/>
      </cmt:optionseq>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="macro_remove">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="macro-name"/>
      <cmt:optionseq>
        <cmt:ruleref name="tag-expr"/>
        <cmt:term name="value"/>
      </cmt:optionseq>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="macro_remove_regexp">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="macro-name"/>
      <cmt:optionseq>
        <cmt:ruleref name="tag-expr"/>
        <cmt:term name="value"/>
      </cmt:optionseq>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="macro_remove_all">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="macro-name"/>
      <cmt:optionseq>
        <cmt:ruleref name="tag-expr"/>
        <cmt:term name="value"/>
      </cmt:optionseq>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="macro_remove_all_regexp">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="macro-name"/>
      <cmt:optionseq>
        <cmt:ruleref name="tag-expr"/>
        <cmt:term name="value"/>
      </cmt:optionseq>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="make_fragment">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="fragment-name"/>
      <cmt:optionseq>
        <cmt:ruleref name="fragment-option"/>
      </cmt:optionseq>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="fragment-option">
    <cmt:alt><cmt:kwd name="-suffix" value="suffix"/></cmt:alt>
    <cmt:alt><cmt:kwd name="-dependencies"/></cmt:alt>
    <cmt:alt><cmt:kwd name="-header" value="fragment"/></cmt:alt>
    <cmt:alt><cmt:kwd name="-trailer" value="fragment"/></cmt:alt>
  </cmt:rule>
  <cmt:rule name="manager">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="manager-name"/>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="package">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="package-name"/>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="path">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="path-name"/>
      <cmt:optionseq>
        <cmt:ruleref name="tag-expr"/>
        <cmt:term name="value"/>
      </cmt:optionseq>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="path_append">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="path-name"/>
      <cmt:optionseq>
        <cmt:ruleref name="tag-expr"/>
        <cmt:term name="value"/>
      </cmt:optionseq>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="path_prepend">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="path-name"/>
      <cmt:optionseq>
        <cmt:ruleref name="tag-expr"/>
        <cmt:term name="value"/>
      </cmt:optionseq>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="path_remove">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="path-name"/>
      <cmt:optionseq>
        <cmt:ruleref name="tag-expr"/>
        <cmt:term name="value"/>
      </cmt:optionseq>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="path_remove_regexp">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="path-name"/>
      <cmt:optionseq>
        <cmt:ruleref name="tag-expr"/>
        <cmt:term name="value"/>
      </cmt:optionseq>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="pattern">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:option><cmt:kwd name="-global"/></cmt:option>
      <cmt:term name="pattern-name"/>
      <cmt:ruleref name="cmt-statement"/>
    </cmt:alt>
    <cmt:continuation>
      <cmt:optionseq>
        <cmt:kwd name=" ; "/>
        <cmt:ruleref name="cmt-statement"/>
      </cmt:optionseq>
    </cmt:continuation>
  </cmt:rule>
  <cmt:rule name="private">
    <cmt:alt><cmt:kwd/></cmt:alt>
  </cmt:rule>
  <cmt:rule name="public">
    <cmt:alt><cmt:kwd/></cmt:alt>
  </cmt:rule>
  <cmt:rule name="set">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="set-name"/>
      <cmt:optionseq>
        <cmt:ruleref name="tag-expr"/>
        <cmt:term name="value"/>
      </cmt:optionseq>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="set_append">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="set-name"/>
      <cmt:optionseq>
        <cmt:ruleref name="tag-expr"/>
        <cmt:term name="value"/>
      </cmt:optionseq>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="set_prepend">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="set-name"/>
      <cmt:optionseq>
        <cmt:ruleref name="tag-expr"/>
        <cmt:term name="value"/>
      </cmt:optionseq>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="set_remove">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="set-name"/>
      <cmt:optionseq>
        <cmt:ruleref name="tag-expr"/>
        <cmt:term name="value"/>
      </cmt:optionseq>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="set_remove_regexp">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="set-name"/>
      <cmt:optionseq>
        <cmt:ruleref name="tag-expr"/>
        <cmt:term name="value"/>
      </cmt:optionseq>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="setup_script">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="script-name"/>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="setup_strategy">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="setup-strategy-name"/>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="setup-strategy-name">
    <cmt:alt><cmt:kwd name="config"/></cmt:alt>
    <cmt:alt><cmt:kwd name="no_config"/></cmt:alt>
    <cmt:alt><cmt:kwd name="root"/></cmt:alt>
    <cmt:alt><cmt:kwd name="no_root"/></cmt:alt>
    <cmt:alt><cmt:kwd name="cleanup"/></cmt:alt>
    <cmt:alt><cmt:kwd name="no_cleanup"/></cmt:alt>
  </cmt:rule>
  <cmt:rule name="symbol">
    <cmt:alt><cmt:ruleref name="alias"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="action"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="macro"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="macro_append"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="macro_prepend"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="macro_remove"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="macro_remove_regexp"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="macro_remove_all"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="macro_remove_all_regexp"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="path"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="path_append"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="path_prepend"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="path_remove"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="path_remove_regexp"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="set"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="set_append"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="set_prepend"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="set_remove"/></cmt:alt>
    <cmt:alt><cmt:ruleref name="set_remove_regexp"/></cmt:alt>
  </cmt:rule>
  <cmt:rule name="tag">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="tag-name"/>
      <cmt:optionseq><cmt:term name="tag-name"/></cmt:optionseq>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="tag_exclude">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="tag-name"/>
      <cmt:optionseq><cmt:term name="tag-name"/></cmt:optionseq>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="tag-expr">
    <cmt:alt>
      <cmt:term name="tag-name"/>
      <cmt:optionseq><cmt:kwd name="&amp;"/><cmt:term name="tag-name"/></cmt:optionseq>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="use">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:term name="package-name"/>
      <cmt:option>
        <cmt:ruleref name="version-tag"/>
	<cmt:option>
	  <cmt:term name="access-path"/>
	</cmt:option>
      </cmt:option>
    </cmt:alt>
    <cmt:continuation>
      <cmt:option>
        <cmt:ruleref name="use-option"/>
      </cmt:option>
    </cmt:continuation>
  </cmt:rule>
  <cmt:rule name="version">
    <cmt:alt>
      <cmt:kwd/>
      <cmt:ruleref name="version-tag"/>
    </cmt:alt>
  </cmt:rule>
  <cmt:rule name="version-tag">
    <cmt:alt>
      <cmt:ruleref name="key"/>
      <cmt:term name="version-number"/>
    </cmt:alt>
    <cmt:continuation>
      <cmt:option>
        <cmt:ruleref name="key"/>
	<cmt:term name="release-number"/>
        <cmt:option>
          <cmt:ruleref name="key"/>
	  <cmt:term name="patch-number"/>
        </cmt:option>
      </cmt:option>
    </cmt:continuation>
  </cmt:rule>
  <cmt:rule name="use-option">
    <cmt:alt><cmt:kwd name="-no_auto_imports"/></cmt:alt>
    <cmt:alt><cmt:kwd name="-auto_imports"/></cmt:alt>
  </cmt:rule>
  <cmt:rule name="key">
    <cmt:alt><cmt:seq><cmt:term name="letter"/></cmt:seq></cmt:alt>
  </cmt:rule>
</cmt:syntax>

</cmt:section> 

<cmt:section title="The default strategies defined in CMT">

  <cmt:cmtcode>
  DefaultPrototypesStrategy = Prototypes, 
  DefaultInstallAreaStrategy = WithoutInstallArea</cmt:cmtcode>

</cmt:section> 

<cmt:section title="The internal mechanism of cmt cvs operations">

  Generally, CVS does not handle queries upon the repository (such as
  knowing all installed modules, all tags of the modules
  etc..). Various tools such as CVSWeb, LXR etc. provide very powerful
  answers to this question, but all through a Web browser.

  <p><tt>CMT</tt> provides a hook that can be installed within a CVS
  repository, based on a helper script that will be activated upon a
  particular CVS command, and that is able to perform some level of
  scan within this repository and return filtered information. </p>

  <p>More precisely, this helper script (found in
  <tt>${CMTROOT}/mgr/cmt_buildcvsinfos2.sh</tt>) is meant to be declared
  within the <tt>loginfo</tt> management file (see the <a
  href="http://www.cvshome.org/docs/manual/index.html">CVS manual</a>
  for more details) as one entry named <tt>.cmtcvsinfos</tt>, able to
  launch the helper script. This installation can be operated at once
  using the following sequence:</p>

  <cmt:code>
sh&gt; cd ${CMTROOT}/mgr
sh&gt; gmake installcvs</cmt:code> 

  <p>This mechanism is thus fully compatible with standard remote
  access to the repository.</p>

  <p>Once the helper script is installed, the mechanism operates as
  follows (this actually describes the algorithms installed in the
  <tt>CvsImplementation::show_cvs_infos</tt> method available in
  <tt>cmt_cvs.cxx</tt> and is transparently run when one uses the <tt>cmt
  cvs<i>xxx</i> commands</tt>):</p>

  <ol>

    <li>Find a location for working with temporary files. This is
    generally deduced from the <tt>${TMPDIR}</tt> environment variable
    or in <tt>/tmp</tt> (or in the current directory if none of these
    methods apply).</li>

    <li>There, install a directory named
    <tt>cmtcvs/&lt;<i>unique-name</i>&gt;/.cmtcvsinfos</tt></li>

    <li>Then, from this directory, try to run a fake import command
    built as follows:

      <cmt:code>
cvs -Q import -m cmt .cmtcvsinfos/&lt;<i>package-name</i>&gt; CMT v1 </cmt:code> 

      <p>Obviously this command is fake, since no file exist in the
      temporary directory we have just created. However, </p>

    </li>

    <li>This action actually triggers the

      <tt>cmt_buildcvsinfos2.sh</tt> script, which simply receives in
      its argument the module name onto which we need
      information. This information is obtained by scanning the files
      into the repository, and an answer is built with the following
      syntax:

      <cmt:code>
[error=<i>error-text</i>]            (1)
tags=<i>tag</i> ...                  (2)
branches=<i>branch</i> ...           (3)
subpackages=<i>sub-package</i> ...   (4)</cmt:code>

      <ol>

        <li>In case of error (typically when the requested module is
        not found in the repository) a text explaining the error
        condition is returned</li>

        <li>The list of tags found on the requirements file</li>

        <li>The list of branches defined in this packages (ie
        subdirectories not containing a requirements file)</li>

        <li>The list of subpackages (ie subdirectories containing a
        requirements files)</li>

      </ol>
    </li>
  </ol>

</cmt:section>

</cmt:section>

</cmt:book>
