# Differences with previous versions of CMT

## Converting a package that was managed with previous versions of CMT (or methods)

Although many major internal evolutions occurred in this version of CMT, the primary source of information handled by CMT, i.e. the syntax - and semantics - of the `requirements` file did not change. Therefore we expect that the effects of using this new version to a package already managed by previous versions of CMT, will remain limited.

Generally, it is enough to just re-configure the package, using the well known command

`> cmt config`

This will result in re-generating the `setup` scripts, and verifying `Makefile`. A proper CMT `Makefile` now contains at least the two following lines: `include ${CMTROOT}/src/Makefile.header include ${CMTROOT}/src/constituents.make`

The first one was already generally present in `Makefiles` used in previous versions of CMT and the second one is new. It replaces the former `include constituents.make`

These two lines are the only required lines to be present in an operational `Makefile`. However, the user is entirely free to install additional make statements at any location for his/her own purpose.

No further operation is then needed. All other `makefile` fragments will be automatically generated at make time. It is even recommended to remove any existing `makefile` fragment generated by previous versions of CMT. This can be easily done by using the dedicated `configclean` target as follows `> gmake configclean`

it might also be useful (if not recommended !) to clean the binary directories and rebuild it as follows: `> gmake config > gmake`

## Differences in the syntax of the Unix commands

The CMT command handler (i.e. the `cmt` command) received a few modifications but which mainly consisted in removing some of the existing options which have been automated. This is the case for the `genmake` command since now, `Makefile` generation is automatic and transparent..

The `show` options are unchanged.

## Operations in a Windows environment

A graphical and interactive application (`cmtw`) is now provided on Windows (95/98/NT) environments. This application permits to browse package directories, to select any version of any package. Its configuration is shown, and interactive edition is possible on its requirements file. A few operations are also possible, such as the generation of MSDev configuration files, so as to permit to directly work of packages managed by CMT with the MSDev development environment. Currently this support is still evolving and user might see limitations in the dialog between CMT and MSDev (only the constituent definitions - applications and libraries - and the use mechanism - package relationships - are understood in the context of MSDev). Users of these new facilities are kindly invited to send their comments, bug observations, suggestions or even contributions to the author.

# Some scenarios

These scenarios correspond to typical situations a user may encounter during his or her development activities. They are presented with increasing complexity and will generally refer to each other, avoiding some duplication of the explanations. Therefore it is recommended to a new user to have a first reading of these sections roughly following the order. However, for already experts users it might be appropriate to skip some of the first sections (but the section on how to use CMT since this must be understood before any other operation described here).

## Using CMT on Unix

Any user willing to use CMT in a unix environment should first setup a few environment variables by sourcing one of the appropriate script, according to the shell family (sh or csh) the user is considering: `source /lal/CMT/v1r3/mgr/setup.csh . /lal/CMT/v1r3/mgr/setup.sh`

Of course, the user has to precisely know where CMT is installed. In the example above, we use the location used at LAL where it originates from. In your environment, you will have to ask your software manager about the actual CMT location. A typical operation then consists in installing this line in the appropriate user's login script so as to have CMT automaticly defined at each login session.

(You may also have to understand the CMT installation procedures)

## Creating a new test package

A test package is a very simple unstructured package not meant to be exported in any way (ie. not used by any other package). Such a package generally corresponds to a simple test application, where the developper wants to benefit from the facilities provided by CMT (automatization of the building procedure, inheritance of usual compilation and linking options, possibility to use other structured packages - managed by CMT) while keeping the simplicity of an unstructured area, where everything (sources, binaries, etc..) is kept in one sigle directory.

Let's consider a simple Fortran application named test made of two sources a.f and b.f . The only operation you have to do to build it is to create a simpletext file named requirements and containing only one line as follows: `application test a.f b.f`

The very first time you install this test package you have to run the installation command: `cmt config` Then you can immediately build it as follows: `gmake`

## Creating a new package using the CMT conventions

A CMT package is a package able to both use other CMT-managed packages and be used by other packages. The only constraints for packages to be fully managed by CMT and thus subject to use-relationships to each other are:

1. to be installed in the conventional minimal structure at least composed of:

1. a root directory named with the package name
2. a version directory immediately below the root directory
3. some branches below the version directory, among which only the `mgr` and the `src` are mandatory. Any other set of branch is permitted and can be understood by CMT (typical structures elements are the `doc` branch, include directories named after the package name, alternate source directories etc...)

2. to provide one text file named `requirements` and located in its `mgr` branch.

These conventions are easily applied if one creates the package using the parameterised config option of CMT as follows: `> cmt config A v1`

This installs the minimal structure for the version v1 of the package `A` below the current directory. This results in creating the directory structure (with the `mgr` and the `src` branch), an empty `requirements` file and a minimal `Makefile` (both in the `mgr` branch).

A complete sequence resulting in a working application could be: ``

