• A requirements file is made of statements, each describing one named configuration parameter.

  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 must be the last character on the line or must be only followed by space characters).

  Each statement is composed of words separated with spaces or tabulations.

  The first word of a statement is the name of the configuration parameter.

  The rest of the statement provides the value assigned to the configuration parameter.

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

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

  tabulation	<cmt:tab/>
  carriage-return	<cmt:cr/>
  line-feed	<cmt:lf/>

• Comments : they start with the # character and extend up to the end of the current line.

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.

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

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.

Various options can be used when declaring a constituent:

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

   library A A.cxx B.cxx

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

   library A -s=A *.cxx -s=B *.cxx
   • -s=A means that next source files should be taken searched from ../src/A
   • -s=B means that next source files should be taken searched from ../src/B. Note that this new specification is not relative to the previous -s=A but relative to the default search path ../src
   • *.cxx indicates that all files with a .cxx suffix in the current search path should be considered

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

   library A -s=A -x=[0-9] *.cxx -s=B -k=^B *.cxx
   • The exclusion specification -x=[0-9] added to the statement will exclude all files from ../src/A containing a number in their name.
   • The selection specification -k=^B added to the statement will select files from ../src/B strictly starting with the B letter.

2. 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 -suffix=<suffix> option. With this option, every object file name will be automatically suffixed by the character string "<suffix>", avoiding name conflicts between the different targets, as in the following example:

   library AXt -suffix=Xt *.cxx library AXaw -suffix=Xaw *.cxx

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

   make_fragment doc_to_html (1) document doc_to_html Foo output=FooA.html FooA.doc (2) (3)
   1. This makefile fragment is meant to contain some text conversion actions and defines a document type named doc_to_html.
   2. This constituent exploits the document type doc_to_html to convert the source FooA.doc into an html file.
   3. The user defined template variable named output is specified and assigned the value FooA.html. If the fragment doc_to_html contains the string ${output}, then it will be substituted to this value.

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

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.

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

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.

One could, for instance specify within the requirements file :

Then, running gmake all would only rebuild the un-grouped constituents, whereas running

in the context of the Foo package would rebuild objy related or graphics related constituents.

We consider here languages that are able to produce object files from sources.

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

The language support is simply named fortran90 and is declared by the following statement:

1. The recognized suffixes for source files will be f90 and F90
2. The linker command used to build a Fortran90 application is described inside the macro named f90link (which must defined in this requirements file but which can also be overridden by clients)

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

These two fragments should be installed in the fragments sub-directory of the cmt branch of our package.

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

These fragments make use of the fcomp macro, which holds the fortran77 compiler command (through the for macro).

We therefore simply replace these macros by new macros named f90comp and f90, defined as follows:

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) -extra_output_suffix option like in:

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:

• The set keyword is translated into an environment variable definition.
• The macro keyword is translated into a make's macro definition.
• The path keyword is translated into a prioritized path-like environment variable, which is supposed to be composed of search paths separated with colon characters ':' (on Unix) or semi-colon characters ';' (on Windows). It is generally recommended to construct such a variable by iteratively concatenating individual items one by one using path_append or path_prepend
• The action keyword is translated into a shell command definition, that can be activated using the cmt do <action> command or the associated make target.
• The alias keyword is translated into a shell alias definition,

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

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

All these definitions follow the same pattern:

• The symbol-name identifies the symbol.

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

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

• Each tag-value pair describes an alternate value to be used when the corresponding tag or tag-expression is active.

• When several alternate values are specified through several tag-value pairs the first matching condition is selected. Therefore one should always specify the most contraining condition first.

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

• The path_remove keyword is slightly specialized since it removes all individual search paths that contain the specified sub-string.

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

The tag expression is used to select one alternate value to replace the default value, using the following matching rule:

• The first matching condition in the ordered list of alternate values is selected, ignoring the following ones
• A tag expression matches when all tags in the expression are active.

