![[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.