Go to the first, previous, next, last section, table of contents.


8 Descriptors

A project-version descriptor is a file that defines the contents of the project. For project with name P, the project-version descriptor (or just `descriptor') is called `P.prj' and is kept at the root of the project directory tree. When you check in a project, the project descriptor indicates what files need to be included, which have keywords that need to be expanded, and from which previous versions of the those files (if any) the working files were derived. A prcs checkin then creates and checks in an updated descriptor file.

The sections below detail the syntax of the project descriptor file and the standard attribute entries that may appear in it.

Descriptor entry syntax

The syntax of the project descriptor file is a slight variant on Lisp. It consists of `S-expressions' (this is the terminology established by Lisp, so we'll use it here). In general, an S-expression has one of the following forms

label
string constant
(s-exprs)

Where `s-exprs' is (recursively) a sequence of 0 or more s-expressions, separated from each other by whitespace and optionally separated from the surrounding parentheses by whitespace (`whitespace' is any non-empty sequence of blanks, tabs, form feeds, and newlines). We've described the syntax of labels and string constants elsewhere (see section 2 Definitions).

You may include comments in the descriptor; these consist of a semicolon (outside of a string) followed by all characters up to and not including the next newline or the end of the file. Comments have no effect on the behavior of PRCS and are copied from one version of a project descriptor to the next.