Examples of such definition are :

Describe the relationships with other packages; the generic syntax is :

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.

The root specification can be relative (ie. on Unix it does not contain a leading '/' character). In this case, this prefix 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).

Examples of such relationships are :

By default, a set of standard macros, which are expected to be specified by used packages, is automatically imported from them (see the detailed list of these macros). This automatic feature can be discarded using the -no_auto_imports option to the use statement, or re-activated using the -auto_imports. 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 -import=<package> option.

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

• all operations done in the context of package B will see both packages C and D
• all operations done in the context of package A will see both packages B and D, but not package C

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.

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

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

The general principle of a pattern is to associate a templated (set of) cmt 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 " ; " separator pattern (beware of really enclosing the ; character between two space characters).

The general syntax for defining a pattern in a requirements file is:

Pattern templates are names enclosed between the < and > characters. A set of predefined templates are automatically provided by CMT:

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.

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

Some examples:

1. Changing the standard include search path.

   The standard include path is set by default to ${<package>_root}/src. 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:

   pattern -global include_path include_path ${<package>_root}/<package>/

   For instance, a package named PackA will expand this pattern as follows:

   include_path ${PackA_root}/PackA/

2. Providing a value to the LD_LIBRARY_PATH environment variable

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

   pattern ld_library_path \ path_remove LD_LIBRARY_PATH "/<package>/" ; \ path_append LD_LIBRARY_PATH ${<PACKAGE>ROOT}/${CMTCONFIG}

   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:

   apply_pattern ld_library_path

   The schema installed by this pattern provides first a cleanup of the LD_LIBRARY_PATH 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.

3. Installing a systematic test application in all packages

   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.

   pattern quality_test application <package>test <package>test.cxx <other_sources>

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

These patterns act quite similarly to the global 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 packages, they are automatically applied to all entries in the CMTPATH list.

Only few system parameters can be used here:

• <path> which stands for any entry in the CMTPATH list.
• <project> which stands for the project name associated with an entry in the CMTPATH list.

As an example suppose we define

this will assemble one -I 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

This can be combined with the standard and automatic macros (automatically setup for all used packages) <package>_cmtpath <package>_offset which provide the CMTPATH entry and the directory offset in this CMTPATH for all used packages.

Describe the specific directory branches to be added while configuring the package.

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

Users can control the behaviour of CMT through a set of strategy specifications. The current implementation provides such control over several aspects :

1. The build strategy

   This controls some aspects of the building process.

   The following keywords are available:

   prototypes	C source files will automatically produce a header file containing a prototype of all global entry points
   no_prototypes	No production of automatic prototype header files for C sources
   with_installarea	The installation area mechanisms are activated. This implies applying the cmtpath_patterns that may be defined (eg in CMT itself)
   without_installarea	The installation area mechanisms are inhibited

2. The setup strategy

   This controls various actions that may be performed during the sourcing of the setup scripts.

   The following keywords are available:

   config	An environment variable <PACKAGE>CONFIG will be generated for all packages in the dependency chain
   no_config	The <PACKAGE>CONFIG environment variable is not generated
   root	An environment variable <PACKAGE>ROOT will be generated for all packages in the dependency chain
   no_root	The <PACKAGE>ROOT environment variable is not generated
   cleanup	The automatic cleanup operation to the current installation area is launched
   no_cleanup	The automatic cleanup operation to the current installation area is not launched

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.

Every strategy setting defines two mutually exclusive tags and activates one of them.

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

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

Override the specification for the default include search path, which is internally set to
${<package>_root}/src.

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

Add explicit specifications for include access paths.

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

There are basically three categories of such fragments :

1. some are provided by CMT itself (they correspond to its internal behaviour)
2. others handle the language support
3. and the last serve as specialized document generators.

The fragments defined in CMT can be:

