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.
In order to learn more about project description files, it is probably best to start with a small example. At Elego, the program prjm itself is (better: was some time ago) a project which is built from nine different software packages. Though these packages are written in Modula-3 and not in C or C++, syntax and semantics of the project description are entirely the same.
So here is the current project description file of prjm:
# The root where collections of packages are kept
collectionroot ${HOME}/work
# two package collections definitions, each consisting of a
# symbolic name (e.g. libs) and a pathname (e.g. m3libs) under
# which the collection can be found in the file system and the
# version control repository
collection libs at m3libs
collection progs at m3progs
# nine package definitions describe the complete project
package pkg_base in libs
package prjbase in libs
package miscutils in libs
package depgraph in libs
package m3tkutils in libs
package prjm in progs
package fileinfo in libs
package pkg_config in libs
package pkg_vc in libs
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. See Section 3.8 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.