.TH SPMSINTRO 1P "1 July 1985" .UC 4 .SH NAME spmsintro - introduction to SPMS commands .SH INTRODUCTION The Software Project Management System (SPMS) is a system for the management of medium- to large-scale software systems. SPMS provides, within the UNIX environment, a number of commands which can greatly simplify many tasks associated with program development and maintenance. SPMS does not attempt to duplicate existing UNIX program development tools such as .I make or .I SCCS, but instead provides a way of coordinating these tools. .PP Each software package managed by SPMS is organized as a project. A project is a collection of directories, each of which supports a specific activity such as program development, testing, or documentation. There is no restriction on the number of directories belonging to a project. The directory layout is arbitrary, and can be altered to reflect the changing needs of the package. Projects can be nested to any level and a mechanism is provided for executing commands globally over an entire project hierarchy. .SH DESCRIPTION .PP \fBGetting Started\fR .PP Before using SPMS for the first time you must do the following \- .PP If you are a \fBC shell\fR, (\fIcsh\fR), user: .IP 1. Include the directory `/usr/new' in the command search path. This is done by altering the PATH variable in one of the startup files, `.cshrc' or `.login', in the home directory. .IP 2. Add the following aliases to the `.cshrc' file .br alias chproject \'eval \`\^"chproject" \\!*\`\^\' .br alias pd \'eval \`\^"pd" \\!*\`\^\' .IP 3. Add the following command to the `.login' file .br chproject ^ .IP 4. Convert the home directory to a project root directory by typing .br /usr/new/mkproject \-d ^ .IP 5. Execute the `.cshrc' and `.login' files by typing .br source .cshrc .br source .login .PP If you are a \fBBourne shell\fR, (\fIsh\fR), user: .IP 1. Include the directory `/usr/new' in the command search path. This is done by altering the PATH variable in the startup file, `.profile', in the home directory. .IP 2. Add the following command to the `.profile' file: .br eval \`chproject \\^\^\` .IP 3. Convert the home directory to a project root directory by typing .br /usr/new/mkproject \-d \\^ .IP 4. Execute the `.profile' file by typing .br . .profile .PP \fBGlobal Operations\fR .PP The means for executing a command over an entire software package is provided by the .I pexec command. By labeling each project directory according to the type of activity that it supports, global operations can be restricted to specific directories. These labels are known as \fItype labels\fR. In some instances, the directories affected by a global command must be processed in a particular order. This ordering is achieved by appending priorities to type labels. For example, if the project directories `include', `cmd1', `cmd2', `lib1', and `lib2' have the following labels, .PP .nf .ta 1.0i 2.5i include print.0, src, update.100, include cmd1 print.1, src, update.300, cmdsrc cmd2 print.1, src, update.300, cmdsrc lib1 print.2, src, update.200, libsrc lib2 print.2, src, update.200, libsrc .DT .fi .PP the entire software package can be updated by the command .PP pexec \-Tupdate make update .PP in the order `include', `lib1', `lib2', `cmd1', `cmd2'. .PP Global commands can be made even more precise by using boolean expressions on type labels to select project directories. The formal definition of a boolean type label expression is .LP .ce \fIE\fR \(-> \fIE\fB or \fIE\fR | \fIE\fB and \fIE\fR | \fBnot\fI E\fR | ( E ) | \fBid\fR .LP where .I E is a boolean expression; \fBand\fR, \fBor\fR, and \fBnot\fR are boolean operators; and .B id is a type label. .B Or and .B and are left-associative. .B Or has the lowest precedence, then \fBand\fR, then .B not. In terms of entering the boolean expression on the command line, `\fBor\fR' is represented by the character `|', `\fBand\fR' by the character `&', and `\fBnot\fR' by `!'. Since these characters, together with `(' and `)', are meaningful to the command shell, it is good idea to enclose the whole expression in quotes. However, even if this is done, the `!' character must still be escaped by a backslash `\\' if it precedes a type label to prevent it from being interpreted by the .I csh history mechanism. The command .PP pexec "\-Tprint\|&\|(libsrc\||\|cmdsrc)" \'pr *.h *.c\' | lpr .PP prints the source code in the command and library directories, but not the directory containing header files. Alternatively, .PP pexec "\-Tprint\|&\|\\!include" \'pr *.h *.c\' | lpr .PP achieves the same result. .PP \fBProject Pathnames\fR .PP \fIProject pathnames\fR provide a convenient way for accessing a particular directory or file within a project hierarchy. A project pathname is formed by a succession of project names separated by `^' characters, followed by the name of the directory or file. For instance, to describe a file `main.c' in the project directory `work' in the project `spms', the project pathname is .PP ^spms^work/main.c .PP The project at the top of each user's project hierarchy is called the \fIroot project\fR and is given the special name `^'. If a project pathname begins with the character `^', it is interpreted relative to the root project and is called an \fIabsolute project pathname\fR. However, a project pathname not beginning with `^' is interpreted with respect to the current working project and is therefore called a \fIrelative project pathname\fR. The parent of the working project is called `....' and the alternative name for the current project is `...'. .PP Project pathnames may have a prepended ~\fIusername\fR, and an appended regular pathname. For example, the pathname .PP ~pjn^spms^work/old/main.c .PP represents the path to `main.c' located in the directory `old' in the project `spms' owned by `pjn'. .SH OPTIONS The options to SPMS commands follow certain conventions. Keyword options are uppercase (with the exception of the .B \-f option). The keyword can immediately follow the option, or be separated by an arbitrary amount of space. The following options are uniformly recognized. .IP "\fB\-P \fIpdirname\fR" Specify a project other than the current working project. .IP "\fB\-T \fItypexpr\fR" Only use project directories corresponding to boolean type label expression, .I typexpr. .PP Non-keyword options are lowercase (with the exception of the .B \-D option). The following options are standard. .IP \fB\-q\fR Quiet mode. Do not print titles. .IP \fB\-r\fR Apply the command recursively to subprojects. .IP \fB\-x\fR Trace and print, but do not execute. .IP \fB\-D\fR Print the expanded pathname when a project pathname is converted to a regular pathname. .PP An option specified as {+\^\-}\fIx\fR means +\fIx\fR or \-\fIx\fR. .SH "ENVIRONMENT VARIABLES" .IP PROJECT \w'ROOTPROJECT'u+.5i Absolute pathname of the current working project root directory. This variable is set by .I chproject. .IP ROOTPROJECT Absolute pathname of the root project directory. The default is the user's home directory. .SH FILES .ta \w'ROOTPROJECT'u+.5i \&... Project link directory. .DT .SH "SEE ALSO" mkmf(1), chproject(1P), mkproject(1P), pcp(1P), pd(1P), pdiff(1P), pexec(1P), pfind(1P), pgrep(1P), phelp(1P), plog(1P), pman(1P), pmkdir(1P), pmv(1P), ppd(1P), prmdir(1P), ptest(1P), pwp(1P), rmproject(1P) Peter J. Nicklin \fIThe SPMS Software Project Management System\fR .SH AUTHOR Peter J. Nicklin .SH BUGS At present, project pathnames are only recognized by SPMS commands. .PP Since the Bourne shell, .I sh, recognizes the `^' character as an alternative pipe symbol, Bourne shell users must type `\\^' instead.