• those used to construct the application or library constituents. Their semantic is standardized (they are all associated with a language statement in the CMT requirements file). 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
• those used internally by CMT as primary building blocks for assembling the makefile. (Generally developers should not see them). 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
• some document generators which may be used if needed, but are not mandatory: installer installer_header readme readme_header readme_trailer readme_use dvi tex generator generator_header
• those used to generate configuration files for MSVisualC++: 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

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 _library 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 language statement

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

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 may freely override any make fragment provided by CMT itself (although in this case a deep understanding of what the original fragment does is recommended).

Makefile fragments may take any form convenient to the document style, and some special pre-built templates (see the appendix) can be used in their body to represent running values, meant to be properly expanded at actual generation time :

CONSTITUENT	the constituent name
FULLNAME	the full source path
FILENAME	the source file name without its path
NAME	the source file name without its path and suffix
FILESUFFIX	the dotted file suffix
FILEPATH	the output path
SUFFIX	the default suffix for output files

The public or private keywords introduce sections containing public or private statements. This concerns:

• the definition of symbols
• the specification of use relationships
• the declaration of make fragments
• the declaration of patterns

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

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.

However, the cmt broadcast and cmt show uses 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)

The tag keyword provides tag definitions, while the apply_tag keyword activates a tag.

A tag is a token which can be used to select particular values of symbols.

Some tags are automatically constructed by CMT according to its knowledge of the context (see this section for more details), but they may be also defined within a requirements file as follows :

1. This simply declares a tag. This does not activate it by default

2. This construct declares that the tags Foo, FooA and FooB will become active if Bar becomes active. Note that this statement implicitly declares FooA and FooB

3. This activates the Bar tag. Tags that have been associated with it (in [2]), will all become active as well.

Running the setup script (through the source setup.[c]sh or call setup.bat command ) can also receive tag specifications using the -tag=tag-list options.

Typical uses of this broadcast operation could be:

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

It is possible to specify a list of selection or exclusion criteria set onto the package path, using the following options, right after the broadcast keyword. These selection criteria may be combined (eg one may combine the begin and select modifiers)

According to the option, the loop will only operate onto:

1. the first package which path contains the string "Cm", and then all other reachable packages (in case other specifiers are used)
2. the packages which path contains the string "Cm"
3. the packages which path contains either the string "/Cm/" or the string "/CSet/"
4. the packages which path contains the string "Cm", but which does not contain the string "Cmo"
5. the packages at the same level as the current package
6. the packages at the same level as the current package or among the <n> first entries in the CMTPATH list
7. the packages at any level of the CMTPATH search list
8. all the packages and versions currently available through the CMTPATH list

The actions associated with the build options are generally meant for internal use only, and users will rarely (if ever!) apply them manually

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.

• [-nmake] constituent_makefile <constituent-name>

  This command is internally used by CMT in the standard Makefile.header fragment. It generates a specific makefile fragment (named <constituent-name>.make) which is used to re-build this fragment.

  All such constituent fragments are automatically included from the main Makefile.

  Although this command is meant to be used internally (and transparently) by CMT 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.

  The -nmake 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 .nmake instead of .make for Unix environments. The main makefile is expected to be named NMake and the standard header is named NMakefile.header

• [-nmake] constituents_makefile

  This command is internally (and transparently) used by CMT 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.

  The -nmake 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 .nmake instead of .make for Unix environments. The main makefile is expected to be named NMake and the standard header is named NMakefile.header

• dependencies

  This command is internally (and transparently) used by CMT from the constituent specific fragment, and when the make command is run, to generate a fragment containing the dependencies required by a source file.

  This fragment contains a set of macro definitions (one per constituent source file), each containing the set of found dependencies.

• library_links

  This command builds a local symbolic link towards all exported libraries from the used packages. A package exports its libraries through the <package>_libraries macro which should contain the list of constituent names corresponding to libraries that must be exported.

  library Foo ... library Foo-utils ... ... macro Foo_libraries "Foo Foo-utils" The corresponding cmt remove library_links command will remove all these links.