> cd (somewhere)

> cmt config A v1

> cd A/v1/mgr

> vi requirements

application A a.c b.c

> vi ../src/a.c

...

> vi ../src/b.c

...

> gmake

> ../${CMTCONFIG}/A.exe

Next sections will present more complex examples of how to build libraries or complex applications.

## Defining a new application

We are now working in an installed package (which could be a test package or a structured one). Defining an application consists in the following operations:

1. Selecting a name (e.g. A) for the application. This name will be used in many places as a mnemonic for the application,

- it defines the constituent name,
- it is the file name of the application's executable (with a default extension of `.exe`, i.e. `A.exe`),
- it yields a dedicated target of the `Makefile`,
- and it is used as a prefix for various Make macros (such as `A_cppflags`, `A_linkflags`, etc…)

1. Installing its definition in the requirements, providing the list of its private source files

application A a1.c a2.c a3.cxx ../B/*.cxx

2. Possibly adding some make macro definitions, specific to this application, still in the requirements file

macro A_cppflags " -g "

Building the application is then entirely deduced from these definitions at make time

`

> gmake

`

And the executable is by default built into `../${A_tag}/A.exe` .The `A_tag` macro gets the default value of `${CMTCONFIG}` (which is always built when CMT is originally set up) but can receive any other definition provided either as arguments to the make command or statically within the `requirements` file

`

> gmake A_tag=debug

`

or

> macro A_tag "debug"

## Defining a new library

This operation is quite similar to the one described for defining an application. Here again a name for the constituent will have to be carefully chosen since it will be used as a mnemonic for all configuration items related to this library. Under Unix, for instance, - and for a constituent named A - the library will be named libA.a, libA.so or libA.ls according to the style of library (static or shared) and the operating system. Under Windows, the library is named Alib.lib .Similar make macros are available too for a library (see the table showing the standard make macros understood by CMT).

In addition, a specific macro named after the package name and suffixed with linkopts (e.g. P_linkopts) provides the exported linker options to be applied to any client package. This macro will generally include a set of -L and -l options under Unix.

## Installing CMT for the first time

### Installing CMT on your Unix site

This section is of interest only if CMT is not yet installed on your site, of if you need a private installation.

The first question you need to answer is the location where to install CMT. This location is typically a disk area where most of packages managed in your project will be located.

Then, you have to fetch the distribution kit from the Web at http://www.lal.in2p3.fr/SI/CMT/CMT.htm. You must get at least the primary distribution kit containing the basic configuration information and the CMT sources. This operation results in a set of directories hanging below the CMT root and the version directory. The src branch contains the sources of CMT, the fragments branch contains the makefile fragments and the mgr branch contains the scripts needed to build or operate CMT.

The very first operation after dowloading CMT consists in running the INSTALL shell script. This will build the setup scripts required by any CMT user.

Then you may either decide to build CMT by yourself or fetch a pre-built binary from the same Web location. The prebuilt binary versions may not exist for the actual plateform you are working on. You will see on the distribution page the precise configurations used for building those binaries.

In case you have to build CMT yourself, you need a C++ compiler capable of handling templates (although the support for STL is not required). Their is a Makefile provided in the distribution kit which takes g++ by default as the compiler. If you need a specific C++ compiler you will override the cpp macro as follows:

`

gmake cpp=CC

`

The cppflags macro permits too to override behaviour of the compilation.

Another important concern is the way CMT will identify the plateform. CMT builds a configuration tag per each type of plateform, and uses this tag for naming the directory where all binary files will be stored. As such this tag has to be defined prior to even build CMT itself.

CMT builds the default configuration by running the cmt_system.sh script found in the mgr branch of CMT. Run it manually to see what is the default value provided by this script. You might consider changing its algorithm for your own convenience.

### Installing CMT on a Windows or Windows NT site

This section is of interest only if CMT is not yet installed on your site, of if you need a private installation.

The first question you need to answer is the location where to install CMT. This location is typically a disk area where most of packages managed in your project will be located.

Then, you have to fetch the distribution kit from the Web at http://www.lal.in2p3.fr/SI/CMT/CMT.htm. You must get at least the primary distribution kit containing the basic configuration information and the CMT sources. This operation results in a set of directories hanging below the CMT root and the version directory. The binary kit provided for Windows environments will generally fit your needs.

The next operation consists in defining a few registries (typically using the standard RegEdit facility):

- HKEY_CLASSES_ROOT/Software/CMT/root will contain the root directory where CMT is installed (eg. "e:").
- HKEY_CLASSES_ROOT/Software/CMT/version will contain the current version tag of CMT ("v1r3" for this version).
- HKEY_CLASSES_ROOT/Software/CMT/path/ may optionally contain a set of text values corresponding to the different package global access paths.
- HKEY_CURRENT_USER/Software/CMT/path/ may contain a set of text of text values corresponding to the different package private access paths.