8.1. Projects and Project Description Files

The ComPact notion of project is currently very simple: a project is a set of packages picked from one or more package collections, which together form the base of a delivered product or part of a product. The product may consist of one or more programs, libraries, documents, or whatever you can think of, which are derived from the sources of the project's packages.

Project description files are used to declare all elements of a software project. As mentioned earlier, projects consist of packages. To add a bit of flexibility, one more level of abstraction is introduced: Packages are grouped together to collections, which are sets of packages located at the same place (and possibly sharing some common characteristic). In a package description file, the names of packages and collections and their location is defined.

Every project description file consists of three small sections: A declaration of the root directory of collections, a declaration of one or more collections, and a declaration of one or more packages.

Here is an example project description file:

    # The root where collections of packages are kept
    collectionroot ${HOME}/work

    # a package collection definition, which consists of a
    # symbolic name and a pathname under which the collection can
    # be found in the file system and the version control repository
    collection gnu at gnu

    # six package definitions describe the complete project
    package cvs-config in gnu
    package cvs-diff   in gnu
    package cvs-error  in gnu
    package cvs-lib    in gnu
    package cvs-zlib   in gnu
    package cvs-main   in gnu
   

You will notice that each collection has a name and a location which is relative to the collection root, while each package has a name and a location that is relative to a collection.

The declaration of collectionroot may contain the environment variables HOME, USER, and PRJ_ROOT, which are expanded according to their current value in the environment when prjm is run. Using this mechanism of variable replacement, you can write project description files that can be used by different members of a project while pertaining the same overall structure of all project elements.

Every line beginning with the character `#' in a project description file is a comment. It is a good idea to use comments to explicitly describe the purpose and meaning of each element of the project. Other people that have to use your project description (and perhaps you yourself when you check it out again after some months) will appreciate every additional information about the project.

Each declaration of a collection or a package should be fit on one line. You may use any amount of spaces or tabulators to separate words inside the declarations.

A project description file may also contain snapshot and release declarations. Usually, these declarations are created automatically by prjm by freezing the current state of the project, but you may also define some yourself. Consult the chapter about snapshots and releases in the project manager handbook for the syntax of snapshots and releases and how they are created.

Usually snapshot and release delcarations are not entered manually into the project desription file PrjDesc, but are automatically generated by prjm. To be able to differentiate between user defined and generated declarations, there is a sub directory snaps, in which complete project descriptions with automatically generated snapshots reside.

This subdirectory is automagically updated by prjm each time a new snapshot or release is created. The project description file PrjDesc itself is never touched by prjm.