• msdev

  This command generates workspace (.dsw) and project (.dsp) files required for the MSDev tool.

• vsnet

  This command generates workspace and project files required for the Visual.net tool.

• os9_makefile

  This command generates external dedicated makefile 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 OS9 operating systems.

  The output of this tool is a set of files (named with the components' name and suffixed by .os9make) that are meant to be included within the main Makefile that the developer has to write anyhow.

  The syntax of the cmt build os9_makefile utility is as follows :

  sh> cmt build os9_makefile <package>
• prototype <source-file-name>

  This command is internally (and transparently) used by CMT from the constituent specific fragment, and when the make command is run, to generate prototype header files from C source files.

  The prototype header files (named <file-name>.ph) will contain prototype definitions for every global entry point defined in the corresponding C source file.

  The effective activation of this feature is controled by the build strategy of CMT. The build strategy may be freely and globally overridden from any &CMTrequirements; file, using the build_strategy cmt statement, providing either the "prototypes" or the "no_prototypes" values.

  In addition, any constituent may locally override this strategy using the "-prototypes" or "-no_prototypes" modifiers.

• readme

  This command generates a README.html file into the cmt branch of the referenced package. This html file will include

  • a table containing URLs to equivalent pages for all used packages,
  • a copy of the local README file (if it exists).
• tag_makefile

  This command produces onto the standard output, the exhaustive list of all macros controled by CMT, ie. those defined in the requirements files as well as the standard macros internally built by CMT, taking into account all used packages.

An empty output means that everything is fine.

If substitution is performed, a copy (with additional extension sav) is produced.

This command is internally used in the cleanup.[c]sh shell script, itself generated by the cmt config command.

This command (re-)generates the setup scripts and the manimal Makefile (when it does not exist yet or have been lost).

To be properly operated, one must already be in the cmt or mgr branch of a package (where the &CMTrequirements; file can be found).

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)

The situations in which it is useful to run this command are:

• When the setup or cleanup scripts have been lost
• When the minimal Makefile have been lost
• When the version of CMT is changed
• After restoring a package from CVS
• 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)

This command creates a new package or a new version of a package

In the first mode (ie. without the area argument) the package will be created in the default path.

The second mode explicitly provides an alternate path.

A minimal configuration is installed for this new package:

• A src and a cmt branch
• A very minimal requirements file
• The setup and cleanup shell scripts
• The minimal Makefile

The expansion consists in:

• Expanding macros referenced in the model string using the standard notations $() or ${} or %% > cmt expand model "abcd $(CMTVERSION) efgh" abcd &CMTVersion; efgh
• Recursively expanding text files with parameters. The model string must then take a conventional XML-based syntax: > cmt expand model "text <file-name parameter=value ... /> text ..." or > cmt expand model -strict "text <cmts:file-name parameter='value' ... /> text ..." or > cmt expand model -strict "text <cmtv:file-name parameter='v1 v2 v3 ...' ... /> text ..." Where:
  • file-name is the name of a file declared using the make_fragment statement
  • parameter=value specifies the value of a parameter that will be substituted in the file when referenced using the $(parameter) notation. Several such values may be specified in one model string
  • the -strict form is useful to handle XML files, and file names must be prefixed (namespaced) by a special keyword cmts: or cmtv: .

    cmts:	Perform a unique substitution over one copy of the file
    cmtv:	Perform a multiple substitution over N copies of the file, taking the N space-separated values specified for the parameters

  The following examples will explain some of the mechanisms.

  We consider A containing:

  A$(P1)B$(P2)C

  And B containing:

  i<cmts:A P1='j' P2='${P2}'/>k > cmt expand model "abcd <A P1=XXX/> efgh" [1] abcd AXXXBC efgh > cmt expand model -strict "abcd <cmts:A P1='XXX' P2='YYY'/> efgh" [2] abcd AXXXBYYYC efgh > cmt expand model -strict "abcd <cmts:A P1='XXX'/> <cmts:B P2='YYY'/> efgh" [3] abcd AXXXBC iAjBYYYCk efgh > cmt expand model -strict "abcd <cmtv:A P1='X Y Z' P2='YYY'/> efgh" [4] abcd AXBYYYCAYBCAZBC efgh > cmt expand model -strict "abcd <cmtv:A P1='X Y Z' P2='\"\" <cmt:null/> ZZZ'/> efgh" [5] abcd AXBCAYBCAZBZZZC efgh ...
  1. A simple expansion using the non-strict model syntax. P1 is substituted, but $(P2) becomes empty
  2. The same using the strict model. Here P2 is valued.
  3. A more complex model, using a recursive expansion described in B showing how parameter values are transmitted
  4. A model showing the multiple expansion. Here P1 receives 3 values. P2 has only one value. The largest vector (3 values) dictates the number of copies. smaller vectors are completed by empty values.
  5. A model showing the multiple expansion with empty values in a vector. Here P1 receives 3 values. P2 has also 3 values, but only one non-empty. This examples show the two possible means of specifying empty vector values: using either \"\" or the reserved keyword <cmt:null/>.

