U.S. DEPARTMENT OF COMMERCE National Institute of Standards and Technology National PDES Testbed Report Series A Guide to Configuration Management and file RevWon Control Sj«tem for Testbed Users NATIONAL TESTBED fiC 100 .056 //4646 1991 U.s. DEPARTMENT OF COMMERCE National Institute of Standards and Technology NISTIR 4646 National PDES Testbed Report Series NAnONAL i TPRTRFn A OiliHp to Confiaiirafion Management and the Revision Control System for Testbed Users u.s. DEPARTMENT OF COMMERCE Robert A. Mosbacher, Secretary of Commerce Scott Bodarl^ National Institute of Standards and Technology John W. Lyons, Director August 21, 1991 1. PUBUCATION NiST-i 14A U.S. DEPARTMENT OF COMMERCE OR REPORT NUMBER (REV. 3-90) NATIONAL INSTITUTE OF STANDARDS AND TECHNOLOGY NISTIR 4646 2. PERFORMING ORGANIZATION REPORT NUMBER BIBLIOGRAPHIC DATA SHEET 3. PUBUCATION DATE AUGUST 1991 4. TITLE AND SUBTITLE A Guide to Configuratin Managment and the Revision Control System for the Tested Users S. AUTHOR(S) Scott Bodarky 6. PERFORMING ORGANIZATION (IF JOINT OR OTHER THAN NIST, SEE INSTRUCTIONS) 7. CONTRACT/GRANT NUMBER U.S. DEPARTMENT OF COMMERCE NATIONAL INSTITUTE OF STANDARDS AND TECHNOLOGY GAITHERSBURG, MD 20899 8. TYPE OF REPORT AND PERIOD COVERED 9. SPONSORINQ ORQANiZATION NAME AND COMPLETE ADDRESS (STREET, aTY, STATE, ZIP) Office of the Secretary of Defense CAL^ Program Office Pentagon Washington, DC 20301-8000 10. SUPPLEMENTARY NOTES 11. ABSTRACT (A 20O-WORD OR LESS FACTUAL SUMMARY OF MOST SIGNIFICANT INFORMATION. IF DOCUMENT INCLUDES A SIGNIFICANT BIBUOGRAPHY OR LITERATURE SURVEY, MENTION IT HERE.) Product Data Exchange using STEP (PDES) refers to the United States organizational activities in support of the development of the Standard for the Exchange of Product Model Data (STEP). These activities have resulted in the creation of large amounts of information and software, which reside in the PDES File System on the computer systems at the National Institute of Standards and Technology. The PDES software, documents, and data have been placed under configuration management using the Revision Control System (RCS), in order to ensure that change to these items occurs in a controlled manner, and that any service provided by them are done so as reliably as possible. This document provides instructions for anyone needing to access this material. 12. KEY WORDS (6 TO 12 ENTRIES; ALPHABETICAL ORDER; CAPITALIZE ONLY PROPER NAMES; AND SEPARATE KEY WORDS BY SEMICOLONS) Configuration Management; PDES; PDES Toolkit; Revision Control; Software Configuration; Software Development IX AVAILABILITY 14. NUMBER OF PRINTED PAGES X UNUMITED 24 FOR OFFICIAL DISTRIBUTION. DO NOT RELEASE TO NATIONAL TECHNICAL INFORMATION SERVICE (NTIS). IX PRICE ORDER FROM SUPERINTENDENT OF DOCUMENTS, U.S. GOVERNMENT PRINTING OFFICE, WASHINGTON, DC 20402. AO 3 X ORDER FROM NATIONAL TECHNICAL INFORMATION SERVICE (NTIS), SPRINGFIELD, VA 22161. ELECTRONIC FORM J I \ 5 Contents 1 Introduction 1 2 Document Conventions 1 3 System Configuration 2 3.1 The ~pdes File System 2 3.2 The Generic Configuration Management Set-up 2 3.3 Additional Notes for Software Developers 3 3.4 File Conventions 4 4 RCS Archives 4 4.1 The Administrative Node 5 4.2 The Revision Tree 6 4.3 The General Description 6 4.4 The Deltas 6 4.5 RCS Reserved Keywords 8 5 Checking Out Files From Archives 9 5.1 Checking Out with Read Access Only 9 5.2 Checking Out with Write Access 10 5.3 Checking Out by Revision or Symbolic Name 10 5.4 Checking Out by Date or Time 11 5.5 Checking Out by State 11 6 Checking Files Into RCS 12 6.1 Checking In 12 6.2 Assigning a Revision Number 12 6.3 Assigning a Date 13 6.4 Assigning a Symbolic Name 13 6.5 Assigning a State 13 7 The RCS Command 14 7 . 1 Manipulating Access Lists 14 7.2 Designating the Default Branch 14 7.3 Locking an Archive 14 7.4 Symbolic Names 15 7.5 Updating Archives 1 7.6 Assigning States 15 7.7 Modifying the General Description 15 8 Getting Information About Archives (rlog) 16 9 RCS and other Gnu Software •. 16 9.1 Gnumake 16 9.2 Gnu Emacs 17 10 Glossary 18 11 References 19 Appendix A The Electronic Mailing Lists/Newsgroups 20 111 A Guide to Configuration Management and the Revision Control System for Testbed Users 1 Introduction Product Data Exchange using STEP (PDES) refers to the United States organizational activities in support of the development of the Standard for the Exchange of Product Model Data (STEP). These activities have resulted in the creation of large amounts of information and software, which reside in the PDES File System, a directory hierarchy called ~pdes on the computer system at the National Institute of Standards and Technology. The PDES software, documents, and data have been placed under configuration management [Ressler90] using the Revision Control System (RCS) [Tichy85], in order to ensure that change to these items occurs in a controlled manner, and that any services provided by them are done so as reliably as possible. This document provides instructions for anyone needing to access this material. Enhancements to the RCS-based configuration management system will be documented in updates to this document and via electronic -mail (see Appendix A). A set of configuration management procedures will be published as another document. The RCS-based system is intended to handle a variety of objects, including documents, software, and data. It is assumed that the reader has a basic familiarity with UNIX and an account on the systems at NIST. It is hoped that this system will be minimally encumbering while providing as stable and productive an environment as possible. This system is designed to make life easier for all users, from whom feedback is encouraged. 2 Document Conventions There are sample command formats and code examples scattered throughout this document, all of which observe the following conventions: • That which is to be typed verbatim by the user appears in bold. • That which is to be typed by the user and is variable appears in boldface italics. • Verbatim RCS and Unix system messages appear in Helvetica. • Variable RCS or Unix system messages appear in Helvetica Oblique. • The Unix system prompt is the percent sign (%, in Helvetica), which wUl precede aU Unix commands to be typed by the user, but is itself not to be typed. • Items enclosed in square brackets G are optional. Note: Certain commercial products are identified in this paper in order to adequately specify configuration management procedures at NIST. This does not, however, imply recommendation or endorsement by NIST, nor does it imply that said products are necessarily the best available for their purpose. The work described in this document was funded by the U.S. Government’s Department of Defense Computer-aided Acquisition and Logistic Support (CALS) program and is not subject to copyright. 1 A Guide to Configuration Management and the Revision Control System for Testbed Users 3 System Configuration This section provides an overview of the configuration management environment and detailed instructions on setting up a local environment, for users needing to access items in '•pdes that are under configuration management. 3.1 The ^pdes File System The principal repository for items under configuration management at the Testbed is a directory hierarchy called ~pdes. This hierarchy contains various entities used in support of the STEP development effort, including software tools, STEP test data, documents, and various other types of objects. The exact configuration of ~pdes and its contents tends to change periodically; these changes will be reflected by updates to this document and by electronic mail distribution (see Appendix A). The following is a list of those sub-directories in -pdes that are under configuration management by RCS. Each sub-directory may contain other sub-directories, which may themselves contain sub-directories, and so forth. ~pdes/data contains step Testing data ~pdes/distribute contains packaged software releases ~pdes/docs contains documents ~pdes/generic .env contains the Testbed generic environment -'pdes/include contains header files for software tools ~pdes/man contains the on-line man pages for software tools ~pdes/src contains the source code for software tools '-pdes/bin contains various executables ~pdes/arch/bin contains architecture-specific executables All manually generated files (i.e., those not output by some program) in these directories are managed by RCS, as are some binary executables. Each directory contains the current, officially-released version of each of its files. Each of these files should be read-only, and should not be modified directiy. Each directory also contains a sub-directory called RCS, which contains an RCS archive for each controlled file. A user who wishes to modify a file must establish a symbolic link between his own account and the RCS directory, and then check out (into his account) a writable copy of the file from the appropriate archive. Instructions for doing this constitute the remainder of this section. 3.2 The Generic Configuration Management Set-up A user’s home directory must contain a sub-directory named pdes (~/pdes) that is stmctured like ~pdes. If the user wishes to access a particular file stored in the -'pdes hierarchy, his own pdes hierarchy must contain copies of all the intermediate nodes. The user’s copy of the file 2 A Guide to Configuration Management and the Revision Control System for Testbed Users will have the same relative path as the copy in ~pdes, differing only by the inclusion/exclusion of the slash between the tilde and the pdes. Once the relevant portion of the pdes hierarchy has been duplicated, the user must establish a symbolic link from his copy of the file’s source directory to the RCS sub-directory in the ~pdes source directory.