The non-nested S-expressions that appear in a descriptor (those that aren't part of some larger expression) each start with an attribute name (a label). The valid attribute names are described in the following sections.

Project-Version attribute

Attribute: Project-Version P M N

This indicates that the descriptor is (or is modified from) the descriptor for version M.N of project P. M must be a valid major version name and N must be a valid minor version name (see section 5 Version Names and Specifiers). The prcs checkin command sets the Project-Version of the checked-in descriptor. See section 5 Version Names and Specifiers.

Project-Description attribute

Attribute: Project-Description string-constant

This attribute is intended to provide a title or short description of the project. By default, prcs checkin leaves it undisturbed.

For example,

(Project-Description "Sample PRCS Project")

Version-Log and New-Version-Log attributes

Attribute: Version-Log string-constant
Attribute: New-Version-Log string-constant

The version log is stored with the descriptor of each version of a project. A prcs checkin initializes it from the New-Version-Log attribute, removing any existing Version-Log attribute, and setting the New-Version-Log to the empty string. The version log is intended to describe the changes made in this version from its predecessor, or to contain other comments about it.

For example,

(Version-Log "Added header.h")
(New-Version-Log "Modified main.c")

Checkin-Time and Checkin-Login attributes

Attribute: Checkin-Time time-specifier
Attribute: Checkin-Login label

These attributes record the login of the user performing the PRCS check-in that created this version and the time at which it was performed. They are set by prcs checkin.

For example,

(Checkin-Time "Sun, 12 Jun 1994 20:00:00 -0700")
(Checkin-Login hilfingr)

Files attribute

Attribute: Files (file1 (internal-file-id1) options1) ...

Each of the 0 or more arguments of the Files attribute denotes one of the constituents of a version. The file arguments give the pathnames of files relative to some root directory. The internal-file-id arguments contain information used by PRCS to identify versions of individual files.

If F is one of the file arguments, then no component of F may be `.' or `..'. Unless one of the options listed for F is :directory (see below), no other file argument in the Files attribute may begin with `F/'.

The precise format of an internal file identifier is not defined, and is subject to change whenever PRCS is revised. Two properties, however, are guaranteed:

The options arguments denote 0 or more labels indicating special properties of the file. At the moment, four are defined.

:no-keywords
indicates that keywords in the file are not to be expanded.
:symlink
indicates the file is a symbolic link, which will be recorded at checkin and reproduced at checkout.
:directory
indicates that the file is a directory, which will be created, if necessary, at checkout. This is useful for having empty directories in your project.
:tag=label
records label as a piece of user-defined information about the file. PRCS does not interpret label; its main use is for filtering in the prcs execute subcommand (see section 6.15 Prcs execute). There may be any number of :tag options attached to a file.

The project descriptor (`.prj' file) is not explicitly included in the Files attribute. Nevertheless, it is implicitly one of the files in each project version.

For example,

(Files
  (empty () :directory)        ; an empty directory
  (pointer () :symlink)        ; a symbolic link
  (realfile () :no-keywords)   ; the only real file in the list
)

Populate-Ignore attribute

Attribute: Populate-Ignore (pattern1 ...)

This attribute is used to inform prcs populate of files that it should not add to the Files list of the project descriptor. It is included as a convenience; you can accomplish the same effect by editing the Files list after running populate.

Each of the pattern arguments is a regular expression (as used by grep). Any path name that prcs populate finds that matches one or more pattern arguments is not added to the Files list (existing names on the list are not affected).

For example, the following filters out object (`.o') files, library archive (`.a') files, core files, files generated by TeX, Postscript (`.ps') files that occur in subdirectory `doc', Emacs backup files, and the executable file `a.out':

(Populate-Ignore ("\\.o$" "\\.a$" "~$" "^a.out$" "^core$"
                  "\\.dvi$" "\\.aux$" "\\.log"
                  "^doc/.*\\.ps"))

Merge-Parents attribute

Attribute: Merge-Parents (merged-against-version
effective-working-version complete (file-action) ...) ...
Attribute: New-Merge-Parents (merged-against-version
effective-working-version complete (file-action) ...) ...

The prcs merge command uses the New-Merge-Parents attribute to record the history of updates to each file. Each merged-against-version indicates a selected version that was merged into the working files, each effective-working-version indicates the effective working version used to select the common version, complete indicates whether the merge against merged-against-version was completed, and each file-action records what action (delete, add, replace, merge, no action) merge took for each file. This information is useful in preventing confusion when the user interrupts a merge operation and then re-executes the merge.

The file-actions entries contain data recording each merge action that takes place. Since the filenames in each merge action need not be the same (see section Files attribute), PRCS records each of up to three filenames for each merge action or an empty list (`()') where a file was not present. In addition, PRCS records which action was taken on each set of files.

The prcs checkin command copies any New-Merge-Parents attribute in the working project descriptor into a Merge-Parents attribute in the new (checked-in) project descriptor. It discards any existing Merge-Parents attribute in the working file.

Each merge-parent in a checked-in version is considered as a parent version. Similarly, each new-merge-parent in a working version is considered as a parent version (see section Parent-Version attribute).

Parent-Version attribute

This attribute, along with the Merge-Parents attribute described above, tracks the history of a project version: Parent-Version records the version from which a project version originally descended, and Merge-Parents records versions against which it was merged.

Attribute: Parent-Version P M N

This has the same form as the Project-Version attribute (see section Project-Version attribute), except that for an initial version (unrelated to any prior version), each of P, M, and N is -*-. The Parent-Version defines the ancestors of a version in the repository as follows:

Given two versions in a repository, any version that is an ancestor to both is called a common ancestor. A common ancestor whose distance from both is minimal is called a nearest common ancestor. It is possible for there to be more than one nearest common ancestor. If so, commands attempting to determine the nearest common ancestor will either abort or ask the user for help.

Each prcs checkin sets Parent-Version to name the Project-Version attribute of the version from which the newly checked-in version is derived. Additionally, it sets the New-Merge-Parents attribute to the Merge-Parents attribute.

Project-Keywords attribute

Attribute: Project-Keywords (keyword value) ...

The Project-Keywords attributes allows the user to define new keywords and their values, which will behave exactly like the builtin keywords (see section 9 Keywords). Each keyword must be unique and must not match one of the builtin keywords. All files contained in the project version described by a descriptor containing a Project-Keywords list will be keyed with each keyword. Each value is either a label or a string and may not contain a newline character. For example, you could include such project meta-data as state labels, release labels, and version numbers:

(Project-Keywords (ReleaseMajorVersion 1)
                  (ReleaseMinorVersion 1)
                  (ReleaseMicroVersion 0)
                  (ReleaseVersion "$ReleaseMajorVersion: 1 $.$ReleaseMinorVersion: 2 $.$ReleaseMicroVersion: 10 $"))
                  (ProjectState "Release")
                  (RealAuthor "Josh")) ; in case the login doesn't
                                       ; provide enough information.


Go to the first, previous, next, last section, table of contents.