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.
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.
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.
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")
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")
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)
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:
prcs checkin
will assign it an internal file identifier
(possibly unchanged from that of the working version) in the same
internal-file family. If a working file has a null internal file
identifier (`()'), prcs checkin
will put it in a new
internal-file family, otherwise unpopulated. Internal-file families are
useful
for certain kinds of version comparisons and merges.
The options arguments denote 0 or more labels indicating special properties of the file. At the moment, four are defined.
:no-keywords
:symlink
:directory
:tag=label
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 )
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"))
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).
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.
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.
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.