![[BACK]](/cvsweb/icons/back.gif){kind=icon}
Return to 3.advanced.ms CVS log ![[TXT]](/cvsweb/icons/text.gif){kind=icon}
![[DIR]](/cvsweb/icons/dir.gif){kind=icon}
Up to [CSRG BSD Unix] / 43BSD / contrib / spms / doc|
Return to 3.advanced.ms CVS log | Up to [CSRG BSD Unix] / 43BSD / contrib / spms / doc |
1.1 root 1: .nr PS 12
2: .NH
3: Advanced Use
4: .nr PS 10
5: .XS
6: \*(SN Advanced Use
7: .XE
8: .PP
9: This section summarizes the rest of the facilities offered by SPMS
10: for handling large software projects. Techniques for searching and
11: editing text files, program testing, and documentation are explained.
12: .NH 2
13: Project Hierarchies
14: .XS
15: \*(SN Project Hierarchies
16: .XE
17: .PP
18: To facilitate the management of large projects, such projects can be
19: subdivided into smaller projects. These subprojects can be nested
20: to any level to form a project hierarchy which is very similar to the
21: .UX
22: directory hierarchy. For example, as project `vs' grows, it might be
23: convenient to convert each of the `hash' and `list' program libraries
24: into subprojects (see fig. 6).
25: .KF
26: .sp 22
27: .SM
28: .ce
29: \fIFigure 6. \fRProject `vs' with subprojects
30:
31: .NL
32: .KE
33: To show how this conversion is done, the following set of
34: commands converts project directory `libhash' into a subproject.
35: .ID
36: \fIConvert the project directory into a subproject\fR . . .
37:
38: % \fBpd src\fR
39: % \fBprmdir \-u libhash\fR
40: % \fBmkproject libhash\fR
41: libhash: description? (1 line): \fBVS Hash Table Operations\fR
42:
43: \&. . . \fIcreate the project directories\fR . . .
44:
45: % \fBchproject libhash\fR
46: % \fBpmkdir src test work\fR
47: src: description? (1 line): \fBhash table library source code\fR
48: test: description? (1 line): \fBhash table library test programs\fR
49: work: description? (1 line): \fBhash table library workbench\fR
50:
51: \&. . . \fIreattach the type labels\fR . . .
52:
53: % \fBpmkdir +T\|libsrc,install.1,print.3 src
54:
55: \&. . . \fIand rearrange the library\fR
56:
57: % \fBpmv Makefile \(**.c \(**.o src\fR
58: % \fBpd src\fR
59: % \fBmkmf DEST=../../../lib\fR
60: .DE
61: .NH 3
62: \fIThe \fBroot\fI project\fR
63: .XS
64: \*(SN The root project
65: .XE
66: .PP
67: The project at the top of each user's project hierarchy is called the
68: .I
69: root project
70: .R
71: and is given the special name `^'. When the SPMS system was initially
72: set up (see \(sc2.1), the command
73: .ID
74: % \fBmkproject \-d ^\fR
75: .DE
76: created the root project and made the user's home directory into the project
77: root directory for `^'.
78: .NH 3
79: Project Pathnames
80: .XS
81: \*(SN Project Pathnames
82: .XE
83: .PP
84: .I
85: Project pathnames
86: .R
87: provide a convenient way for accessing a particular directory or file
88: within a project hierarchy\**.
89: .FS
90: Project pathnames are recognized only by SPMS commands.
91: .FE
92: A project pathname is formed
93: by a succession of project names separated by `^' characters\**,
94: .FS
95: Since the Bourne shell, (\fIsh\fR), recognizes the `^' character as
96: an alternative pipe symbol, Bourne shell users must type `\\\\^' instead.
97: .FE
98: followed by the name of the directory or file. For instance, the pathname
99: .ID
100: ^vs^libhash^src
101: .DE
102: represents the path from the root project to the `src' directory
103: located in subproject `libhash', and the pathname
104: .ID
105: ^vs^libhash^src/hthash.c
106: .DE
107: locates the file `hthash.c' in that directory.
108: .PP
109: A project pathname can be
110: .I absolute
111: or
112: .I relative.
113: An
114: .I
115: absolute project pathname
116: .R
117: specifies the path from the root project and begins with the
118: character `^'. However, a project pathname not beginning with
119: `^' is interpreted with respect to the current working project and is
120: therefore called a
121: .I
122: relative project pathname.
123: .R
124: For example, the pathname
125: .ID
126: libhash^src
127: .DE
128: specifies the location of `src' relative to project `vs', assuming
129: that `vs' is the working project.
130: .PP
131: Since relative project pathnames are interpreted relative to the
132: current working
133: .B project
134: rather than the current working directory, this means that project directories
135: and files can be accessed from
136: .B any
137: working directory. For example, the command
138: .ID
139: % \fBpmv src/libhash.a work\fR
140: .DE
141: moves the hash table library from the `src' directory in the working project
142: `libhash' to the `work' directory in the same project, regardless of
143: the location of the current working directory.
144: .PP
145: The parent of the working project is called `....' and may be used
146: in a project pathname to go up one level in a project hierarchy. Thus,
147: the command
148: .ID
149: % \fBchproject ....\fR
150: .DE
151: makes the parent project of the current project into the new working project.
152: If the current project happens to be `libhash', then the command
153: .ID
154: % \fBchproject ....^liblist\fR
155: .DE
156: will change to project `liblist'. For completeness, `...' is an
157: alternative name for the current working project. Table 1 summarizes
158: the conventions used in project pathnames together with the equivalent
159: conventions for regular pathnames.
160: .KF
161:
162: .SM
163: .ce
164: \fITable 1.\fR Pathname conventions
165: .NL
166:
167: .so pathname.tbl
168: .KE
169: .PP
170: Project pathnames can be modified in two ways. The first way allows
171: a user to refer to a project belonging to someone else by prepending
172: ~\fIuser\fR to the pathname. For example, if `root' has a copy of the project
173: `vs', the command
174: .ID
175: % \fBppd ~root^vs\fR
176: .DE
177: will print the directories in that project. The other way allows a
178: regular pathname to follow a project pathname, separated by a `/'
179: character. This enables access to directories which are not part of
180: a project. To illustrate, if `junk' is a regular directory in the
181: `work' directory of the project `vs', the command
182: .ID
183: % \fBpd ^vs^work/junk\fR
184: .DE
185: changes to that directory.
186: .NH 2
187: Project Environment
188: .XS
189: \*(SN Project Environment
190: .XE
191: .PP
192: It is possible to tailor the environment for the current project by
193: adding commands to the `.projectrc' startup file located in the root
194: directory of the project. When the project is activated by the
195: .I chproject
196: command, this file is executed. For instance, if a user wishes to be
197: reminded of tasks that still need attention on a project, a reminder
198: service can be set up by putting the reminders in a file, (e.g.
199: `.reminder') and adding the line
200: .ID
201: cat .reminder
202: .DE
203: to the `.projectrc' file.
204: .PP
205: It is also a good idea to include the
206: .B \-d
207: option in the alias for the
208: .I chproject
209: command (see \(sc\|2.1) so that when
210: .I chproject
211: is invoked, it will print the name of the new working project, as in
212: .DS
213: % \fBchproject ^vs\fR
214: Visual Spreadsheet
215: %
216: .DE
217: .NH 2
218: Global Operations
219: .XS
220: \*(SN Global Operations
221: .XE
222: .PP
223: Even if a project is divided into subprojects, commands can
224: still be executed globally over the entire software package by the
225: .I pexec
226: command.
227: .I Pexec
228: has two modes of execution, depending on the method chosen for selecting
229: directories. If type labels are not used for selecting a particular
230: set of directories,
231: .I pexec
232: descends recursively through the project hierarchy and executes
233: the command argument in the project directories at each level. The
234: command
235: .ID
236: % \fBpexec ls\fR
237: .DE
238: demonstrates this mode of operation by listing the contents of the
239: directories in the project `vs' in the order shown in figure 7.
240: .KF
241: .sp 26
242: .SM
243: .ce
244: \fIFigure 7. \fRDirectory ordering for `pexec ls'
245:
246: .NL
247: .KE
248: .PP
249: The other mode of operation, involving the use of type labels, causes
250: .I pexec
251: to search the project hierarchy for directories with appropriate type
252: labels, sort the directories according to their priorities, and then
253: execute the command argument in each directory. As an example of this
254: mode of execution, figure 8 indicates the order in which the command
255: .ID
256: % \fBpexec \-T\|print \'pr \(**.h \(**.c\' | lpr\fR
257: .DE
258: prints the project `vs'.
259: .KF
260: .sp 24
261: .SM
262: .ce
263: \fIFigure 8. \fRDirectory ordering for `pexec \-T\|print ...'
264:
265: .NL
266: .KE
267: .PP
268: With both modes of operation,
269: .I pexec
270: resets the current working project to the project in which the directory
271: resides. For each of the `src' directories in project `vs' the
272: corresponding working projects are
273: .so cwp.tbl
274: .NH 3
275: \fIBoolean type label expressions\fR
276: .XS
277: \*(SN Boolean type label expressions
278: .XE
279: .PP
280: Global commands can be made even more precise by using boolean expressions\**
281: .FS
282: The formal definition of a boolean type label expression is
283: .CD
284: \fIE\fR \(-> \fIE\fB or \fIE\fR | \fIE\fB and \fIE\fR | \fBnot\fI E\fR | ( E ) | \fBid\fR
285: .DE
286: where
287: .I E
288: is a boolean expression; \fBand\fR, \fBor\fR, and \fBnot\fR are
289: boolean operators; and
290: .B id
291: is a type label. As is customary, it is assumed that
292: .B or
293: and
294: .B and
295: are left-associative, and that
296: .B or
297: has the lowest precedence, then \fBand\fR, then
298: .B not.
299: .FE
300: on type labels to select project directories. To show how boolean
301: expressions are used, let the source code directories in project `vs'
302: have the type labels shown below.
303: .KS
304: .so src.tbl
305: .KE
306: .LP
307: In terms of entering the boolean expression on the command line, `\fBor\fR'
308: is represented by the character `|', `\fBand\fR' by the character `&', and
309: `\fBnot\fR' by `!'. Since these characters, together with `(' and `)',
310: are meaningful
311: to the command shell, it is good idea to enclose the whole expression
312: in quotes\**.
313: .FS
314: Even if this is done, the `!' character must still be escaped by a
315: backslash `\\\\' if it precedes a type label to prevent it from being
316: interpreted by the
317: .I csh
318: history mechanism.
319: .FE
320: Then, the command
321: .ID
322: % \fBpexec "\-T\|print\|&\|(libsrc\||\|cmdsrc)" \'pr \(**.h \(**.c\' | lpr\fR
323: .DE
324: prints the source code in both the program and library source code directories,
325: but not the directory containing header files. Alternatively,
326: .ID
327: % \fBpexec "\-T\|print\|&\|\\!include" \'pr \(**.h \(**.c\' | lpr\fR
328: .DE
329: achieves the same result.
330: .NH 3
331: \fISearching and editing\fR
332: .XS
333: \*(SN Searching and editing
334: .XE
335: .PP
336: Whenever it becomes necessary to alter something like the number of arguments
337: in a call to a function, the
338: .I pgrep
339: command can be used to bring up the text editor on all the files in the software
340: package that contain that function call. Suppose, for example, that the
341: number of arguments to the
342: .UX
343: system call `open' for opening files has changed. The command
344: .ID
345: % \fBpgrep \-C\|vi \-T\|src \-m \'open(\'\fR
346: .DE
347: will edit all the source code files containing that call, using the
348: .I vi
349: text editor.
350: .NH 2
351: Testing
352: .XS
353: \*(SN Testing
354: .XE
355: .PP
356: After a program is released for general use, it will require
357: maintenance. It may have to be modified to speed it up, fix bugs, or add
358: new features. Each time the program is altered, the parts that are
359: affected should be checked against previous test results by doing
360: .I regression
361: testing. The
362: .I ptest
363: program mechanizes this process.
364: .PP
365: .I Ptest
366: tests each function by running a test program and comparing the output
367: with previously prepared results. For example, the test for the `htinstall'
368: function in the hash table library produces
369: .DS
370: % \fBptest htinstall\fR
371: htinstall: extracting archive ... compiling test ... executing test ... done
372: %
373: .DE
374: if the test succeeds. However, if the test fails,
375: .I ptest
376: reports this fact by
377: .ID
378: htinstall: extracting archive ... compiling test ... executing test ... failed
379: .DE
380: and saves the error diagnostics in a file named `Ehtinstall'.
381: .PP
382: The test program and data files for each test case are stored in an archive file
383: named \fItest\fR.a where
384: .I test
385: is the name of the test case, located in the `test' directory. In the
386: case of `htinstall', the test archive is called `htinstall.a' and contains
387: the test program source file, Thtinstall.c, the input data file, Ihtinstall,
388: and the validated output data file, Ohtinstall. The details on how to set
389: up a test archive are explained more fully in section ptest(1P) of the
390: .UX
391: programmer's manual.
392: .NH 2
393: Documentation
394: .XS
395: \*(SN Documentation
396: .XE
397: .NH 3
398: \fIThe project log\fR
399: .XS
400: \*(SN The project log
401: .XE
402: .PP
403: The
404: .I plog
405: project log command provides an electronic notebook system by which to record
406: transactions such as incoming and outgoing mail, progress reports,
407: minutes of project staff meetings, etc.
408: .I Plog
409: records messages in a file called `projectlog' located in the project root
410: directory, by invoking the
411: .UX
412: .I Mail
413: program\|[9]. After the
414: .I Mail
415: program starts up, the user types in the message, followed by a period `.'
416: or CNTL-D at the beginning of a line. Since the
417: .I Mail
418: program processes the message, the user can take advantage of all the mailing
419: facilities offered by the system. For instance, the following announcement
420: on the `vs' project can be mailed to a group of users labeled `vsusers'\**
421: .FS
422: By the
423: .I alias
424: mechanism of
425: .I Mail.
426: .FE
427: using the `~c' `carbon copy' facility of the
428: .I Mail
429: program:
430: .DS
431: % \fBplog\fR
432: Subject: \fB`vs' release 2
433: ~c vsusers
434: Release 2 of the `vs' visual spreadsheet package is now available for
435: distribution. It has the following features:\fR
436: .
437: .
438: .
439: %
440: .DE
441: .PP
442: .I Plog
443: can be used to produce reports by printing sections of the project log
444: with subject headings. For example, if the above announcement is message 20
445: in the project log for the `vs' project, the following command will print
446: message 20 plus any subsequent messages.
447: .ID
448: % \fBplog \-p20\fR
449: \l'\n(.lu-\n(.iu\&-'
450: .ce
451: `vs' release 2
452: \l'\n(.lu-\n(.iu\&-'
453: From pjn Wed Aug 10 11:02:44 1983
454: To: /usr/pjn/vs/projectlog
455: Subject: `vs' release 2
456: Cc: vsusers
457:
458: Release 2 of the `vs' visual spreadsheet package is now available for
459: distribution. It has the following features:
460: .
461: .
462: .
463: %
464: .DE
465: .PP
466: .I Plog
467: can also be used to collect incoming mail, edit the project log, and
468: sort it into chronological order. These options are explained
469: more fully in section plog(1P) of the
470: .UX
471: programmer's manual.
472: .NH 3
473: \fIReference manual\fR
474: .XS
475: \*(SN Reference manual
476: .XE
477: .PP
478: The
479: .I pman
480: command supports a project reference manual in the same
481: way that the
482: .I man
483: command provides information from the
484: .UX
485: programmer's manual. For example, to print information about the `vs'
486: visual spreadsheet program, type
487: .ID
488: % \fBpman vs\fR
489: .DE
490: and to find out about the `vstutor' program, type
491: .ID
492: % \fBpman vstutor\fR
493: .DE
494: .PP
495: The directories that contain the manual entries must
496: be set up in the same way as the programmer's manual as shown in figure 9.
497: .KF
498: .sp 18
499: .SM
500: .ce
501: \fIFigure 9. \fRLayout of the `vs' project manual
502:
503: .NL
504: .KE
505: By convention, manual pages for commands have `.1' suffixes and are
506: kept in the `man1' directory, manual pages for libraries have `.3'
507: suffixes and are kept in `man3', and file formats have `.5' suffixes
508: and are kept in `man5'. The
509: .I pman
510: command searchs through each of the `man1', `man3', and `man5'
511: directories in turn until it finds the topic.
512: .NH 3
513: \fIOn-line help\fR
514: .XS
515: \*(SN On-line help
516: .XE
517: .PP
518: On-line help for a project is provided by the
519: .I phelp
520: command. After
521: .I phelp
522: is typed, it prints some introductory information, a list of available
523: topics, and then the prompt `???', indicating that it is ready for a
524: command. The following commands are recognized
525: .DS C
526: .so help.tbl
527: .DE
528: If a topic name is typed in reply,
529: .I phelp
530: will print a page of information and then wait until a space is typed before
531: it continues.
532: .PP
533: In project `vs' there are three topics available \-
534: `install' explains how to install `vs'; `progress' lists recent developments;
535: and `schedule' outlines the development plan. In the following session,
536: .I phelp
537: is used to examine some of these topics.
538: .ID
539: % \fBphelp\fR
540: (\fIprints an introduction to phelp\fR)
541:
542: Help topics available: install progress schedule
543:
544: ??? \fBschedule\fR
545: (\fIprints `schedule' topic\fR)
546: ??? \fBprogress\fR
547: (\fIprints `progress' and goes down one level to `progress' subtopics\fR)
548:
549: progress subtopics: bugfixes
550:
551: progress-->??? \fBbugfixes\fR
552: (\fIprints `bugfixes' topic\fR)
553: progress-->??? \fBq\fR
554: (\fIexits from phelp\fR)
555: %
556: .DE
557: .PP
558: Help topics are contained in files which reside in the `help' directory
559: located in the project root directory. Figure 10 shows how these
560: topics are set up for project `vs'.
561: .KF
562: .sp 20
563: .SM
564: .ce
565: \fIFigure 10. \fRHelp topics for project `vs'
566:
567: .NL
568: .KE
569: The circles represent topic files, and the rectangles represent
570: directories. Subtopics are contained in subdirectories named according
571: to the topics they represent, but with a `.d' suffix. Consequently,
572: `bugfixes' is in the subdirectory `progress.d' since it is a subtopic of
573: `progress'.
574:
575:
This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.