• 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 -strict option, when selected is propagated during the recursion.

This mechanism is widely internally used by CMT, especially for instanciating make fragments. Then, users may use it for any kind of document, including maual generation of MSDev configuration files, etc...

1. Check if a conflicting lock is already set onto this package (ie. a lock owned by another user).
2. If not, then install a small text file named lock.cmt into the cmt/mgr branch of the package, containing the following text: locked by <user-name> date <now>

3. Run a shell command described in the macro named lock_command meant to install physical locks onto all files for this version of this package. A typical definition for this macro could be: macro lock_command "chmod -R a-w ../*" \ WIN32 "attrib /S /D +R ../*"

The arguments needed to reach the package version to be removed are the same as the ones whic had been used to create it.

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.

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.

This may be combined with the global options -pack=package, -version=version, -path=access-path, to give a direct access to any package context.

This command has no effect when run in the context of a package structured with the version directory

This command must be run while being in the context of one CMT package.

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 version.cmt files

This command is internally used in the setup.[c]sh or setup.bat shell script, itself generated by the cmt config command.

• all_tags

This command displays all currently defined tags, even when not currenty active

• applied_patterns

This command displays all patterns actually applied in the current package

• author

• branches

• clients <package> [ <version> ]

  This command displays all packages that express an explicit use statement onto the specified package. If no version is specified on the argument list, then all uses of that package are displayed.

  Note that the search on clients is not performed recusively. Thus only clients explicitly using the specified package will be displayed.

• constituent_names

• constituents

• cycles

  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 use_linkopts macro.

• fragment <name>

  This command displays the actual location where the specified make fragment is currently found by CMT, taking into account possible overridden definitions.

• fragments

  Display the effective location of all declared make fragments

• groups

  This command displays all groups possibly defined in constituents of the current package (using the -group=<group-name> option).

• languages

  Display al languages declared using the language keyword

• macro <name>
  set <name>
  action <name>

  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.

  By adding a -tag=<tag> 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.

• macro_value <name>
  set_value <name>
  action_value <name>

  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.

  By adding a -tag=<tag> 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.

  The typical usage of the show macro_value command is to get at the shell level (rather than within a Makefile) the value of a macro definition, providing means of accessing them (quite similarly to an environment variable) :

  csh> set compiler=`cmt show macro_value cppcomp` csh> ${compiler} ....
• macros
  sets
  actions

  This set of commands extracts from the &CMTrequirements; file(s) the complete set of symbol (macro, set or action) definitions, selects the appropriate tag definition (or uses the one provided in the -tag=<tag> option) and displays the effective symbol values corresponding to this tag.

  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 :

  csh> eval make `cmt show macros`

  This use of cmt show macros is directly installed within the default target provided in the standard Makefile.header file. Therefore if this file is included into the package's Makefile, 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.

  By adding a -tag=<tag> 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.

