Programmer 7500

home *** CD-ROM | disk | FTP | other *** search

/ Programmer 7500 / MAX_PROGRAMMERS.iso / CLIPPER / MISC / PSCM13.ZIP / PSCM.MAN < prev next >

Wrap

Text File | 1992-07-31 | 60.7 KB | 1,356 lines

====================================================== Project Source Code Manager Version 1.3 July 31, 1992 --------------------------- Copyright (c) 1990-1992 J. Bart Henthorn All Rights Reserved ====================================================== The programs described in this documentation are the copyrighted works of J. Bart Henthorn. They are expressly distributed under the ShareWare concept. They are not free. You must license them if you use them beyond the initial trial period. PSCM -- The Project Source Code Manager July 31st, 1992 Introduction to PSCM.............................................1 Installing PSCM..................................................2 The PSCM Configuration File......................................2 The Project Source Files.........................................3 The Project Database File........................................3 The Item File System.............................................4 The CHECKIN Program..............................................5 Adding New Files to a Project Database......................5 Updating Files in the Project Database......................5 Adding Comments to the Project Database File................6 Entering Comments...........................................6 Saving a Set of Files in the Database.......................7 Viewing Differences in the Source Files.....................8 Undoing A Previous CHECKIN..................................8 Special Macros in Source Files...................................10 The Revision Comments Macro.................................11 The CHECKOUT Program.............................................12 Retrieving for Editing or Making............................12 Listing the Files in the Project Database...................13 Listing Comments in the Project Database....................13 Listing or Retrieving File Sets.............................14 Using PSCM with Make Programs....................................15 Step 1: Pre- and Post-Processing...........................15 Step 2: Templates..........................................16 Enhancements................................................16 PSCM is ShareWare................................................18 Revision History.................................................19 Bugs Fixed and Enhancements Added to Version 1.3............20 Table of Contents PSCM v1.3 PSCM -- The Project Source Code Manager July 31st, 1992 PSCM - Project Source Code Manager PSCM - Project Source Code Manager __________________________________ __________________________________ PSCM consists of two main programs: CHECKIN and CHECKOUT. These two programs control a project database that contains the complete source code and support files for a project. The basic function of PSCM is to maintain and archive various versions of the project source code as it evolves. At any point in time it should be possible to retrieve the full set of files needed to create the project at any point in time. PSCM manages the different revisions by assigning a Version Number to each different version of the files. This number has three parts as follows: M.N.R where: M The major version number. This number may range from 0 to 32767. N The minor version number. This number may range from 0 to 32767. R The revision number. This number may range from 0 to 32767 and is used to indicate intermediate revisions between releases. When a project's files are identified by only the major and minor version numbers, this is referred to as a "Version." When the revision number is included, this is called an "Instance." When a set of files is retrieved for a particular Version, the most recent Instance of all files is retrieved. It is also possible to retrieve a specific revision of a file. The database maintains an internal directory of files that constitute a project set. This directory contains a list of all source code files as well as any comments or set descriptions that have been entered. Once an item has been added to a project database it is not possible to remove it (with one exception described later). It is for this reason that you should be sure about your actions when you add an item to a database. PSCM stores only the latest instance of a file in the database. Prior instances are stored as "Difference Scripts." These scripts are generated and used by the three PSCM support programs: DIFS, MRGS, and SHOWDIFS. DIFS compares two files and produces a script file that describes how they differ. MRGS uses a script file and the later version source file to produce the earlier version source file. SHOWDIFS uses a script file and the later version source file to display the differences between the later and earlier versions. PSCM also allows the inclusion of comments in the database file. When one or more files have been changed, and new Instances of the files are added to the database, an optional comment may be saved. Along with the comment is a list of the files modified and their revision level and file date and time. These comments PSCM v1.3 page 1 PSCM -- The Project Source Code Manager July 31st, 1992 may be either listed one at a time or all comments at once. The same comment is entered for all files updated during that run. This saves you from having to reenter the same information over and over again. It is also possible to feed the comment from an ASCII file by using the redirection features of DOS. During development it may be desirable to take a "Snapshot" of the current revision level of all files in the database. PSCM allows this function through the use of "Sets." When a Set is created a record is made of all source files at their most recent Instance. This is stored along with a comment which can be used to describe the Set. At any point in time it is possible to recreate the exact state of these files using the CHECKOUT program's Set command. It is also possible to generate a list of all Sets in the database. PSCM also supports a limited "Undo" function. Since we humans do occasionally make mistakes, PSCM saves information about the items changed during an update. This information is only one level deep; you can only undo the most recent update to the project database. The undo is a one-way undo. This means that you cannot undo an undone database. Once you undo a database the necessary information is removed. Installing PSCM Installing PSCM _______________ _______________ PSCM version 1.3 contains six program files (CHECKIN.EXE, CHECKOUT.EXE, DIFS.EXE, MRGS.EXE, SHOWDIFS.EXE, and ISIZE.EXE). These files should be placed in a directory along your PATH. This will make them accessible from anywhere on your system. There is also a standard configuration file named PSCM.CFG. This file is a normal ASCII text file (see description below). You should edit this file to suit your system and then put it in the same directory with the CHECKOUT.EXE program file. The PSCM Configuration File The PSCM Configuration File ___________________________ ___________________________ PSCM uses a configuration file to store some basic information used when expanding some of the special macro strings described later. The configuration file is an eight line text file. The first line in the file is called the "System" line. The text of the first line is used when expanding the System Name macro. The remaining seven lines are called "User Parameters." They are used when expanding the seven User macros. Each of the lines in the configuration file is limited to a maximum of 63 characters. PSCM will truncate an entry at the 63rd character when using it to expand a macro. When the CHECKOUT program begins execution, it attempts to open the configuration file "PSCM.CFG" in the current directory. If it cannot find the file in the current directory, and you are using DOS version 3.0 or later, it will attempt to load the configuration file from the directory where the CHECKOUT program was loaded. This allows you to have a default configuration page 2 PSCM v1.3 PSCM -- The Project Source Code Manager July 31st, 1992 stored in the same directory as the CHECKOUT.EXE file and to have a project specific configuration in the working directory. For example, suppose you keep a stock configuration file in the directory where you keep your program files. This file has User Parameter #1 set to your standard copyright message. If you wanted to change the copyright message for a special project you could simply copy the stock PSCM.CFG file to the same directory with your source files and then edit User Parameter #1. The Project Source Files The Project Source Files ________________________ ________________________ A Project's source files are plain ASCII text files that contain the source code for a project. The source files may also include the various support files used to create and maintain the project such as a make file and batch files. For example, the PSCM project has several 'C' code source files, a couple of 'C' header files, a make file and a few batch files. Taken together, these files are all that is necessary to recreate the entire project from scratch. ----------------------------------------------------------------- NOTE PSCM can only work with plain ASCII text files. It NOTE will not handle word processor files properly. The various control codes in most word processor files will corrupt the PSCM database file. ----------------------------------------------------------------- The Project Database File The Project Database File _________________________ _________________________ The Project Database file is used to hold all information about the project's source files. There is no requirement on the name of the file, however the convention is to name it the same as the project with no extension. For example, my project file for PSCM is named "PSCM". The project database file need not even be in the same directory as the rest of the project files. This allows you to place the project file on another drive or in another directory for that added "Peace of Mind." PSCM v1.3 page 3 PSCM -- The Project Source Code Manager July 31st, 1992 The Item File System (IFS) The Item File System (IFS) __________________________ __________________________ PSCM project files use a database manager called the "Item File System." This DBMS allows records in the database to be of varying lengths. It is also very fast because it uses a hashing algorithm to store the records. When a project file is first created (by the CHECKIN program) it is given a default size (called a "Modulo") of 47. As the project database file grows it may be necessary to resize the file to improve retrieval speed. The ISIZE program is used to resize the project database file. Use the following command: ISIZE -r PROJECT The ISIZE program will inspect the project database file and then create a new file with a new size and copy all items from the old file to the new file. It will then delete the old file and rename the new file to the old file name. ----------------------------------------------------------------- NOTE The old file will only be deleted if the new file is NOTE created correctly. If the ISIZE program encounters any errors the old file will be left intact. ----------------------------------------------------------------- page 4 PSCM v1.3 PSCM -- The Project Source Code Manager July 31st, 1992 The CHECKIN Program The CHECKIN Program ___________________ ___________________ The CHECKIN program is used to add project files to the database and to create new Versions or Instances of files. CHECKIN is also used to add comments to the database, to create project Sets, and to undo a previous CHECKIN command. ----------------------------------------------------------------- NOTE None of the CHECKIN command forms discussed will alter NOTE the source files. They are left on disk exactly as before CHECKIN was run. ----------------------------------------------------------------- Adding New Files to a Project Database Adding New Files to a Project Database When adding one or more new files to the project database, or when creating a new Version level, the Version numbers must be specified via a command line switch as follows: CHECKIN -vM.N PROJECT FILE1 FILE2 ... FILEn The '-v' switch is used to specify the major and minor version numbers. As with most CHECKIN commands you can use wildcards to specify the files. However, you cannot specify files that are not in the current directory; all files specified must be in the current directory. Note that the revision number is not specified, it is set to 0 by the program. If a copy of the file already exists at the specified Version level, a warning message will be displayed and the file will be skipped. This feature is particularly handy when adding new files to an existing project database. For example, assume you have created three new source files, two with the extension ".C" and one with the extension ".H". You can easily add these to the project database by using wildcards to specify all .C and .H files (e.g. "*.C *.H"). Only the new files will be added to the database; any files already existing in the project database will be skipped. Updating Files in the Project Database Updating Files in the Project Database To create a new Instance of an existing file, the following command line is used: CHECKIN -i PROJECT FILE1 FILE2 ... FILEn -or- CHECKIN -i PROJECT -or- CHECKIN -iM.N PROJECT FILE1 FILE2 ... FILEn -or- CHECKIN -iM.N PROJECT PSCM v1.3 page 5 PSCM -- The Project Source Code Manager July 31st, 1992 When no file names are specified on the CHECKIN command line, all source files that have been modified since they were last checked in are updated. This is a shorthand way of updating all modified files. You can also use wildcards to specify the files that will be updated. The first command form is used to create new Instances for the specified files at the most recent Version level. The second command is the same except that all modified files in the most recent Version are updated to a new Instance. These two forms are the most common used in project management. The third and fourth commands are similar to the first two except a specific Version level is updated instead of the most recent. These two command forms are used when a previous CHECKOUT was run to retrieve a Version other than the most recent. Adding Comments to the Project Database File Adding Comments to the Project Database File The '-i' switch discussed above is used to create new Instances of source files. But it is also possible to add a comment record at the same time. The following commands behave the same except that they also allow an optional comment record to be created and saved with the files. The comment record contains one or more lines of text and a list of the files updated. The following command forms are used to create comment records: CHECKIN -c PROJECT FILE1 FILE2 ... FILEn -or- CHECKIN -c PROJECT -or- CHECKIN -cM.N PROJECT FILE1 FILE2 ... FILEn -or- CHECKIN -cM.N PROJECT The same comment is saved with every file updated. This allows you to easily apply the same comments to every file modified since the last update. If you need to save a specific comment with a small subset of files you should run CHECKIN and specify those files that will receive the different comment. You can then use the second command form shown above to pick up the remaining files and give them a global comment. If you do not specify a comment (by entering Control+Z "^Z" without any text) then no comment will be saved with the files but they will still be updated in the project database. This allows you to always use the "-c" switch to update files and only enter comments when you truly need to comment on the update. Entering Comments Entering Comments CHECKIN reads comments, one line at a time, from STDIN. You can edit the current line only; once you press <Enter> at the end of the line you cannot edit that line any more. When you are done page 6 PSCM v1.3 PSCM -- The Project Source Code Manager July 31st, 1992 entering the comment, enter a Control+Z "^Z", either using the <Ctrl>+<Z> keys or by pressing the <F6> function key, and then press <Enter>. This ends the current comment. Note that there is no limit to the number of lines in a comment, but there is a limit to the width of a comment line. No comment line should extend past column 80, but you may find that output formatting is easier if you limit comment lines to something less than this. Because CHECKIN can read the comments from an ASCII file using redirection, you may find it easier to enter your comments into a text file and then redirect them into CHECKIN from the command line. For example, assume that you have saved all your comments in a text file called "COMMENTS". You can update the project database and save the contents of the COMMENTS file as the update comment using the following command: CHECKIN -c PROJECT < COMMENTS ----------------------------------------------------------------- NOTE It is generally NOT a good idea to enter source file NOTE comment symbols in a revision comment. In some languages, most notably 'C', the comment symbols in the expanded comment macro could cause compilation errors. ----------------------------------------------------------------- Saving a Set of Files in the Database Saving a Set of Files in the Database During the development process it may be useful to save a record of the current revision level of all files in the database. This record is called a "Set." It is commonly used as a place marker to indicate where specific versions of the project were generated and released. For example, if you are in the habit of releasing preliminary versions to a small group of testers, the Set function can be used to regenerate the source code used for each tester's version of the program. This allows you to forge ahead making fixes and enhancements to the project, yet still pull the "release" version to check on specific bug reports. The command used to generate a Set is: CHECKIN -s PROJECT -or- CHECKIN -sM.N PROJECT Note that no file names are specified on the command line. This is because the Set command generates and saves a list of all files in the database. The first command form will generate a set for the most recent Version, while the second form is used to create a set for a specified version. Note that you must also enter a "Set Comment." If you do not enter a comment (or enter a blank comment) then the set will not be created. PSCM v1.3 page 7 PSCM -- The Project Source Code Manager July 31st, 1992 Viewing Differences in the Source Files Viewing Differences in the Source Files After making changes in the source files, and before checking them into the project database, you can view the changes you have made. The "-d" command switch is used to compare the current versions of the source files on disk with the most recent Instances saved in the project database. CHECKIN -d[M.N] PROJ [FILE1 FILE2 ... FILEn] If you do not specify a version ("M.N" in the above command spec) then the most recent version will be used, otherwise the files from the specified version will be compared. If you do not specify any files then every file in the project database will be compared. If files are specified then only those files will be compared. This command compares the source files found on disk with the most recent Instances at the specified (or most recent) Version in the project database. It does not alter the project database _______________________________________ file. The differences will be written to a file with the same ____ base name as the source file but with the extension "__D". For example, assume you have modified the source file "FILE1.C" and then enter the following command: CHECKIN -d PROJ FILE1.C The differences between the on-disk version and the checked-in version will be written to a file named "FILE1.__D". The following is an example of the difference file format: < = Version on disk; > = Version checked in < DESC desc1; ---------------------------------------- > DESC desc1, desc2; < run_showdifs(difscript, filename, difoutname); ---------------------------------------- > run_showdifs(filename, difscript, difoutname); ----------------------------------------------------------------- NOTE No check is made for source files that already have an NOTE extension of "__D". This situation could cause severe problems including the possible loss of the source file on disk. ----------------------------------------------------------------- Undoing A Previous CHECKIN Undoing A Previous CHECKIN From time to time you may find it necessary to "undo" the most recent CHECKIN command on a project database. This usually happens because you have accidentally added the wrong files to a page 8 PSCM v1.3 PSCM -- The Project Source Code Manager July 31st, 1992 project file or because you entered a wrong comment. Whatever the reason it would be nice if you could "take that back." The CHECKIN program allows a limited form of this. The "-u" command switch will undo the changes made to a project database by the most recent CHECKIN run. When CHECKIN makes modifications to a project database it saves information in the database about what items were added and which items were changed and how they were changed. This information is used to restore the database to it original condition. To undo a previous CHECKIN run use the command: CHECKIN -u PROJ CHECKIN will first inspect the project database file (PROJ in the above example) and determine if the necessary information is present. If it is not possible to undo the database then CHECKIN will print an error message to this effect and exit. The undo information is deleted at the beginning of a modification run. This means that once you begin an update (using the "-v", "-i", "-c", or "-s" command switches) you can no longer undo the previous modification. This is true even if you abort the current run by pressing Control+C or Control+Break. If the necessary information is present in the database then CHECKIN will prompt you to verify that you truly wish to undo the modifications made by the previous CHECKIN. Press "Y" or "y" to continue with the undo process. Any other key will cause CHECKIN to abort the undo leaving the undo information intact. As each file is restored to its previous version a progress message will display indicating which file is being affected and what version is involved. Note that the Control+C and Control+Break keys are ignored during an undo process. When the undo is complete the undo information is deleted from the project database. ----------------------------------------------------------------- NOTE Undo does not alter any source files on disk. It only NOTE ______________ modifies the contents of the project database file. ----------------------------------------------------------------- PSCM v1.3 page 9 PSCM -- The Project Source Code Manager July 31st, 1992 Special Macros in Source Files Special Macros in Source Files ______________________________ ______________________________ When files are retrieved for editing (see the description of the CHECKOUT program below), certain special "Macro" strings are left in the unexpanded form. When files are retrieved for making (i.e. compiling, assembling, etc.) these Macros are expanded. The Macros can be used to specify version numbers, file dates and times, file names, etc. The Macros are used to place information about the system, project, or file in the text of the file. When the file is retrieved for making, the Macros are replaced with the information specified. There are two types of date and time macros. One form is used to place the current SYSTEM date and time in the file. This is the system date and time when the file is retrieved. The other form is used to place the FILE's date and time in the text. This is the date and time of the last modification to the file. General Macros ------------------------------------------------------- @#D System Date in the form mm/dd/yy @#T System Time in the form hh:mm:ss @#P Project name @#c Revision history comments Configuration File Macros ------------------------------------------------------- @#S System name from the PSCM config file @#1 User parameter 1 from the PSCM config file @#2 User parameter 2 from the PSCM config file @#3 User parameter 3 from the PSCM config file @#4 User parameter 4 from the PSCM config file @#5 User parameter 5 from the PSCM config file @#6 User parameter 6 from the PSCM config file @#7 User parameter 7 from the PSCM config file Version and Revision Macros ------------------------------------------------------- @#v Version number in the form M.N @#r Revision number in the form M.N.R @#M Major version number @#N Minor version number @#R Revision number Source File Modification Information Macros ------------------------------------------------------- @#d File date in the form mm/dd/yy @#t File time in the form hh:mm:ss @#f File name and extension in the form filename.ext @#F File name part only (no extension) page 10 PSCM v1.3 PSCM -- The Project Source Code Manager July 31st, 1992 The Revision Comments Macro The Revision Comments Macro The '@#c' macro is slightly different than all the others. When it is processed, it puts the revision history comments for the source file in the text. The part of the line already printed is put at the beginning of each line before it is inserted in the text. For example, if the lines: /* * @#c */ are in the source text, they will be expanded to look like: /* * * Revision M.N.R entered at HH:MM:SS on MM/DD/YY * Comment line 1 * * Revision M.N.R entered at HH:MM:SS on MM/DD/YY * Comment line 1 * Comment line 2 * * */ Only those comments entered when a file was updated and then checked in using the CHECKIN option '-c' will be printed. Even though the comment may have been entered when more than one file was updated, the comment text will be printed if the current file was included in the update. The comment text is placed in the text file starting with the most recent revision and proceeding to the oldest. When a file is extracted at a specific revision, only those comments which were entered before or at the revision are placed in the file. If no comments are found, the '@#c' macro is simply discarded. ----------------------------------------------------------------- NOTE It is generally NOT a good idea to enter source file NOTE comment symbols in a revision comment. In some languages, most notably 'C', the comment symbols in the expanded comment macro could cause compilation errors. ----------------------------------------------------------------- PSCM v1.3 page 11 PSCM -- The Project Source Code Manager July 31st, 1992 The CHECKOUT Program The CHECKOUT Program ____________________ ____________________ The CHECKOUT program is used to retrieve files from the most recent or a specified Version level. The files can be retrieved for one of two purposes: Editing or Making. Retrieving for Editing or Making Retrieving for Editing or Making When files are retrieved for editing, all special Macros are left in their unexpanded form and the file is written to disk as a modifiable file. When files are retrieved for making, the special Macros are replaced by the appropriate information and the file is marked read-only. This prevents modification of the file. When a file is retrieved (either for editing or making) it is actually retrieved only if the file on disk is different than the retrieved version or the last version was retrieved for the opposite purpose. For example, if a file is retrieved for editing and the version on disk is different (i.e. has a different date and time stamp) then the file will be written to disk. If the file is the same but was last retrieved for editing and is now being retrieved for making, the file will be written to disk. Note that when a file is checked in (using the CHECKIN program) the file on disk is assumed to be retrieved for editing. ----------------------------------------------------------------- NOTE This behavior can sometimes cause problems. Make sure NOTE that you really want CHECKOUT to overwrite ALL POSSIBLE files first. Because of the way DOS overwrites existing files it will not be possible to retrieve a new, and as yet not checked-in, version of a source file once CHECKOUT has overwritten it. ----------------------------------------------------------------- The command line for CHECKOUT is as follows: CHECKOUT -e[M.N[.R]] PROJECT [FILE1 FILE2 ... FILEn] -or- CHECKOUT -m[M.N[.R]] PROJECT [FILE1 FILE2 ... FILEn] The '-e' switch is used to retrieve files for editing. The '-m' switch is used to retrieve files for making. Only one is allowed on the command line. When the Version level is omitted, the most recent version is retrieved. If the Revision number is omitted, the most recent Instance is retrieved. Note that you must specify a Version in order to specify a Revision. If you do not specify any file names on the command line, all files which are different than the version on disk will be retrieved. If one or more files are named in the command, only those files will be retrieved. Note that a file will be page 12 PSCM v1.3 PSCM -- The Project Source Code Manager July 31st, 1992 retrieved only if the version on disk is different (has a different time and date) or was last retrieved for the opposite purpose (editing versus making.) You can use wild cards to specify files for extracting. This allows you to easily specify that all files of a specific type be extracted in one command. You might use this in a MAKE control file to extract all inclusion files before actually beginning the compilation of the source files. Listing the Files in the Project Database Listing the Files in the Project Database The CHECKOUT program is also used to list files in a specific or the latest version. The listing shows each file's name, time and date, and full version and revision number. The command is as follows: CHECKOUT -l[M.N[.R]] PROJECT [FILE1 FILE2 ... FILEn] Note that the command switch is a lower case ell, not the digit one. As with the other forms of the CHECKOUT command, the version and revision numbers and the file names are optional. Listing Comments in the Project Database Listing Comments in the Project Database CHECKOUT can also list the comment records stored in the database. When new Instances of files are created using the '-c' switch in the CHECKIN program, a comment record is saved along with a list of the files that were updated. CHECKOUT can list either a specified comment record, all comment records, or only comments for a specific file or files. The commands used are as follows: CHECKOUT -c[M.N] PROJECT -or- CHECKOUT -cM.N.R PROJECT -or- CHECKOUT -c[M.N] PROJECT FILE1 FILE2 ... FILEn -or- CHECKOUT -cM.N.R PROJECT FILE1 FILE2 ... FILEn The first command form is used to list all comment records. If a Version is specified then all comments for that version will be listed. Otherwise all comments for the latest version are listed. The second command form is used to list a specific comment record. As with source files, all comment records are assigned a Revision number. This revision number is not related to the revision numbers of the other files in the database, it is simply used to track sequential comments. The third and fourth command forms are used to display the comments for specific source files. The former method lists all PSCM v1.3 page 13 PSCM -- The Project Source Code Manager July 31st, 1992 comments entered when the specified files were updated. The latter form lists only those comments entered up to and including the Revision of the source file specified. Both forms list the comments one source file at a time. This means that a single comment may be repeated many times, once for each file listed. The output from the Comment command is sent to STDOUT. This means that it may be redirected to a file or piped to another program if desired. Listing or Retrieving File Sets Listing or Retrieving File Sets The CHECKOUT program is also used to list or retrieve Sets saved in the project database using the CHECKIN program. The Set command forms are as follows: CHECKOUT -s[M.N] PROJECT -or- CHECKOUT -sM.N.R PROJECT -or- CHECKOUT -rM.N.R PROJECT The first form is used to list all Sets saved in the project database file. If a Version is specified then only Sets for that version are listed. If the Version is omitted, then the Sets for the most recent Version are listed. The listing includes the comment saved when the Set was created along with a list of all files and their revisions that were saved in the Set. The listing is sent to STDOUT so it may be redirected to a file or piped to another program. To retrieve the files from a specific Set, the second and third command forms are used. An exact Version and Instance must be specified. Note that the Revision numbers of the Sets are not related to the Revision numbers for files. All files are retrieved at their extant Version and Instance when the Set was created. When the '-s' switch is used, the files are retrieved for Making, so all special macros are expanded and the files are marked as read-only to prevent modification. If the '-r' switch is used, then the files are retrieved for Editing. All macros are left unexpanded and the files are made modifiable. Once a Set has been retrieved, the files may be used to rebuild the project or simply viewed or printed as desired. page 14 PSCM v1.3 PSCM -- The Project Source Code Manager July 31st, 1992 Using PSCM with Make Programs Using PSCM with Make Programs _____________________________ _____________________________ PSCM was designed expressly for use with the various MAKE programs and utilities available both through ShareWare and commercially. In fact, with a little thought you will find that PSCM ceases to be of any concern. You just MAKE your project the way you always do and PSCM handles the modifications without trouble. When files are retrieved from a project database (by the CHECKOUT program) they are given the proper time and date so MAKE can make the right decisions about what should be rebuilt. PSCM will only store or retrieve files that are different thus easing the control issues. Step 1: Pre- and Post-Processing Step 1: Pre- and Post-Processing There are just a few things that you need to do to integrate PSCM into your development environment. The first is to identify where the "PRE" and "POST" processing is done in your make process. Most MAKE programs have readily identifiable stages where PSCM can be added. For example, I use NDMAKE version 4.5 (a very good MAKE utility if you can still find it). NDMAKE, just like Unix make, makes the first target found in the control file. Most control files wind up with a primary target that looks like the following: build: prog1.exe prog2.exe prog3.exe Since "build" is a dummy target (it never exists so must always be remade), NDMAKE proceeds down the list of dependents, rebuilding whatever is necessary to update them. The effect of this is to rebuild all of the program files in the project. This is an excellent candidate for inclusion of PSCM. We can add two new dummy targets to handle the pre- and post-processing needed by PSCM. The preprocessing stage consists of checking in any updated or modified files, and then checking out any files that are not direct targets (i.e. header and inclusion files). If we are using 'C' we might rewrite our make control file as follows: build: PREP prog1.exe prog2.exe prog3.exe FINI PREP: CHECKIN -C PROJ CHECKOUT -M PROJ *.H FINI: CHECKOUT -E PROJ The PREP dummy target will always cause the CHECKIN and CHECKOUT commands to execute. The CHECKIN command causes all modified files to be updated in the PROJ project database and prompts for PSCM v1.3 page 15 PSCM -- The Project Source Code Manager July 31st, 1992 a comment describing the modifications made. The CHECKOUT command then extracts for "making" all the dependent files (header files) that will not be directly compiled. This is all the preparation we need in order to begin compiling. The FINI dummy target runs CHECKOUT one more time to make sure that all our source code files are extracted for editing. Keep in mind that when a file is extracted for making all the macros are expanded and the file is marked read-only. If errors were encountered during the make we want the source files ready to modify without any hassle. Step 2: Templates Step 2: Templates Most (recent) MAKE programs use a special construct called a "Template." A template tells the MAKE program how to build a target file from a source file without having to exactly specify the file name, only the extensions of the two. For example, NDMAKE uses the following template to tell it how to create a .OBJ file from a .C source file: # C -> OBJ .c.obj: ${CC} ${CFLAGS} -c $< The "${CC} ${CFLAGS} -c" are the command and options needed to run the 'C' compiler. During the make process the "$<" is replaced with the name of each .C source file that must be recompiled. This can also be used by CHECKOUT to extract the source file from the project database just before it is compiled. (Remember that our post-processing will extract it for editing at the end of the make run so we only need to extract it for making.) We can change this template to include the CHECKOUT command as follows: # C -> OBJ .c.obj: CHECKOUT -m PROJ $< ${CC} ${CFLAGS} -c $< This simple addition will now cause the compiler to work with source code files that have expanded macros. Enhancements Enhancements What we have just shown is the minimum needed to use PSCM with a MAKE program. There are a few enhancements we can use to improve PSCM's integration into our work methods. page 16 PSCM v1.3 PSCM -- The Project Source Code Manager July 31st, 1992 Most (if not all) MAKE programs allow the use of macros. In the examples shown above the "${CC}" and "${CFLAGS}" are just macros. We can also use macros to further enhance our use of PSCM. By changing the references to "PROJ" in the above examples to "${PROJ}" and then setting the PROJ macro to the name of our project database we make the changes universal. All that we have to do to include PSCM in a different make control file is to copy the modified control lines to the new file and add the PREP and FINI dummy targets to the list of dependents for the primary target. Most MAKE programs also have an initialization file. This file is read when the program starts. It contains standard macros and templates used during the make process. It may be possible for you to modify the initialization file to include the CHECKOUT command. Note that this usually requires decision making and branching capabilities too since we don't want the make to fail just because we don't happen to have a project file. However, it is okay to specify a non-existent source file on the CHECKOUT command line; CHECKOUT will simply checkout nothing. You can also use the CHECKIN feature that allows entering comments from ASCII text files. Simply change the CHECKIN command in the PREP dummy target to include redirecting the contents of the comment file into CHECKIN. For example: CHECKIN -c ${PROJ} < COMMENTS This allows you to keep a running COMMENTS file that describes each change as you make it. You could also use a custom editor macro that extracts this information from the source code and copies it to this file. Either way it helps to further automate the make process. You should make sure to truncate the comments file to zero length after it has been used by CHECKIN. Note that this is not the same as deleting the file. If the file does not exist CHECKIN will not execute because DOS will fail to open the input file. The quickest way to truncate a file to zero length is with the following DOS command: IF 1 == 0 ECHO>COMMENTS Since "1" never equals "0" (at least we hope not) then the ECHO command will never execute. But DOS will truncate the COMMENTS file before it determines that it should skip the ECHO. PSCM v1.3 page 17 PSCM -- The Project Source Code Manager July 31st, 1992 PSCM is ShareWare PSCM is ShareWare _________________ _________________ I have been a software developer for many years. During that time I have acquired and used many very good programs through the "ShareWare" system. ShareWare allows you to try a program before buying it. It does not mean the program is free, nor does it mean that it is a limited version of a commercial program. I wrote PSCM as an answer to my needs in software development. I first came across the idea of source code and revision management when I ported some code from DOS to Unix. The SCCS system on Unix was very neat, but horribly cryptic and cumbersome. Since then I have hunted for a good source code manager, but everything is either priced way out of my range or just wasn't designed to work with a MAKE program. If you try PSCM and you like it and intend to use it, a donation of $25 is suggested. Educational institutions may register PSCM for $15. With a donation of $40 I will send the latest version of PSCM, laser printed docs, and a BIG thank you. If you need a bunch of copies, contact me and we can work something out. To register your copy, print out and complete the registration form (REGISTER.FRM) and mail it to: J. Bart Henthorn 10607 E. Lowry Pl. Aurora, CO 80010-4035 Please make payments by personal check or money order. I cannot accept credit card orders and it is never a good idea to send cash through the mail. If you have questions or comments about PSCM you can contact me by fax at (303) 341-7336. page 18 PSCM v1.3 PSCM -- The Project Source Code Manager July 31st, 1992 Revision History Revision History ________________ ________________ Date Vers Comments 11/15/90 1.0 Initial Release: CHECKIN.EXE, CHECKOUT.EXE, DIFS.EXE, MRGS.EXE, ISIZE.EXE 11/18/90 1.1 Enhancements and Bug Fixes: Added support for Comments and Sets. Fixed bug regarding file selection in CHECKOUT.EXE 11/18/90 1.1a Fixed bug that caused wrong time/date stamps on files listed in a Set. The files were retrieved with the proper time and date, just the listing in the Set was wrong. Added mode to allow extracting Sets for Editing as well as Making. 12/03/90 1.2 New Version 1.2: Added support for revision comments placed in files extracted for making. 07/31/92 1.3 New Version 1.3: Added undo capability. Added comment listing for single files. Added listing of differences. Added SHOWDIFS.EXE program. Trap and handle Control+C and Control+Break. Prevent accidental overwrite of source file. Fixed various bugs. (Please see following page for details.) PSCM v1.3 page 19 PSCM -- The Project Source Code Manager July 31st, 1992 Bugs Fixed and Enhancements Added to Version 1.3 Bugs Fixed and Enhancements Added to Version 1.3 ________________________________________________ ________________________________________________ 1. There was an obscure little bug that doesn't show up often, but when it does it is a booger to find. The PSCM.CFG file can hold seven strings that are expanded as macros when files are extracted from a project file. If one of these strings is exactly the right length the Microsoft fgets() function reads the carriage return (CR) but not the linefeed (LF). On the next call it reads the LF and sets the next string to an empty string and moves the remaining strings down one line. This bug is now fixed in 1.3. 2. I've done it, and I'm sure you've done it too; forget to include the project file name when trying to add new files to an existing project file. Prior versions promptly wrote over the first source file name, creating a new project file with that name. For example: CHECKIN -V0.0 FOO.C BAR.C When what you meant was: CHECKIN -V0.0 PROJ FOO.C BAR.C This little finger faux pas means that your brand new FOO.C module gets overwritten with a brand new project file named FOO.C. This bug has been fixed in version 1.3. CHECKIN now reports that the file FOO.C already exists and is not a project file. 3. CHECKIN, CHECKOUT, MRGS, DIFS and SHOWDIFS are now protected against use of the Control+C or Control+Break keys. Prior versions could do everything from quietly die (at the mild end) to completely trash your Project file (at the severe end). This behavior has now been fixed. CHECKOUT, MRGS, DIFS and SHOWDIFS will now happily ignore these keys. CHECKIN will behave slightly different. If you press either Control+C or Control+Break while CHECKIN is running or when you are entering a comment, the Project file will be politely shut down. If changes have been made to the Project file they will be undone before CHECKIN quits. IMPORTANT: Using Control+C or Control+Break to abort a IMPORTANT CHECKIN run also deletes any "Undo" information that was saved in the Project file before the run was begun. (See next section for more on Undo.) This means that if you start a CHECKIN run and then abort it, you cannot then further undo the Project file. 4. CHECKIN now supports an "Undo" command. This is a single level, one-time only undo. The most recent changes wrought by CHECKIN will be reversed. No source files on disk are page 20 PSCM v1.3 PSCM -- The Project Source Code Manager July 31st, 1992 modified; the Project file is the only file altered. You may only perform an undo once. CHECKIN will print an error message if there is no undo information in the Project file. To undo the previous CHECKIN session, use the following command: CHECKIN -U PROJ Each file will be listed as it is removed or reverted. IMPORTANT: This is an all or nothing proposition. You can not undo only certain files from the previous CHECKIN. All modifications made during the previous run will be undone. 5. The CHECKOUT List command (-L) will now display an extra line if undo information is present in the Project file. 6. The CHECKOUT Comment command (-C) has been enhanced to permit specifying which files should be listed. The display format changes when files are included on the command line. If no files are specified then the output format is the same as in version 1.2. If you do specify file names they will be listed one at a time with all related comments immediately following each individual name. The following is an example of the new report format: === DIFS.C ========================================= Revision: 1.3.1 entered at 22:54:32 on 07/27/92 Added Control-C handler to DIFS and MRGS ==================================================== === MRGS.C ========================================= Revision: 1.3.1 entered at 22:55:20 on 07/27/92 Added Control-C handler to DIFS and MRGS ==================================================== 7. It is sometimes helpful to see how a source file has been modified before it is checked in to the project database. The CHECKIN command now provides a new switch "-D" that performs this function. Before checking in the modified source files you can run "CHECKIN -D PROJ" to create a set of difference files. Each file has the same base name as the source file but with the extension "__D". The following is an example of the difference file format: < = Version on disk; > = Version checked in < DESC desc1; ---------------------------------------- > DESC desc1, desc2; PSCM v1.3 page 21