+.nr PS 12
+.NH
+Simple Tasks
+.nr PS 10
+.XS
+\*(SN Simple Tasks
+.XE
+.PP
+In this document several examples related to an interactive screen-oriented
+spreadsheet program are presented to demonstrate the use of SPMS for
+software development and project management. It is assumed that the
+reader is familiar with the
+.UX
+operating system and a text editor such as
+.I ex.
+In these examples, user input is shown in \fBbold\fR face.
+.NH 2
+Getting Started
+.XS
+\*(SN Getting Started
+.XE
+.PP
+Before using SPMS for the first time the following steps must be performed\**
+.FS
+For C shell, (\fIcsh\fR), users only. Consult the UNIX Programmer's
+Manual for instructions on how to set up SPMS for the Bourne shell,
+(\fIsh\fR).
+.FE
+.IP 1.
+Include the directory `/usr/new' in the
+command search path. This is done by altering the PATH environment variable
+in one of the startup files, `.cshrc' or `.login', in the home directory.
+.IP 2.
+Add the following aliases to the `.cshrc' file located in the home directory
+.br
+ alias chproject \'eval \`\^"chproject" \\!*\`\^\'
+.br
+ alias pd \'eval \`\^"pd" \\!*\`\^\'
+.IP 3.
+Add the following command to the `.login' file located in the home directory
+.br
+ chproject ^
+.IP 4.
+Convert the home directory to a project root directory by typing
+.br
+ \fB/usr/new/mkproject \-d ^\fR
+.IP 5.
+Execute the `.cshrc' and `.login' files by typing
+.br
+ \fBsource .cshrc\fR
+.br
+ \fBsource .login\fR
+.NH 2
+Building a Project
+.XS
+\*(SN Building a Project
+.XE
+.PP
+The directory structure to support a software package is created by the
+.I mkproject
+and
+.I pmkdir
+commands. These commands create directories using the standard
+.UX
+.I mkdir
+command, and record information about each directory in a project database
+called the
+.I
+project link directory.
+.R
+This information is used by various SPMS commands to control the development
+and maintenance activities for a project.
+.PP
+The steps for building the project structure are:
+.IP 1.
+Initialize the project using the
+.I mkproject
+command.
+.I Mkproject
+creates a directory known as a
+.I
+project root directory,
+.R
+to serve as the focus for a project, and initializes the project database.
+After
+.I mkproject
+creates the project root directory, the user is prompted for a line
+describing the purpose of the project.
+.IP 2.
+Use the \fI\%chproject\fR command to change to the root directory of
+the new project and make it the \fIworking project\fR (see \(sc\|2.13).
+.IP 3.
+Create the project directories using the
+.I pmkdir
+command. After
+.I pmkdir
+creates each directory, the user is prompted for a line describing the
+purpose of the directory.
+.PP
+To illustrate this process, the following commands create project `vs'
+with directories `doc', `src', and `work' (see fig. 2) to support a
+`Visual Spreadsheet' program\** called \fIvs\fR.
+.FS
+\fIVs\fR is a fictitious name bearing no resemblance to any actual program.
+.FE
+.DS
+% \fBmkproject vs\fR
+vs: description? (1 line): \fBVisual Spreadsheet\fR
+% \fBchproject vs\fR
+% \fBpmkdir doc src work\fR
+doc: description? (1 line): \fBvs user's guide\fR
+src: description? (1 line): \fBvs program source code\fR
+work: description? (1 line): \fBvs workbench\fR
+%
+.DE
+.KF
+.sp 11
+.SM
+.ce
+\fIFigure 2. \fRLayout of the project `vs'
+
+.NL
+.KE
+.NH 2
+Displaying a Project
+.XS
+\*(SN Displaying a Project
+.XE
+.PP
+The
+.I ppd
+``\fBp\fRrint \fBp\fRroject \fBd\fRirectory'' command may be used to list
+the directories belonging to `vs':
+.DS
+% \fBppd\fR
+doc src work
+%
+.DE
+Alternatively, a table of contents for the project can be obtained by using
+.I ppd
+with the \fB\-d\fR description option to print the description of each project
+directory.
+.DS
+% \fBppd \-d\fR
+doc vs user's guide
+src vs program source code
+work vs workbench
+%
+.DE
+.NH 2
+Moving Around Inside a Project
+.XS
+\*(SN Moving Around Inside a Project
+.XE
+.PP
+The
+.I pd
+command provides a convenient way for changing to another project directory
+without the user having to remember it's precise location. For example,
+to move to the source code directory `src', type
+.ID
+% \fBpd src\fR
+.DE
+To change to the directory `work', type
+.ID
+% \fBpd work\fR
+.DE
+To return to the project root directory, type
+.ID
+% \fBpd\fR
+.DE
+without any arguments.
+.NH 2
+Compiling a Program
+.XS
+\*(SN Compiling a Program
+.XE
+.PP
+Program development and maintenance is handled by the
+.I make
+command\|[3].
+.I Make
+mechanizes many development and maintenance activities, including
+compiling and linking of programs, printing of source code, and the removal
+of unneeded files. The instructions which tell
+.I make
+how to perform these duties are kept in a special file known as a makefile,
+together with the names of the source code files which make up the
+program. The makefile editor program,
+.I mkmf,
+creates the makefile (named `Makefile' by default) by gathering up
+the names of all the source code files in the current working directory and
+inserting them into a standard makefile.
+.PP
+The following example shows how to produce the program for the visual
+spreadsheet, given the file `vs.c' containing the source code in the directory
+`src'.
+.DS
+% \fBmkmf\fR
+mkmf: creating Makefile from template /usr/new/lib/p.Makefile
+% \fBmake\fR
+cc \-c vs.c
+Loading a.out ... done
+%
+.DE
+In this example the executable program is called `a.out'. However, by using the
+makefile editor interactively the name `vs' could have been specified instead:
+.DS
+% \fBmkmf \-i\fR
+mkmf: creating Makefile from template /usr/new/lib/p.Makefile
+program name? \fBvs\fR
+destination directory?
+% \fBmake\fR
+cc \-c vs.c
+Loading vs ... done
+%
+.DE
+Since a carriage return was typed in response to the second question in
+the example above, the destination directory for the program remains the
+current directory.
+.PP
+Because program
+.I vs
+is a screen-oriented program, it would not be
+surprising if it requires special functions to control cursor movement
+and updating of the terminal screen. There is a standard package of C
+library functions for this purpose called `curses'\|[1], and if the program
+has taken advantage of these functions, this library should be included
+in the makefile together with the terminal database package `termlib'.
+This can be done by including the LIBS macro definition as an argument to the
+.I mkmf
+command\**
+.FS
+Arguments with embedded blanks in UNIX commands must be enclosed by double
+quotes.
+.FE
+.ID
+% \fBmkmf \-i "LIBS=\-lcurses \-ltermlib"\fR
+.DE
+.NH 2
+Moving Files Within a Project
+.XS
+\*(SN Moving Files Within a Project
+.XE
+.PP
+A file can be moved to another project directory by using the
+.I pmv
+command. For instance, the following command moves the executable program
+.I vs
+from the current working directory to the `work' directory
+.ID
+% \fBpmv vs work\fR
+.DE
+In a similar manner, files can be copied from one project directory
+to another using the
+.I pcp
+command.
+.I Pmv
+and
+.I pcp
+behave very similarly to the standard
+.UX
+.I mv
+and
+.I cp
+commands in that they blindly overwrite any existing files of the same
+name in the destination directory unless the
+.B \-i
+interactive option is used.
+.NH 2
+More on Building a Project
+.XS
+\*(SN More on Building a Project
+.XE
+.PP
+As development of a software package continues, extra project directories may
+be needed to support the work. For example, project `vs' must accommodate
+an additional program called
+.I vstutor
+which provides instruction on the use of the visual spreadsheet program;
+two library packages called `hash' and `list' for hash table and linked
+list operations; and three files that are ``included'' in more than one
+source file \- `vs.h' which contains common program definitions,
+`hash.h' which defines hash tables, and `list.h' which holds linked
+list definitions. Figure 3 shows the extra directories needed for
+these components and the following command sequence creates them
+.DS
+% \fBpd\fR
+% \fBpmkdir bin include lib\fR
+bin: description? (1 line): \fBvs and vstutor programs\fR
+include: description? (1 line): \fBcommon included files\fR
+lib: description? (1 line): \fBcompiled hash table and list libraries\fR
+% \fBpd src\fR
+% \fBpmkdir vs vstutor libhash liblist\fR
+vs: description? (1 line): \fBvs program source code\fR
+vstutor: description? (1 line): \fBvstutor program source code\fR
+libhash: description? (1 line): \fBhash table library source code\fR
+liblist: description? (1 line): \fBlist library source code\fR
+%
+.DE
+The final step is to change the description of the `src' directory now
+that it has been subdivided into four separate source code
+directories. This can be done by using the
+.I pmkdir
+with the \fB+d\fR (change \fBd\fRescription) option
+.DS
+% \fBpmkdir +d src\fR
+src: description? (1 line): \fBC source code\fR
+%
+.DE
+.KF
+.sp 17
+.SM
+.ce
+\fIFigure 3. \fRRevised layout of project `vs'
+
+.NL
+.KE
+Note that in Figure 3 there are two directories called `vs'. The top one
+bears the name of the project, and the bottom one is named according to the
+program contained within it. Similarly, the directories `libhash' and
+`liblist' are named according to libraries that they contain.
+.NH 2
+Creating a Program Library
+.XS
+\*(SN Creating a Program Library
+.XE
+.PP
+A program library is a collection of compiled subroutines that are shared
+by more than one program. In the
+.UX
+environment a program library is stored as an
+.I archive
+file. Each member of the archive is an object file containing one or
+more compiled subroutines. By convention a library archive file is named
+\fBlib\fIname\fR.\fBa\fR where
+.I name
+is the name of the program library.
+.PP
+The example below shows how to create a program library for the hash table
+subroutines in the `libhash' directory. Note that the
+.I mkmf
+command must be given with the \fB\-l\fR option so that a makefile will be
+created for a library rather than a program.
+.DS
+% \fBmkmf \-i \-l\fR
+mkmf: creating Makefile from template /usr/new/lib/l.Makefile
+library name? \fBlibhash.a\fR
+destination directory? \fB../../lib\fR
+% \fBmake\fR
+cc \-c hthash.c
+cc \-c htinit.c
+cc \-c htinstall.c
+cc \-c htlookup.c
+cc \-c htrm.c
+Loading libhash.a ... done
+%
+.DE
+Since the `lib' directory is in the same
+project as the `libhash' directory, the path to `lib' is
+made
+.I relative
+to `libhash' so that the project will be portable.
+.PP
+The next step is to install the program library in the `lib' project directory
+where the
+.I vs
+and
+.I vstutor
+programs can access it easily.
+.DS
+% \fBmake install\fR
+Installing libhash.a in ../../lib
+%
+.DE
+.NH 2
+More on Developing a Program
+.XS
+\*(SN More on Developing a Program
+.XE
+.NH 3
+\fIIncluded files\fR
+.XS
+\*(SN Included files
+.XE
+.PP
+Definitions which are common to more than one source code file (e.g. buffer
+sizes, data structure definitions) should be declared only once in a program.
+This can be achieved by keeping such definitions in files separate from the
+main program and ``including'' them at compilation time. In C, Fortran, and
+Pascal programs, the contents of a file can be included by the statement
+.ID
+#include "filename"
+.DE
+By convention
+.I filename
+ends in \fB.h\fR and is commonly referred to as a
+.I header
+file. Hence, in the source code for programs
+.I vs
+and
+.I vstutor,
+the statements
+.DS
+#include "vs.h"
+#include "hash.h"
+#include "list.h"
+.DE
+include common program definitions, hash table definitions, and linked
+list definitions respectively.
+.PP
+Since the header files in this example are used in more than
+one program, they should be placed in the `include' directory where they can
+be accessed easily. Although the include statements can be rewritten as
+.DS
+#include "../../include/vs.h"
+#include "../../include/hash.h"
+#include "../../include/list.h"
+.DE
+it is better to tell the compiler where the header files are by using the
+.B \-I
+compiler option\** as follows
+.FS
+C and Fortran compilers only.
+.FE
+.ID
+\-I../../include
+.DE
+This is done most conveniently by adding the option to the compiler
+flags in the makefile (see \(sc\|4.1.1).
+.NH 3
+\fIProgram libraries\fR
+.XS
+\*(SN Program libraries
+.XE
+.PP
+The LIBS macro definition in a makefile specifies the libraries that
+are to be used by the link editor for resolving references to
+subroutines that are not found in the program source code. Because
+.I make
+checks to see if the libraries needed by a program have changed since
+the last time the program was made, their pathnames must be defined
+explicitly. In the makefiles belonging to programs
+.I vs
+and
+.I vstutor,
+the LIBS macro definition looks like
+.DS
+LIBS = \kx../../lib/libhash.a \\\\
+\h'|\nxu'\&../../lib/liblist.a \\\\
+\h'|\nxu'\&/usr/lib/libcurses.a \\\\
+\h'|\nxu'\&/usr/lib/libtermlib.a
+.DE
+Note also that when this macro definition was added to the makefile by
+the command
+.PP
+% \fBmkmf "LIBS=../../lib/libhash.a ../../lib/liblist.a \-lcurses \-ltermlib"\fR
+.LP
+to include the `hash' and `list' libraries, the `curses' and `termlib'
+libraries were automatically expanded to full pathnames by the makefile editor.
+.NH 3
+\fIInstallation\fR
+.XS
+\*(SN Installation
+.XE
+.PP
+Once a program has been completed, it should be installed in a place
+where it will be generally available \- that is, in a directory which
+is in the command search path specified by the PATH environment
+variable. In the case of the project `vs', if the `bin' directory is in
+the search path, this might be a good place to install the
+.I vs
+and
+.I vstutor
+programs. If the makefiles for these programs do not already specify `bin' as
+their destination directory, it can be added by the command
+.ID
+% \fBmkmf "DEST=../../bin"\fR
+.DE
+Then, each program can be installed by the
+.I
+make install
+.R
+command. For the program \fIvs\fR:
+.DS
+% \fBpd vs\fR
+% \fBmake install\fR
+Installing vs in ../../bin
+%
+.DE
+and for the program \fIvstutor\fR:
+.DS
+% \fBpd vstutor\fR
+% \fBmake install\fR
+Installing vstutor in ../../bin
+%
+.DE
+.NH 2
+Global Operations
+.XS
+\*(SN Global Operations
+.XE
+.PP
+One of the goals of SPMS is to reduce the effort associated with software
+maintenance. This can be achieved by treating a software package as an
+atomic unit \- that is, a single entity on which to perform operations.
+The mechanism for executing a command over an entire software package
+is provided by the
+.I pexec
+command. This command takes another command as an argument and executes it
+in each of the directories belonging to a project, as in
+.ID
+% \fBpexec ls\fR
+.DE
+which lists the names of all the files in a project.
+.NH 3
+\fIDirectory selection\fR
+.XS
+\*(SN Directory selection
+.XE
+.PP
+By labeling each project directory according to the type of activity that it
+supports, global operations can be restricted to specific directories. These
+labels, which are known as
+.I
+type labels,
+.R
+are attached to project directories by the
+.I pmkdir
+command, and removed by the
+.I prmdir
+command\**.
+.FS
+Except in the case of project root directories, where
+.I mkproject
+and
+.I rmproject
+must be used.
+.FE
+For instance, if the directories containing source code in project `vs' are
+labeled `src' by
+.ID
+% \fBpmkdir +T\|src include libhash liblist vs vstutor\fR
+.DE
+then, the total number of lines of source code in a project can be counted by
+giving the command
+.ID
+% \fBpexec \-T\|src \'cat \(**.h \(**.c\^\' | wc \-l\fR
+.DE
+where quotes surround the
+.I cat
+command to prevent file name expansion in the current directory.
+.PP
+If a project directory supports more than one type of activity,
+labels corresponding to each of the activities can be attached to
+the directory.
+.NH 3
+\fIDirectory order\fR
+.XS
+\*(SN Directory order
+.XE
+.PP
+In some instances the directories affected by a global command must be
+processed in a particular order. For example, when installing a software
+package which has both libraries and programs, the libraries should be
+installed first. This ordering is achieved by appending priorities to type
+labels. In the case of the project `vs', if the directories containing the
+program and library source code are labeled `install' with the following
+priorities
+.so install.tbl
+by the commands
+.DS
+% \fBpmkdir +T\|install.1 libhash liblist\fR
+% \fBpmkdir +T\|install.2 vs vstutor\fR
+.DE
+then, the command
+.ID
+% \fBpexec \-T\|install make install\fR
+.DE
+installs the `vs' software package in the order shown in figure 4.
+.KF
+.sp 18
+.SM
+.ce
+\fIFigure 4. \fROrdering for `install' directories
+
+.NL
+.KE
+.KS
+.PP
+In a similar fashion, if the directories containing source code are
+labeled `print' with the following priorities,
+.so print.tbl
+.KE
+a source code listing for the entire project may be obtained by the command
+.ID
+% \fBpexec \-T\|print \'pr \(**.h \(**.c\' | lpr\fR
+.DE
+in the order shown in figure 5.
+.KF
+.sp 18
+.SM
+.ce
+\fIFigure 5. \fROrdering for `print' directories
+
+.NL
+.KE
+.NH 2
+Locating Files in a Project
+.XS
+\*(SN Locating Files in a Project
+.XE
+.PP
+When the location of a file within a project is unknown, it can be
+found by using the
+.I pfind
+command. For example, the command
+.ID
+% \fB pfind Makefile\fR
+.DE
+searches for all occurrences of `Makefile' in project `vs' and produces
+the output
+.ID
+\&...^vs/Makefile
+\&...^vstutor/Makefile
+\&...^libhash/Makefile
+\&...^liblist/Makefile
+.DE
+.PP
+In a large project, the time required to search for a file can be reduced
+by telling
+.I pfind
+to scan only those directories in which there is some likelihood of the
+file being found. In the example above, since makefiles are only likely
+to be found in source code directories (i.e. directories having type
+label `src'), the command could have been given as
+.ID
+% \fBpfind \-T\|src Makefile\fR
+.DE
+.NH 2
+Searching Files for Patterns
+.XS
+\*(SN Searching Files for Patterns
+.XE
+.PP
+Sometimes it is necessary to look at all the files in a software
+package that contain a certain pattern\**.
+.FS
+The term
+.I pattern
+is used to denote a set of strings.
+.FE
+One reason might be to find all of the places from which a subroutine
+is called, perhaps with the intent of altering its arguments. The
+.I pgrep
+command searchs through specified files in a project for lines
+matching a given pattern. For example,
+.ID
+% \fBpgrep \-T\|src listappend \'\(**.h \(**.c\'\fR
+.DE
+will search all the C source code files in project `vs' for the function
+`listappend'. Because of the
+.B \-T
+option,
+.I pgrep
+searchs only in those directories which have the `src' type label.
+.PP
+An alternative way for specifying file names is to use the
+.B \-m
+option. This causes
+.I pgrep
+to fetch the names of source code files from the HDRS and SRCS macro
+definitions in a makefile. Consequently, the command in the example
+above could have been expressed as
+.ID
+% \fBpgrep \-T\|src \-m listappend\fR
+.DE
+.PP
+If the pattern contains characters that have a special meaning to the
+shell, such as \fB\(**\fR or \fB^\fR, the pattern should be quoted.
+For example,
+.ID
+% \fBpgrep \-T\|src \-m \'ht.\(**(\'\fR
+.DE
+finds all of the places where functions from the hash table library
+are used.
+.NH 2
+Changing the Working Project
+.XS
+\*(SN Changing the Working Project
+.XE
+.PP
+Along with a working directory, each user has a
+.I
+working project.
+.R
+Immediately after logging in, the working project is the root project `^'.
+To change to a new working project, the
+.I chproject
+command must be used, as in
+.ID
+% \fBchproject vs\fR
+.DE
+which makes `vs' the current (or working) project. To return to the
+root project, execute the command
+.ID
+% \fBchproject ^\fR
+.DE
+To find out the name of the working project, type
+.ID
+% \fBpwp\fR
+.DE
+
+
projects / unix-history / commitdiff