• manager

• packages

  This command displays all packages (and all versions of them) currently reachable through the current access path definition (which can be displayed using the cmt show path command).

• path

  This command displays the complete and effective access path currently defined using any possible alternate way.

• pattern <name>

  This command displays how and where the specified pattern is defined, and which packages do apply it.

• patterns

  This command displays all pattern definitions.

• projects

  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 CMTPATH

  > cmt show projects 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)

• pwd

  This command displays a filtered version of the standard pwd unix command. The applied filter takes into account the set of aliases installed in the standard configuration file located in ${CMTROOT}/mgr/cmt_mount_filter.

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

• setup

  This command combines in one go the output of:

  > cmt show uses > cmt show tags > cmt show path

• strategies

• tags

This command displays all currently active tags, and what part of the configuration actually activates them

• uses

  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 -public modifier

  > cmt -public show uses

  A typical output produced by this command is:

  > cmt show uses # 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)
  1. The first section of the display (up to the Selection keyword) displays the hierarchical use graph.

     Use statements as specified in the requirements files are displayed, rather than the result of the effective selection performed by CMT

  2. Sub-uses are expanded only once and indented according to the depth in the graph

  3. Various precisions on the use statements are shown in the first section, such as the scoping section, the -no_auto_imports modifier, and the native version of this package, (when a <package>_native_version macro has been defined)

  4. The second section shows the effective ordered set of use statements resolved by CMT according to the combined use specifications.

  5. On every line the effective location of the found package is displayed.

  The -quiet 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.

• use_paths <target-package>

This command displays all possible paths between the current package and the specified used target package.

In particular this will detect if a package has no access to another one, due to private use statements

• version

  This command displays the version tag of the current package.

• versions <name>

  This command displays the reachable versions of the specified package, looking at the current access paths.

1. Check if a conflicting lock is already set onto this package (ie. a lock owned by another user).
2. If not, then remove the text file named lock.cmt from the cmt/mgr branch of the package.
3. Run a shell command described in the macro named unlock_command meant to remove physical locks from all files for this version of this package. A typical definition for this macro could be: macro unlock_command "chmod -R g+w ../*" \ WIN32 "attrib /S /D -R ../*"

macro	usage	default value
CMTrelease	gives the current release number of CMT	&CMTrelease;
CMTVERSION	gives the current complete version tag of CMT	&CMTVersion;

macro	usage	default value
tag	gives the binary tag	${CMTCONFIG}
src	the src branch	../src/
inc	the include branch	../src/
mgr	the cmt or mgr branch	../cmt/ or ../mgr/
bin	the branch for binaries	../$(<package>_tag)/
javabin	the branch for java classes	../classes/
doc	the doc branch	../doc/
cmt_hardware	the description of the current hardware	<none>
cmt_system_version	the version of the current OS	<none>
cmt_compiler_version	the version of the currently visible C++ compiler	<none>

During the mechanism of new language declaration and definition available in the CMT syntax, developers are expected to define similar conventions for corresponding actions.

Their default values are originally defined inside the &CMTrequirements; file of the CMT package itself but can be redefined by providing a new definition in the package's requirements file using the macro statement. The original definition can be completed using the macro_append or macro_prepend statements.

macro	usage	default value
cc	The C compiler	cc
ccomp	The C compiling command	$(cc) -c -I$(inc) $(includes) $(cflags)
clink	The C linking command	$(cc) $(clinkflags)
cflags	The C compilation flags	none
pp_cflags	The preprocessor flags for C	none
clinkflags	The C link flags	none

