13. 2. 1 - The package structuring style
Packages are installed in a directory structure that
can optionnally include a version directory (just after
the top directory of the package name). This is controlled
through the structuring style
or structuring
strategy
parameters specified using one of the
following means:
- Through the environment variable
CMTSTRUCTURINGSTYLE
taking one of the
alternate values:
with_version_directory
without_version_directory
- Through the command line options
-with_version_directory
or
-without_version_directory
- Through the structure_strategy
specification entered into the project file of the current project, using the alternate values:
with_version_directory
without_version_directory
It should be noted that the command line option will
take precedence over the strategy specification, in case
of conflict.
13. 2. 2 - Meta-information : author, manager
The author and manager names
13. 2. 3 - package, version
The package name and version. These statements are purely
informational.
13. 2. 4 - Constituents : application, library, document
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:
| option
|
validity
|
usage
|
| -s=directory
|
any |
switch to a new default directory (1)
|
| -x=regexp
|
any |
specify an exclusion regular expression to be applied to the sources (1)
|
| -k=regexp
|
any |
specify a finer selection regular expression to be applied to the sources (1)
|
| -no_share
|
libraries |
do not generate the shared library |
| -no_static
|
libraries |
do not generate the static library (not yet implemented
) |
| -prototypes
|
applications, libraries |
do generate the prototype header files |
| -no_prototypes
|
applications, libraries |
do not generate the prototype header files |
| -check
|
applications |
generate a check target meant to execute the rebuilt application |
| -group=<group-name>
|
any |
install the constituent within this group target |
| -suffix=<suffix>
|
applications, libraries |
provide a suffix to names of all object files generated for this constituent (2)
|
| -import=<package>
|
applications, libraries |
explicitly import for this constituent the standard macros from a package that has the -no_auto_imports
option set |
| -target_tag
|
any |
construct a specific tag named
target_<constituent>
. This tag will
only be active during the make session for this
constituent. (4)
|
| -windows
|
applications |
When used in a Windows environment, generates a GUI-based application (rather than a console application) |
| <var-name>=<var-value>
|
any |
define a variable and its value to be given to the make fragment (3)
|
-
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.
-
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
-
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)
- This makefile fragment is meant to contain some text
conversion actions and defines a document type
named
doc_to_html
.
- This constituent exploits the document type
doc_to_html
to convert the source FooA.doc
into an html file.
- 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.
-
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.
Groups permit the organization of the constituents that must
be consistently built at the same development phases or with similar
constraints.
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 :
# Constituents belonging to the default all group
... constituents without group specification ...
library Foo *.cxx
# Constituents belonging to specific groups
library Foo-objy -group=objy <sources making use of Objectivity>
application FooGUI -group=graphics <sources making use of Qt>
application BarGUI -group=graphics <sources making use of Qt>
(Beware of the position of the -group option which must be
located after the constituent name. Any other position will be
misunderstood by CMT)
Then, running gmake all
would only rebuild the un-grouped
constituents, whereas running
> gmake objy
> gmake graphics
in the context of the Foo
package would rebuild objy
related or graphics
related constituents.
Some computer languages are known by default by CMT
(C
, C
++, Fortran77
, Java
,
lex
, yacc
). However it is possible to extend
this knowledge to any other langage.
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:
language fortran90 \
-suffix=f90 -suffix=F90 \ [1]
-linker=$(f90link) \ [2]
-preprocessor_command=$(ppcmd)
- The recognized suffixes for source files will be f90
and F90
- 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).
macro for "f77" \
...
macro fcomp "$(for) -c $(fincludes) $(fflags) $(pp_fflags)"
We therefore simply replace these macros by new macros
named f90comp
and f90
, defined as
follows:
macro f90 "f90"
...
macro f90comp "$(f90) -c $(fincludes) $(fflags) $(pp_fflags)"
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:
language idl -suffix=idl -fragment=idl -extra_output_suffix=_skel
where, in this case, two object files are produced for each
IDL source file, one named <name
>.o
the
other named <name
>_skel.o
.
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:
|
|
|
| symbol |
: |
symbol-type
symbol-name
default-value
[
tag-expr
value
...
]
|
| symbol-type |
: |
definition
|
|
| |
modification
|
| definition |
: |
macro
|
|
| |
set
|
|
| |
path
|
|
| |
action
|
|
| |
alias
|
| modification |
: |
macro_prepend
|
|
| |
macro_append
|
|
| |
macro_remove
|
|
| |
macro_remove_regexp
|
|
| |
macro_remove_all
|
|
| |
macro_remove_all_regexp
|
|
| |
set_prepend
|
|
| |
set_append
|
|
| |
set_remove
|
|
| |
set_remove_regexp
|
|
| |
path_prepend
|
|
| |
path_append
|
|
| |
path_remove
|
|
| |
path_remove_regexp
|
| tag-expr |
: |
tag
[
&
tag
...
]
|
- 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 :
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 "
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.
An example of a symple action:
action directory "ls $(dir_options)" WIN32 "dir $(dir_options)"
Like other symbols, actions can be visualized using
the cmt show actions
or the cmt show action
<name>
command.
Some specialized mechanims are available on actions,
in order to execute in various ways the corresponding
shell commands.
Actually two operating modes are supported:
- Immediate mode
This can be done via the cmt do
command:
> cmt <action-name>
or, when the action name conflicts with a native CMT keyword,
> cmt do <action-name>
This mode immediately executes the specified
command, after locally setting all environment
variables known from the current package.
- Through make
> cmt make <action-name>
Describe the relationships with other packages; the
generic syntax is :
use <package> [ <version> [ <offset> ] ] [ -no_auto_imports=<package> ... ]
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 offset
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).
The additional -no_auto_imports
options
suppress the automatic inheritance of some standard
parameters from the specified used packages, such as
include paths, compiler flags, ...
Examples of such relationships are :
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
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:
----------------
package A
use B v1
use D v1
----------------
----------------
package B
private
use C v1
use D v1
----------------
- 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
:
| package
|
the name of the current package |
| PACKAGE
|
the name of the current package in upper case |
| version
|
the version tag of the current package |
| path
|
the access path of the current package |
| project
|
the project name of the current package |
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:
-
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/
-
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.
-
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).
According to whether the -global
qualifier was
used in the pattern definition, the aplication mode will
be completely different.
- Normal patterns
Such patterns must be applied explicitly using
the apply_pattern
construct
Doing so, it is possible to specify custmization
values for user defined template parameters
pattern TA macro <base>AAA "AAA"
apply_pattern TA base=abc
apply_pattern TA base=def
In the apply_pattern
syntax, it is even
possible to simply ommit
the keyword itself,
and thus using the pattern name as a plain CMT
keyword. The previous example becomes:
TA base=abc
TA base=def
This can be seen as a way to extend
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
apply_pattern
keyword, so as to avoid any
possible ambiguity.
- Global patterns
(ie when the -global
qualifier is used
In this case, the pattern is automatically applied
to all
packages that effectively see the
pattern definition, which includes all clients of
the package defining the pattern.
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.
Conversely it is possible to inhibit the
automatic application of a global pattern in a
particular package by using the following
statement:
ignore_pattern <name>
13. 2.10 - cmtpath_patterns
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
path CMTPATH "/ProjectA"
path_append CMTPATH "/ProjectB"
cmtpath_pattern \
macro_prepend pp_cppflags " -I<path>/InstallArea/include "
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
-I/ProjectA/InstallArea/include -I/ProjectB/InstallArea/include
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.
branches <branch-name> ...
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
.
13. 2.12 - Strategy specifications
Users can control the behaviour of CMT
through a
set of strategy specifications. The current implementation
provides such control over several aspects :
-
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 |
-
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.
<project>_<have_item>
<project>_<have_not_item>
Examples
<project>_prototypes
<project>_no_prototypes
<project>_with_install_area
<project>_without_install_area
<project>_config
<project>_no_config
<project>_root
<project>_no_root
<project>_cleanup
<project>_no_cleanup
13. 2.13 - setup_script, cleanup_script
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).
Note that this behaviour is expected to become
obsolete in some next release of CMT. The default
include search path of ../src
will then simply
disappear, and the include_path
statement will
become meaningless. When this happens, include search
paths will always have to be explicitly specified using the
include_dirs
statement. In order to anticipate
this evolution, it is suggested to always use
include_path none
and add all include search
directories using the include_dirs
statement.
Add explicit specifications for include access
paths. The value may be provided through a macro
reference.
The statement is sensitive to private scoping.
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 :
- some are provided by CMT
itself (they
correspond to its internal behaviour)
- others handle the language support
- 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 |
13. 2.17 - public, private
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
- the declaration of include search paths (via the
include_dirs
statement)
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)
By using the public
or private
keywords,
one defines scoping
sections. This sections
continues until:
- another scoping statement is found, which simply
switch to this new mode
- an end_private
or end_public
keyword is found, in which case the scoping mode is
reset to the state prior to the previous matching
private
or public
statement. This
latter mechanisms permits in particular to define
autonomous scoping sections within pattern
s
.
By default cmt
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.
This standard behaviour though is not applied when
running cmt broadcast
or cmt show
uses
, and in this case all statements public or
private, are always considered, even in used
packages.
However it is always possible to override the default
behaviours by using the -private
or
-public
modifier to the cmt
command:
13. 2.18 - tag, apply_tag
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 :
tag Foo [1]
tag Bar Foo FooA FooB [2]
apply_tag Bar [3]
- This simply declares a tag. This does not
activate it by default
- 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
- 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.
This utility (a shell script combined with a C++
application) provides a centralised access to various commands
to the CMT
system. The first way to use cmt
is
to run it without argument, this will print a minimal help text
showing the basic commands and their syntax :
> cmt command [option...]
command :
none
awk
broadcast [-select=list] [-exclude=list] [-local] [-global] [-begin=pattern] [-depth=n] <command> :
apply a command to [some of] the used packages
build <option> : build actions. (Try cmt help build)
build constituent_makefile <constituent> : 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 <constituent> : generate library trigger file
build windefs <library_name> : generate def file for Windows shared libraries
check <option> : check actions. (Try cmt help check)
check configuration : check configuration
check files <old> <new> : compare two files and overrides <old> by <new> if different
check version <name> : 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 <package> <version> [<path>] : create and configure a new package
create_project <project> <name> [<path>] : create and configure a new project
cvsbranches <module> : display the subdirectories for a module
cvssubpackages <module> : display the subpackages for a module
cvssubprojects <module> : display the subprojects for a module
cvstags <module> : display the CVS tags for a module
do <action> [<param>=<value>] ... : Execute an action
expand model <model> :
filter <in> <out> : filter a file against CMT macros and env. variables
help | -help | --help : display this help
load
lock [<p> <v> [<path>]] : lock a package
relocate : generate setup and cleanup scripts (without makefiles)
remove <package> <version> [<path>] : remove a package version
remove library_links : remove symbolic links towards all imported libraries
run '<command>' : apply a command
run_sequence <sequence file> : execute a cmt equence file
set version <version> : generate a version file in the current package
set versions : generate version files into packages
setup [-csh|-sh|-bat] : generate a setup script
show <option> : query actions. (Try cmt help show)
show action <name> : a formatted action definition
show action_value <name> : 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 <name>: constituent definition
show constituent_names : constituent names
show constituents : constituent definitions
show cycles : cycles in the use graph
show fragment <name> : one fragment definition
show fragments : fragment definitions
show groups : group definitions
show include_dirs :
show language <name> : language definition
show languages : language definitions
show macro <name> : a formatted macro definition
show macro_value <name> : 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 <name> : 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 <name> : a formatted set definition
show set_names : set names
show set_value <name> : a raw set definition
show sets : set definitions
show strategies : all strategies (build & version)
show tags : all currently active tags
show use_paths <pack> : all paths to the used package
show uses : used packages
show version : version of the current package
show versions <name> : visible versions of the selected package
system : display the system tag
unlock [<p> <v> [<path>]] : unlock a package
version : version of CMT
global options :
-quiet : don't print errors
-use=<p>:<v>:<path> : set package version path
-pack=<package> : set package
-version=<version> : set version
-path=<path> : set root path
-f=<requirement-file> : set input file
-e=<statement> : add a one line statement
-tag=<tag-list> : select a new tag-set
-tag_add=<tag-list> : add specific comma-separated tag(s)
-tag_remove=<tag-list> : remove specific comma-separated tag(s)
-warnings : display various warnings
-with_version_directory : reset to default structuring style
-without_version_directory : switch structuring style
The following sections present the detail of each available command.
13. 3. 1 - Global options of the cmt command
These options of the general form
-<option>
or
-<option>=<value>
should be provided
before
the command itself. They give special hints
to cmt onto how to perform the command.
Some options have meaning over all commands (such as
the -quiet
option) while some others only have a
meaning in the context of some specialized commands (such
as the -with_version_directory
option which is
only useful for the create
or co
commands)
The following table describes the various global
options of the cmt
tool:
| option
|
effect
|
commands
|
| -quiet
|
don't print errors |
all
|
| -use=<p>:<v>:<path>
|
set current package version and path in one option |
all
|
| -pack=<package>
|
set current package, version and root path |
all
|
| -version=<version>
|
| -path=<path>
|
| -f=<requirement-file>
|
override input file |
all
|
| -e=<statement>
|
add a one line statement |
all
|
| -tag=<tag-list>
|
select a new tag-set |
all
|
| -tag_add=<tag-list>
|
add specific comma-separated tag(s) |
all
|
| -tag_remove=<tag-list>
|
remove specific comma-separated tag(s) |
all
|
| -warnings
|
displays various warnings, such as invalid PATH items |
|
| -with_version_directory
|
reset to default structuring style |
|
| -without_version_directory
|
switch structuring style |
|
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 cmt show uses
command, which also indicates in which order the broadcast is
performed. When the all_packages
option, the set of
packages reached by the broadcast is rather the same as the one shown
by the cmt show packages
command, ie all CMT
packages
and versions available through the current CMTPATH
list.
Typical uses of this broadcast
operation could be:
csh> cmt broadcast cmt config
csh> cmt broadcast - gmake
csh> cmt broadcast '(cd ../; cvs -n update)'
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)
sh> cmt broadcast -begin=Cm gmake (1)
sh> cmt broadcast -select=Cm gmake (2)
sh> cmt broadcast -select='/Cm/ /CSet/' gmake (3)
sh> cmt broadcast -select=Cm -exclude=Cmo gmake (4)
sh> cmt broadcast -local gmake (5)
sh> cmt broadcast -depth=<n> gmake (6)
sh> cmt broadcast -global gmake (7)
sh> cmt broadcast -all_packages gmake (8)
According to the option, the loop will only operate onto:
- the first package which path contains the string
"Cm"
, and then all other reachable packages (in
case other specifiers are used)
- the packages which path contains the string "Cm"
- the packages which path contains either the string
"/Cm/"
or the string "/CSet/"
- the packages which path contains the string "Cm"
,
but which does not contain the string "Cmo"
- the packages at the same level as the current package
- the packages at the same level as the current package or
among the <n> first entries in the CMTPATH
list
- the packages at any level of the CMTPATH search list
- all the packages and versions currently available
through the CMTPATH
list
The environment variables as specified in the
requirements files of the use graph are internally pre-set
before running the specified shell command. Thus it's not
required to source
the setup scripts before using
the broadcast
command
13. 3. 2. 1 - Specifying the shell command
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:
- The current shell first parses the complete command line
- CMT catches all possible options given to the broadcast command itself
- CMT then gets the rest of the command line and makes it the shell command to be executed during the broadcast scan.
- This command line may be subject to template substitution (see below) by CMT
- Eventually the command line is passed to the local shell (which may then perform additional parsing actions)
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
13. 3. 2. 2 - Templates in the shell command
Similarly to what exists in the pattern
mechanism, some standard
templated
values can be embedded inside the
command to be executed by the broadcast action. They take
a standard form of
<template-name>
. 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:
| <package_cmtpath>
|
The element in the CMTPATH search list where the package has been found |
| <package_offset>
|
The directory offset to cmtpath |
| <package>
|
The package name |
| <version>
|
The version of the package |
The next example shows a typical broadcast command listing the
header files as expected in the conventional location
../<package>
:
> cmt broadcast 'ls ../<package>'
[...]
#--------------------------------------------------------------
# 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
[...]
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
<>
syntax by the shell.
13. 3. 3 - cmt build <option>
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.
CMT is able to recursively compute the dependencies
implied by the include
statements found in
the source files. However it's also possible to make
plain use of the standard mechanisms provided by some
standard tools like cpp -M
. In this case, it
will be required to format
the output produced
by the selected tool so as to let CMT parse it and
properly deduce the dependencies. Formatting the
output of external tools may require to interface the
tool itself e.g. using a shell script.
The standard CMT macro
$(build_dependencies)
must be used to specify
an alternate dependency builder. The default value is:
$(cmtexe) -quiet -tag=$(tags) build dependencies
The expected output format from any dependency builder is as follows:
A Unix shell script in
${CMTROOT}/mgr/cmt_build_deps.sh
is offered
as an example of how to interface the standard cpp
-M
command with CMT. It can be declared as a
substitute to the internal mechanism as follows:
macro build_dependencies "${CMTROOT}/mgr/cmt_build_deps.sh"
Of course this shell script should be considered as
an example and might have to be adapted for other
dependency builders, or for Windows.
- 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 requirements 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.
13. 3. 4 - 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.
An empty output means that everything is fine.
13. 3. 5 - cmt check files <reference-file> <new-file>
This command compares the reference file to the new file, and
substitues the reference file by the new one if they are
different.
If substitution is performed, a copy (with additional
extension sav
) is produced.
13. 3. 6 - cmt checkout ...
See the paragraph
on how to use cvs together with CMT
, and more specifically the
details on checkout oprations
.
This is simply a short cut to the cmt checkout
command.
13. 3. 8 - 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 requirements files
of the used packages.
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).
csh> cd ~/Packages/Foo/v1/cmt
csh> cmt config
To be properly operated, one must already
be in
the cmt
or mgr
branch of a package (where the
requirements 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)
It should be noted however that when using
actions
, such as the one defined by default to
launch make
tools neither cmt config
nor
source setup
are required any longer.
13. 3.10 - cmt create <package> <version> [<area>]
This command creates a new package or a new version of a package
csh> cmt create Foo v1
or:
csh> cmt create Foo v1 ~/dev
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
A version directory may be created according to the
structuring style or structuring strategy parameters
specified using one of the following means:
- Through the environment variable
CMTSTRUCTURINGSTYLE
taking one of the
alternate values:
with_version_directory
without_version_directory
- Through the command line options
-with_version_directory
or
-without_version_directory
- Through the structure_strategy
specification entered into the project file of the current project, using the alternate values:
with_version_directory
without_version_directory
It should be noted that the command line option will
take precedence over the strategy specification, in case
of conflict.
13. 3.11 - cmt expand model [-strict] <model-string>
This command produces on the standard output an
expansion
of the model string given in the
argument.
The expansion consists in:
- Expanding macros referenced in the model string
using the standard notations $()
or
${}
or %%
> cmt expand model "abcd $(CMTVERSION) efgh"
abcd v1r19 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
...
- A simple expansion using the non-strict model
syntax. P1
is substituted, but
$(P2)
becomes empty
- The same using the strict model. Here P2 is valued.
- A more complex model, using a recursive
expansion described in B
showing how
parameter values are transmitted
- 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.
- 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.
13. 3.12 - cmt filter <in-file> <out-file>
This command reads <in-file>, substitutes all occurences
of macro references (taking either the form
$(macro-name
)
or ${macro-name
}
) by values deduced from corresponding macro specifications
found in the requirements files, and writes the result into
<out-file>.
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...
13. 3.13 - cmt help | --help
This command shows the list of options of the cmt
driver.
13. 3.14 - cmt lock [ <package> <version> [<area>] ]
This command tries to set a lock onto the current package (or onto the
specified package). This consists in the following operations:
- Check if a conflicting lock is already set onto this
package (ie. a lock owned by another user).
- 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>
- 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 ../*"
13. 3.15 - cmt remove <package> <version> [<area>]
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, all
files below
the version directory will be definitively removed. Therefore
this command should be used with as much care as possible.
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.
13. 3.16 - cmt remove library_links
This command removes symbolic links towards all imported
libraries which had been installed using the
cmt build library_links
command. This command is generally transparently executed
when one runs gmake clean
13. 3.17 - cmt run [shell-command]
This command runs any shell command, in the context of the
current
package.
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.
13. 3.18 - cmt set version <version>
This command creates and/or fills in the
version.cmt
file for a package structured without
the version directory.
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.
13. 3.19 - cmt set versions
This command applies recursively the cmt set version
...
command onto all used packages using a broadcast operation.
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
13. 3.20 - 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
requirements
files of the used
packages.
This command is internally used in the
setup.[c]sh
or setup.bat
shell script,
itself generated by the cmt config
command.
13. 3.21 - cmt show <option>
- 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
requirements
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
requirements 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 v1r19 (/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)
- 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
- Sub-uses are expanded only once and indented
according to the depth in the graph
- 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)
- The second section shows the effective ordered
set of use statements resolved by CMT according to
the combined use specifications.
- 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.
This command displays the current value assigned by default to
the CMTCONFIG
environment variable.
13. 3.23 - cmt unlock [ <package> <version> [<area>] ]
This command tries to remove a lock from the current package (or from the
specified package). This consists in the following operations:
- Check if a conflicting lock is already set onto this
package (ie. a lock owned by another user).
- If not, then remove the text file named lock.cmt
from the
cmt/mgr
branch of the package.
- 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 ../*"
13. 3.24 - cmt version | --version
This command shows the current verion of CMT
, including (if
applicable) the actual patch level. This always corresponds to
the corresponding CVS tag assigned to CMT
sources.
13. 3.25 - cmt cvstags <module>
(see the section on how tu use
CVS
together
with CMT
for more details on this command)
13. 3.26 - cmt cvsbranches <module>
13. 3.27 - cmt cvssubpackages <module>
13. 3.28 - cmt cvssubprojects <module>