cpp	The C++ compiler	g++
preproc	The C++ preprocessor	g++ -MD -c
cppcomp	The C++ compiling command	$(cpp) -c -I$(inc) $(includes) $(cppflags)
cpplink	The C++ linking command	$(cpp) $(cpplinkflags)
cppflags	The C++ compilation flags	none
pp_cppflags	The preprocessor flags for C++	none
cpplinkflags	The C++ link flags	none

for	The Fortran compiler	f77
fcomp	The Fortran compiling command	$(for) -c -I$(inc) $(includes) $(fflags)
flink	The Fortran linking command	$(for) $(clinkflags)
fflags	The Fortran compilation flags	none
pp_fflags	The preprocessor flags for fortran	none
flinkflags	The Fortran link flags	none
ppcmd	The include file command for Fortran	-I

javacomp	The java compiling command	javac
jar	The java archiver command	jar

lex	The Lex command	lex $(lexflags)
lexflags	The Lex flags	none
yacc	The Yacc command	yacc $(yaccflags)
yaccflags	The Yacc flags	none
ar	The archive command	ar -clr
ranlib	The ranlib command	ranlib

They are automatically and by default concatenated by CMT to fill in the corresponding global use macros (see appendix on generated macros). However, this concatenation mechanism is discarded when the -no_auto_imports option is specified in the corresponding use statement.

macro	usage
<package>_cflags	specific C flags
<package>_pp_cflags	specific C preprocessor flags
<package>_cppflags	specific C++ flags
<package>_pp_cppflags	specific C++ preprocessor flags
<package>_fflags	specific Fortran flags
<package>_pp_fflags	specific Fortran preprocessor flags
<package>_libraries	gives the (space separated) list of library names exported by this package. This list is typically used in the cmt build library_links command.
<package>_linkopts	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. A typical example of how to define such a macro could be : macro Cm_linkopts "-L$(CMROOT)/$(Cm_tag) -lCm -lm"
<package>_stamps	may contain a list of stamp 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 <library>.stamp. Thus, a typical definition for this macro could be : macro Cm_stamps "$(Cm_root)/$(Cm_tag)/Cm.stamp" Then, these stamp file references are accumulated into the standard macro named use_stamps 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.

The following macros are not subject to automatic concatenation (and therefore are not hidden by the -no_auto_imports modifier).

macro	usage
<package>_native_version	specifies the native version of the external package referenced by this interface package. When this macro is provided, its value is displayed by the cmt show uses command
<package>_export_paths	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
<package>_home	specifies the base location for external software described in glue packages. This macro is generally used to specify the previous one

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 lib_, app_ or doc_).

They are used in the various make fragments for fine customization of the build command parameters.

<type>_<constituent>_cflags	specific C flags
<type>_<constituent>_pp_cflags	specific C preprocessor flags
<type>_<constituent>_cppflags	specific C++ flags
<type>_<constituent>_pp_cppflags	specific C++ preprocessor flags
<type>_<constituent>_fflags	specific Fortran flags
<type>_<constituent>_pp_fflags	specific Fortran preprocessor flags
<constituent>linkopts	provides additional linker options to the application. It is complementary to - and should not be confused with - the <package>_linkopts macro, which provides exported linker options required by clients packages to use the package libraries.
<constituent>_shlibflags	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).
<constituent>_dependencies	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 have 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).
<group>_dependencies	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 have 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).

By convention, they are all prefixed by the source file name followed by the source file suffix (either _c, _cxx, _f, etc.)

They are used in the various make fragments for fine customization of the build command parameters.

<constituent>_<suffix>_cflags	specific C flags
<constituent>_<suffix>_cppflags	specific C++ flags
<constituent>_<suffix>_fflags	specific Fortran flags

These macros are automatically generated when any cmt connand is run (and thus when make is run).

The first set of them provide constant values corresponding to CMT based information. They are not meant to be overridden by the user, since they serve as a communication mean between CMT and the user.

<PACKAGE>ROOT	The access path of the package (including the version branch)
<package>_root	The access path of the package (including the version branch). This macro is very similar to the <PACKAGE>ROOT macro except that it tries to use a relative path instead of an absolute one.
<PACKAGE>VERSION	The used version of the package
PACKAGE_ROOT	The access path of the current package (including the version branch)
package	The name of the current package
version	The version tag of the current package
package_offset	The directory offset of the current package
package_cmtpath	The package area where the current package has been found
<package>_project	The project name to which the corresponding package belongs
<package>_cmtpath	The package area where the corresponding package has been found
<package>_offset	The directory offset of the corresponding package

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 CMT behaviour.

<package>_tag	The specific configuration tag for the package. By default it is set to $(tag) but can be freely overridden
constituents	The ordered set of constituents declared without any group option
<group-name>_constituents	The ordered set of all constituents declared using a group=<group-name> option

The third set of generated macros are the global use macros. They correspond to the concatenation of the corresponding package specific customizing options that can be deduced from the ordered set of use statements found in the requirements file (taking into account the complete hierarchy of used packages with the exception of those specified with the
-no_auto_imports option in their use statement) :

use_cflags	C compiler flags
use_pp_cflags	Preprocessor flags for the C language
use_cppflags	C++ compiler flags
use_pp_cppflags	Preprocessor flags for the C++ language
use_fflags	Fortran compiler flags
use_pp_fflags	Preprocessor flags for the Fortran language
use_libraries	List of library names
use_linkopts	Linker options
use_stamps	Dependency stamps
use_requirements	The set of used requirements
use_includes	The set of include search paths options for the preprocessor from the used packages
use_fincludes	The set of include search paths options for the fortran preprocessor from the used packages
includes	The overall set of include search paths for the preprocessor
fincludes	The overall set of include search paths options for the fortran preprocessor

macro	usage	default value
cmt_installarea_command
cmt_uninstallarea_command
cmt_install_action		$(CMTROOT)\mgr\cmt_install_action.bat
cmt_installdir_action		$(CMTROOT)\mgr\cmt_installdir_action.bat
cmt_uninstall_action		$(CMTROOT)\mgr\cmt_uninstall_action.bat
cmt_uninstalldir_action		$(CMTROOT)\mgr\cmt_uninstalldir_action.bat
cmt_installdir_excludes		$(CMTROOT)\mgr\cmt_installdir_excludes.txt
cmt_installarea_prefix		InstallArea
<project>_installarea_prefix		$(cmt_installarea_prefix)
CMTINSTALLAREA		C:\Arnault\test\tprojects\PC\InstallArea
cmt_installarea_paths
cmt_installarea_linkopts

macro	usage	default on Unix
X11_cflags	compilation flags for X11	-I/usr/include
Xm_cflags	compilation flags for Motif	-I/usr/include
X_linkopts	Link options for XWindows (and Motif)
make_shlib	The command used to generate the shared library from the static one	${CMTROOT}/mgr/cmt_make_shlib_common.sh extract
shlibsuffix	The system dependent suffix for shared libraries	so
shlibbuilder	The loader used to build the shared library	g++
shlibflags	The additional options given to the shared library builder	-shared
application_suffix	The default extension for applications	.exe
library_prefix	The default name prefix of libraries	lib
library_suffix	The default name suffix of libraries
symlink	The command used to install a symbolic link	/bin/ln -fs
	The command used to remove a symbolic link	/bin/rm -f
build_prototype	The command used to generate the C prototype header file (default to the internal cmt dedicated command)	$(cmtexe) build prototype
build_dependencies	The command used to generate dependencies (default to the internal cmt dedicated command)	$(cmtexe) -quiet -tag=$(tags) build dependencies
lock_command	The command used to physically lock a package	chmod -R a-w ../*
unlock_command	The command used to physically unlock a package	chmod -R g+w ../*
make_hosts	The list of remote host names which exactly require the make command
gmake_hosts	The list of remote host names which exactly require the gmake command