diff options
Diffstat (limited to 'usr.bin/sccs/PSD.doc/sccs.me')
-rw-r--r-- | usr.bin/sccs/PSD.doc/sccs.me | 1609 |
1 files changed, 1609 insertions, 0 deletions
diff --git a/usr.bin/sccs/PSD.doc/sccs.me b/usr.bin/sccs/PSD.doc/sccs.me new file mode 100644 index 0000000..16dc3fb --- /dev/null +++ b/usr.bin/sccs/PSD.doc/sccs.me @@ -0,0 +1,1609 @@ +.\" Copyright (c) 1986, 1993 +.\" The Regents of the University of California. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" 3. All advertising materials mentioning features or use of this software +.\" must display the following acknowledgement: +.\" This product includes software developed by the University of +.\" California, Berkeley and its contributors. +.\" 4. Neither the name of the University nor the names of its contributors +.\" may be used to endorse or promote products derived from this software +.\" without specific prior written permission. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND +.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE +.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE +.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE +.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL +.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS +.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) +.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT +.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY +.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF +.\" SUCH DAMAGE. +.\" +.\" @(#)sccs.me 8.2 (Berkeley) 6/1/94 +.\" +.eh '\fRPSD:14-%\fP''\fRAn Introduction to the Source Code Control System\fP' +.oh '\fRAn Introduction to the Source Code Control System\fP''\fRPSD:14-%\fP' +.ds S \s-1SCCS\s0 +.ds I \s-1SID\s0 +.nr bi 8n +.ev 1 \" only for keeps +.ss 16 +.ev +.\".he '\*S Introduction''%' +.+c +.(l C +.sz 14 +.b +An Introduction to the +Source Code Control System +.sz +.r +.sp +Eric Allman +.i "Project Ingres" +.i "University of California at Berkeley" +.)l +.sp 3 +.pp +.(f +This is version 1.21 of this document. +It was last modified on 12/5/80. +.)f +This document gives a quick introduction +to using the Source Code Control System +(\*S). +The presentation is geared to programmers +who are more concerned with +what +to do to get a task done +rather than how it works; +for this reason some of the examples +are not well explained. +For details of what the magic options do, +see the section on +.q "Further Information" . +.(l F +This is a working document. +Please send any comments or suggestions +to eric@Berkeley.Edu. +.)l +.sh 1 "Introduction" +.pp +\*S is a source management system. +Such a system maintains a record of versions of a system; +a record is kept with each set of changes +of what the changes are, +why they were made, +and who made them and when. +Old versions can be recovered, +and different versions can be maintained simultaneously. +In projects with more than one person, +\*S will insure that two people are not +editing the same file at the same time. +.pp +All versions of your program, +plus the log and other information, +is kept in a file called the +.q "s-file" . +There are three major operations +that can be performed on the s-file: +.np +Get a file for compilation (not for editing). +This operation retrieves a version of the file +from the s-file. +By default, the latest version is retrieved. +This file is intended for compilation, printing, or whatever; +it is specifically NOT intended to be edited +or changed in any way; +any changes made to a file retrieved +in this way will probably be lost. +.np +Get a file for editing. +This operation also retrieves a version of the file +from the s-file, +but this file is intended to be edited and then +incorporated back into the s-file. +Only one person may be editing a file at one time. +.np +Merge a file back into the s-file. +This is the companion operation to (2). +A new version number is assigned, +and comments are saved explaining why this change was made. +.sh 1 "Learning the Lingo" +.pp +There are a number of terms that are worth learning +before we go any farther. +.sh 2 "S-file" +.pp +The s-file +is a single file that holds all the different versions +of your file. +The s-file is stored in +differential format; +.i i.e. , +only the differences between versions are stored, +rather than the entire text of the new version. +This saves disk space +and allows selective changes to be removed later. +Also included in the s-file +is some header information for each version, +including the comments given by the person who +created the version explaining why the changes were made. +.sh 2 "Deltas" +.pp +Each set of changes to the s-file +(which is approximately [but not exactly!] equivalent +to a version of the file) +is called a +.i delta . +Although technically a delta only includes the +.i changes +made, +in practice +it is usual for +each delta to be made with respect to +all the deltas that have occurred before\**. +.(f +\**This matches normal usage, where the previous changes are not saved +at all, +so all changes are automatically based on all other changes +that have happened through history. +.)f +However, +it is possible to get a version of the file +that has selected deltas removed out of the middle +of the list of changes \*- +equivalent to removing your changes later. +.sh 2 "\*I's (or, version numbers)" +.pp +A \*I +(\*S Id) +is a number that represents a delta. +This is normally a two-part number +consisting of a +.q release +number and a +.q level +number. +Normally the release number stays the same, +however, +it is possible to move into a new release +if some major change is being made. +.pp +Since all past deltas are normally applied, +the \*I of the final delta applied +can be used to represent a version number of the file +as a whole. +.sh 2 "Id keywords" +.pp +When you get a version of a file +with intent to compile and install it +(\c +.i i.e. , +something other than edit it), +some special keywords are expanded inline +by \*S. +These +.i "Id Keywords" +can be used to include the current version number +or other information into the file. +All id keywords are of the form +.b % \c +.i x \c +.b % , +where +.i x +is an upper case letter. +For example, +.b %\&I\&% +is the \*I of the latest delta applied, +.b %\&W\&% +includes the module name, +\*I, +and a mark that makes it findable by a program, +and +.b %\&G\&% +is the date of the latest delta applied. +There are many others, +most of which are of dubious usefulness. +.pp +When you get a file for editing, +the id keywords are not expanded; +this is so that after you put them back in to the s-file, +they will be expanded automatically on each new version. +But notice: if you were to get them +expanded accidently, +then your file would appear to be the same version +forever more, +which would of course defeat the purpose. +Also, +if you should install a version of the program +without expanding the id keywords, +it will be impossible to tell what version it is +(since all it will have is +.q %\&W\&% +or whatever). +.sh 1 "Creating \*S Files" +.pp +To put source files +into +\*S +format, run the following shell script from csh: +.(b +mkdir SCCS save +foreach i (*.[ch]) + sccs admin \-i$i $i + mv $i save/$i +end +.)b +This will put the named files +into s-files +in the subdirectory +.q SCCS +The files will be removed from the current directory +and hidden away in the directory +.q save , +so the next thing you will probably want to do +is to get all the files +(described below). +When you are convinced that +\*S has correctly created the s-files, +you should remove the directory +.q save . +.pp +If you want to have id keywords in the files, +it is best to put them in before you create the s-files. +If you do not, +.i admin +will print +.q "No Id Keywords (cm7)" , +which is a warning message only. +.sh 1 "Getting Files for Compilation" +.pp +To get a copy of the latest version +of a file, +run +.(b +sccs get prog.c +.)b +\*S will respond: +.(b +1.1 +87 lines +.)b +meaning that version 1.1 was retrieved\** +.(f +\**Actually, +the \*I of the final delta applied was 1.1. +.)f +and that it has 87 lines. +The file +.i prog.c +will be created +in the current directory. +The file will be read-only +to remind you that you are not +supposed to change it. +.pp +This copy of the file +should not be changed, +since \*S is unable +to merge the changes +back into the s-file. +If you do make changes, +they will be lost the next time +someone does a +.i get . +.sh 1 "Changing Files (or, Creating Deltas)" +.sh 2 "Getting a copy to edit" +.pp +To edit a source file, +you must first get it, +requesting permission to edit it\**: +.(f +\**The +.q "edit" +command is equivalent to using the \-e +flag to +.i "get" , +as: +.(l +sccs get \-e prog.c +.)l +Keep this in mind when reading other documentation. +.)f +.(b +sccs edit prog.c +.)b +The response will be the same as with +.i get +except that it will also say: +.(b +New delta 1.2 +.)b +You then edit it, +using a standard text editor: +.(b +vi prog.c +.)b +.sh 2 "Merging the changes back into the s-file" +.pp +When the desired changes are made, +you can put your changes into the +\*S +file using the +.i delta +command: +.(b +sccs delta prog.c +.)b +.pp +Delta will prompt you for +.q "comments?" +before it merges the changes in. +At this prompt you should type a one-line description +of what the changes mean +(more lines can be entered by ending each line +except the last with a backslash\**). +.(f +\**Yes, this is a stupid default. +.)f +.i Delta +will then type: +.(b +1.2 +5 inserted +3 deleted +84 unchanged +.)b +saying that delta 1.2 was created, +and it inserted five lines, +removed three lines, +and left 84 lines unchanged\**. +.(f +\**Changes to a line are counted as a line deleted +and a line inserted. +.)f +The +.i prog.c +file will be removed; +it can be retrieved +using +.i get . +.sh 2 "When to make deltas" +.pp +It is probably unwise to make a delta +before every recompilation or test; +otherwise, +you tend to get a lot of deltas with comments like +.q "fixed compilation problem in previous delta" +or +.q "fixed botch in 1.3" . +However, +it is very important to delta everything +before installing a module for general use. +A good technique is to edit the files you need, +make all necessary changes and tests, +compiling and editing as often as necessary +without making deltas. +When you are satisfied that you have a working version, +delta everything being edited, +re-get them, +and recompile everything. +.sh 2 "What's going on: the info command" +.pp +To find out what files where being edited, +you can use: +.(b +sccs info +.)b +to print out all the files being edited +and other information such as the name of the user +who did the edit. +Also, +the command: +.(b +sccs check +.)b +is nearly equivalent to the +.i info +command, +except that it is silent if nothing is being edited, +and returns non-zero exit status if anything is being edited; +it can be used in an +.q install +entry in a makefile +to abort the install +if anything has not been properly deltaed. +.pp +If you know that everything being edited should be deltaed, +you can use: +.(b +sccs delta \`sccs tell\` +.)b +The +.i tell +command is similar to +.i info +except that only the names of files being edited +are output, +one per line. +.pp +All of these commands take a +.b \-b +flag +to ignore +.q branches +(alternate versions, described later) +and the +.b \-u +flag to only give files being edited by you. +The +.b \-u +flag takes an optional +.i user +argument, +giving only files being edited by that user. +For example, +.(b +sccs info \-ujohn +.)b +gives a listing of files being edited by john. +.sh 2 "ID keywords" +.pp +Id keywords can be inserted into your file +that will be expanded automatically by +.i get . +For example, +a line such as: +.(b +static char SccsId[] = "%\&W\&%\et%\&G\&%"; +.)b +will be replaced with something like: +.(b +static char SccsId[] = "@\&(#)prog.c 1.2 08/29/80"; +.)b +This tells you +the name and version +of the source file +and the time the delta was created. +The string +.q "@\&(#)" +is a special string +which signals the beginning +of an +\*S +Id keyword. +.sh 3 "The what command" +.pp +To find out what version of a program +is being run, +use: +.(b +sccs what prog.c /usr/bin/prog +.)b +which will print all strings +it finds that +begin with +.q "@\&(#)" . +This works on all types of files, +including binaries and libraries. +For example, the above command will output something like: +.(b +prog.c: + prog.c 1.2 08/29/80 +/usr/bin/prog: + prog.c 1.1 02/05/79 +.)b +From this I can see +that the source that I have in prog.c +will not compile into the same version +as the binary in /usr/bin/prog. +.sh 3 "Where to put id keywords" +.pp +ID keywords can be inserted anywhere, +including in comments, +but +Id Keywords that are compiled into the object module +are especially useful, +since it lets you find out what version of +the object is being run, +as well as the source. +However, +there is a cost: +data space is used up to store +the keywords, +and on small address space machines +this may be prohibitive. +.pp +When you put id keywords into header files, +it is important that you assign them to different variables. +For example, you might use: +.(b +static char AccessSid[] = "%\&W\&% %\&G\&%"; +.)b +in the file +.i access.h +and: +.(b +static char OpsysSid[] = "%\&W\&% %\&G\&%"; +.)b +in the file +.i opsys.h . +Otherwise, +you will get compilation errors because +.q SccsId +is redefined. +The problem with this is that if the header file +is included by many modules that are loaded together, +the version number of that header file is included +in the object module many times; +you may find it more to your taste +to put id keywords in header files +in comments. +.sh 2 "Keeping \*I's consistent across files" +.pp +With some care, +it is possible to keep the \*I's consistent +in multi-file systems. +The trick here is to always +.i edit +all files +at once. +The changes can then be made +to whatever files are necessary +and then all files +(even those not changed) +are redeltaed. +This can be done fairly easily +by just specifying the name of the directory +that the \*S files are in: +.(b +sccs edit SCCS +.)b +which will +.i edit +all files in that directory. +To make the delta, use: +.(b +sccs delta SCCS +.)b +You will be prompted for comments only once. +.sh 2 "Creating new releases" +.pp +When you want to create a new release +of a program, +you can specify the release number you want to create +on the +.i edit +command. +For example: +.(b +sccs edit \-r2 prog.c +.)b +will cause the next delta to be in release two +(that is, +it will be numbered 2.1). +Future deltas will automatically be in release two. +To change the release number +of an entire system, +use: +.(b +sccs edit \-r2 SCCS +.)b +.sh 1 "Restoring Old Versions" +.sh 2 "Reverting to old versions" +.pp +Suppose that after delta 1.2 +was stable +you made and released a delta 1.3. +But this introduced a bug, +so you made a delta 1.4 to correct it. +But 1.4 was still buggy, +and you decided you wanted to go back +to the old version. +You could +revert to delta 1.2 +by choosing the \*I in a get: +.(b +sccs get \-r1.2 prog.c +.)b +This will produce a version of +.i prog.c +that is delta 1.2 +that can be reinstalled so that work can proceed. +.pp +In some cases you don't know +what the \*I of the delta you want is. +However, +you can revert to the version of the program +that was running as of a certain date +by using the +.b \-c +(cutoff) flag. +For example, +.(b +sccs get \-c800722120000 prog.c +.)b +will retrieve whatever version was current +as of July 22, 1980 +at 12:00 noon. +Trailing components can be stripped off +(defaulting to their highest legal value), +and punctuation can be inserted in the obvious +places; +for example, +the above line could be equivalently stated: +.(b +sccs get \-c"80/07/22 12:00:00" prog.c +.)b +.sh 2 "Selectively deleting old deltas" +.pp +Suppose that you later decided +that you liked the changes in delta 1.4, +but that delta 1.3 should be removed. +You could do this by +.i excluding +delta 1.3: +.(b +sccs edit \-x1.3 prog.c +.)b +.ne 1i +When delta 1.5 is made, +it will include the changes made +in delta 1.4, +but will exclude the changes made +in delta 1.3. +You can exclude a range of deltas +using a dash. +For example, +if you want to get rid of 1.3 and 1.4 +you can use: +.(b +sccs edit \-x1.3\-1.4 prog.c +.)b +which will exclude all deltas from 1.3 to 1.4. +Alternatively, +.(b +sccs edit \-x1.3\-1 prog.c +.)b +will exclude a range of deltas +from 1.3 to the current highest delta in release 1. +.pp +In certain cases when using +.b \-x +(or +.b \-i ; +see below) +there will be conflicts +between versions; +for example, it may be necessary +to both include and delete +a particular line. +If this happens, +\*S always prints out a message +telling the range of lines effected; +these lines should then be examined very carefully +to see if the version \*S got +is ok. +.pp +Since each delta +(in the sense of +.q "a set of changes" ) +can be excluded at will, +that this makes it most useful +to put each semantically distinct change +into its own delta. +.sh 1 "Auditing Changes" +.sh 2 "The prt command" +.pp +When you created a delta, +you presumably gave a reason for the delta +to the +.q "comments?" +prompt. +To print out these comments later, +use: +.(b +sccs prt prog.c +.)b +This will produce +a report +for each delta +of the \*I, +time and date of creation, +user who created the delta, +number of lines inserted, deleted, and unchanged, +and the comments associated with the delta. +For example, the output of the above command might be: +.(b +D 1.2 80/08/29 12:35:31 bill 2 1 00005/00003/00084 +removed "-q" option +.sp \n(psu +D 1.1 79/02/05 00:19:31 eric 1 0 00087/00000/00000 +date and time created 80/06/10 00:19:31 by eric +.)b +.sh 2 "Finding why lines were inserted" +.pp +To find out +why you inserted lines, +you can get a copy of the file +with each line +preceded by the \*I that created it: +.(b +sccs get \-m prog.c +.)b +You can then find out +what this delta did +by printing the comments using +.i prt . +.pp +To find out what lines are associated with a particular delta +(\c +.i e.g. , +1.3), +use: +.(b +sccs get \-m \-p prog.c \(bv grep \'^1.3\' +.)b +The +.b \-p +flag causes \*S to output the generated source +to the standard output rather than to a file. +.sh 2 "Finding what changes you have made" +.pp +When you are editing a file, +you can find out what changes you have made using: +.(b +sccs diffs prog.c +.)b +Most of the ``diff'' flags can be used. +To pass the +.b \-c +flag, +use +.b \-C . +.pp +To compare two versions that are in deltas, +use: +.(b +sccs sccsdiff -r1.3 -r1.6 prog.c +.)b +to see the differences between delta 1.3 and delta 1.6. +.sh 1 "Shorthand Notations" +.pp +There are several sequences of commands that get +executed frequently. +.i Sccs +tries to make it easy to do these. +.sh 2 "Delget" +.pp +A frequent requirement is to make a delta of some file +and then get that file. +This can be done by using: +.(b +sccs delget prog.c +.)b +which is entirely equivalent to using: +.(b +sccs delta prog.c +sccs get prog.c +.)b +The +.q deledit +command is equivalent to +.q delget +except that the +.q edit +command is used +instead of the +.q get +command. +.sh 2 "Fix" +.pp +Frequently, there are small bugs +in deltas, +e.g., compilation errors, +for which there is no reason to maintain an audit trail. +To +.i replace +a delta, use: +.(b +sccs fix \-r1.4 prog.c +.)b +This will get a copy of delta 1.4 of prog.c for you to edit +and then delete delta 1.4 from the \*S file. +When you do a delta of prog.c, +it will be delta 1.4 again. +The \-r flag must be specified, +and the delta that is specified must be a leaf delta, +i.e., no other deltas may have been made subsequent +to the creation of that delta. +.sh 2 "Unedit" +.pp +If you found you edited a file +that you did not want to edit, +you can back out by using: +.(b +sccs unedit prog.c +.)b +.sh 2 "The \-d flag" +.pp +If you are working on a project +where the \*S code is in a directory somewhere, +you may be able to simplify things +by using a shell alias. +For example, +the alias: +.(b +alias syssccs sccs \-d/usr/src +.)b +will allow you to issue commands such as: +.(b +syssccs edit cmd/who.c +.)b +which will look for the file +.q "/usr/src/cmd/SCCS/who.c" . +The file +.q who.c +will always be created in your current directory +regardless of the value of the \-d flag. +.sh 1 "Using \*S on a Project" +.pp +Working on a project with several people +has its own set of special problems. +The main problem occurs when two people +modify a file at the same time. +\*S prevents this by locking an s-file +while it is being edited. +.pp +As a result, +files should not be reserved for editing +unless they are actually being edited at the time, +since this will prevent other people on the project +from making necessary changes. +For example, +a good scenario for working might be: +.(b +sccs edit a.c g.c t.c +vi a.c g.c t.c +# do testing of the (experimental) version +sccs delget a.c g.c t.c +sccs info +# should respond "Nothing being edited" +make install +.)b +.pp +As a general rule, +all source files should be deltaed +before installing the program for general use. +This will insure that it is possible +to restore any version in use at any time. +.sh 1 "Saving Yourself" +.sh 2 "Recovering a munged edit file" +.pp +Sometimes you may find +that you have destroyed or trashed +a file that you were trying to edit\**. +.(f +\**Or given up and decided to start over. +.)f +Unfortunately, +you can't just remove it +and re-\c +.i edit +it; +\*S keeps track +of the fact +that someone is trying to edit it, +so it won't let you do it again. +Neither can you just get it using +.i get , +since that would expand the Id keywords. +Instead, +you can say: +.(b +sccs get \-k prog.c +.)b +This will not expand the Id keywords, +so it is safe to do a delta +with it. +.pp +Alternately, +you can +.i unedit +and +.i edit +the file. +.sh 2 "Restoring the s-file" +.pp +In particularly bad circumstances, +the \*S file itself +may get munged. +The most common way this happens +is that it gets edited. +Since \*S keeps a checksum, +you will get errors every time you read the file. +To fix this checksum, use: +.(b +sccs admin \-z prog.c +.)b +.sh 1 "Using the Admin Command" +.pp +There are a number of parameters that can be set +using the +.i admin +command. +The most interesting of these are flags. +Flags can be added by using the +.b \-f +flag. +For example: +.(b +sccs admin \-fd1 prog.c +.)b +sets the +.q d +flag to the value +.q 1 . +This flag can be deleted by using: +.(b +sccs admin \-dd prog.c +.)b +The most useful flags are: +.nr ii 7n +.ip "b" +Allow branches to be made using the +\-b +flag to +.i edit . +.ip "d\fISID\fP" +Default \*I to be used on a +.i get +or +.i edit . +If this is just a release number +it constrains the +version +to a particular release only. +.ip "i" +Give a fatal error +if there are no Id Keywords in a file. +This is useful to guarantee that a version of the +file does not get merged into the s-file +that has the Id Keywords inserted as constants +instead of internal forms. +.ip "y" +The +.q type +of the module. +Actually, +the value of this flag is unused by \*S +except that it replaces the +.b %\&Y\&% +keyword. +.pp +The +.b \-t\fIfile\fR +flag can be used +to store descriptive text +from +.i file . +This descriptive text might be the documentation +or a design and implementation document. +Using the +.b \-t +flag insures that if the \*S file is sent, +the documentation will be sent also. +If +.i file +is omitted, +the descriptive text is deleted. +To see the descriptive text, +use +.q "prt \-t" . +.pp +The +.i admin +command can be used safely +any number of times on files. +A file need not be gotten +for +.i admin +to work. +.sh 1 "Maintaining Different Versions (Branches)" +.pp +Sometimes it is convenient +to maintain an experimental version of a program +for an extended period +while normal maintenance continues +on the version in production. +This can be done using a +.q branch. +Normally deltas continue in a straight line, +each depending on the delta before. +Creating a branch +.q "forks off" +a version of the program. +.pp +The ability to create branches +must be enabled in advance using: +.(b +sccs admin \-fb prog.c +.)b +The +.b \-fb +flag can be specified when the +\*S file is first created. +.sh 2 "Creating a branch" +.pp +To create a branch, use: +.(b +sccs edit \-b prog.c +.)b +This will create a branch +with (for example) \*I 1.5.1.1. +The deltas for this version +will be numbered +1.5.1.\c +.i n . +.sh 2 "Getting from a branch" +.pp +Deltas in a branch are normally not included +when you do a get. +To get these versions, +you will have to say: +.(b +sccs get \-r1.5.1 prog.c +.)b +.sh 2 "Merging a branch back into the main trunk" +.pp +At some point you will have finished the experiment, +and if it was successful +you will want to incorporate it into the release version. +But in the meantime +someone may have created a delta 1.6 +that you don't want to lose. +The commands: +.(b +sccs edit \-i1.5.1.1\-1.5.1 prog.c +sccs delta prog.c +.)b +will merge all of your changes +into the release system. +If some of the changes conflict, +get will print an error; +the generated result +should be carefully examined +before the delta is made. +.sh 2 "A more detailed example" +.pp +The following technique might be used +to maintain a different version of a program. +First, +create a directory to contain the new version: +.(b +mkdir ../newxyz +cd ../newxyz +.)b +Edit a copy of the program +on a branch: +.(b +sccs \-d../xyz edit prog.c +.)b +When using the old version, +be sure to use the +.b \-b +flag to info, check, tell, and clean +to avoid confusion. +For example, use: +.(b +sccs info \-b +.)b +when in the directory +.q xyz . +.pp +If you want to save a copy of the program +(still on the branch) +back in the s-file, +you can use: +.(b +sccs -d../xyz deledit prog.c +.)b +which will do a delta on the branch +and reedit it for you. +.pp +When the experiment is complete, merge it back into the s-file +using delta: +.(b +sccs -d../xyz delta prog.c +.)b +At this point you must decide whether this version +should be merged back into the trunk +(\c +.i i.e. +the default version), +which may have undergone changes. +If so, it can be merged using the +.b \-i +flag to +.i edit +as described above. +.sh 2 "A warning" +.pp +Branches should be kept to a minimum. +After the first branch from the trunk, +\*I's are assigned rather haphazardly, +and the structure gets complex fast. +.sh 1 "Using \*S with Make" +.pp +\*S and make can be made to work together +with a little care. +A few sample makefiles +for common applications are shown. +.pp +There are a few basic entries that every makefile +ought to have. +These are: +.nr ii 1i +.ip a.out +(or whatever the makefile generates.) +This entry regenerates whatever this makefile is +supposed to regenerate. +If the makefile regenerates many things, +this should be called +.q all +and should in turn +have dependencies on everything +the makefile can generate. +.ip install +Moves the objects to the final +resting place, +doing any special +.i chmod 's +or +.i ranlib 's +as appropriate. +.ip sources +Creates all the source files from \*S files. +.ip clean +Removes all files from the current directory +that can be regenerated from \*S files. +.ip print +Prints the contents of the directory. +.lp +The examples shown below are only partial examples, +and may omit some of these entries +when they are deemed to be obvious. +.pp +The +.i clean +entry should not remove files that can be +regenerated from the \*S files. +It is sufficiently important to have the +source files around at all times +that the only time they should be removed +is when the directory is being mothballed. +To do this, the command: +.(b +sccs clean +.)b +can be used. +This will remove all files for which an s-file +exists, +but which is not being edited. +.sh 2 "To maintain single programs" +.pp +Frequently there are directories with several +largely unrelated programs +(such as simple commands). +These can be put into a single makefile: +.(b +LDFLAGS= \-i \-s +.sp \n(psu +prog: prog.o + $(CC) $(LDFLAGS) \-o prog prog.o +prog.o: prog.c prog.h +.sp \n(psu +example: example.o + $(CC) $(LDFLAGS) \-o example example.o +example.o: example.c +.sp \n(psu +\&.DEFAULT: + sccs get $< +.)b +The trick here +is that the .DEFAULT rule +is called every time +something is needed +that does not exist, +and no other rule exists to make it. +The explicit dependency of the +.b \&.o +file on the +.b \&.c +file is important. +Another way of doing the same thing is: +.(b +SRCS= prog.c prog.h example.c +.sp \n(psu +LDFLAGS= \-i \-s +.sp \n(psu +prog: prog.o + $(CC) $(LDFLAGS) \-o prog prog.o +prog.o: prog.h +.sp \n(psu +example: example.o + $(CC) $(LDFLAGS) \-o example example.o +.sp \n(psu +sources: $(SRCS) +$(SRCS): + sccs get $@ +.)b +There are a couple of advantages to this approach: +(1) the explicit dependencies of the .o on the .c files are +not needed, +(2) there is an entry called "sources" so if you want to get +all the sources you can just say +.q "make sources" , +and +(3) the makefile is less likely to do confusing things +since it won't try to +.i get +things that do not exist. +.sh 2 "To maintain a library" +.pp +Libraries that are largely static +are best updated using explicit commands, +since +.i make +doesn't know about updating them properly. +However, +libraries that are in the process of being developed +can be handled quite adequately. +The problem is that the .o files +have to be kept out of the library +as well as in the library. +.(b +# configuration information +OBJS= a.o b.o c.o d.o +SRCS= a.c b.c c.c d.s x.h y.h z.h +TARG= /usr/lib +.sp \n(psu +# programs +GET= sccs get +REL= +AR= \-ar +RANLIB= ranlib +.sp \n(psu +lib.a: $(OBJS) + $(AR) rvu lib.a $(OBJS) + $(RANLIB) lib.a +.sp \n(psu +install: lib.a + sccs check + cp lib.a $(TARG)/lib.a + $(RANLIB) $(TARG)/lib.a +.sp \n(psu +sources: $(SRCS) +$(SRCS): + $(GET) $(REL) $@ +.sp \n(psu +print: sources + pr *.h *.[cs] +clean: + rm \-f *.o + rm \-f core a.out $(LIB) +.)b +.pp +The +.q "$(REL)" +in the get +can be used to get old versions +easily; for example: +.(b +make b.o REL=\-r1.3 +.)b +.pp +The +.i install +entry includes the line +.q "sccs check" +before anything else. +This guarantees that all the s-files +are up to date +(\c +.i i.e. , +nothing is being edited), +and will abort the +.i make +if this condition is not met. +.sh 2 "To maintain a large program" +.(b +OBJS= a.o b.o c.o d.o +SRCS= a.c b.c c.y d.s x.h y.h z.h +.sp \n(psu +GET= sccs get +REL= +.sp \n(psu +a.out: $(OBJS) + $(CC) $(LDFLAGS) $(OBJS) $(LIBS) +.sp \n(psu +sources: $(SRCS) +$(SRCS): + $(GET) $(REL) $@ +.)b +(The +.i print +and +.i clean +entries are identical to the previous case.) +This makefile requires copies of the source and object files +to be kept during development. +It is probably also wise to include lines of the form: +.(b +a.o: x.h y.h +b.o: z.h +c.o: x.h y.h z.h +z.h: x.h +.)b +so that modules will be recompiled +if header files change. +.pp +Since +.i make +does not do transitive closure on dependencies, +you may find in some makefiles lines like: +.(b +z.h: x.h + touch z.h +.)b +This would be used in cases where file z.h +has a line: +.(b +#include "x.h" +.)b +in order to bring the mod date of z.h in line +with the mod date of x.h. +When you have a makefile such as above, +the +.i touch +command can be removed completely; +the equivalent effect will be achieved +by doing an automatic +.i get +on z.h. +.sh 1 "Further Information" +.pp +The +.i "SCCS/PWB User's Manual" +gives a deeper description +of how to use \*S. +Of particular interest +are the numbering of branches, +the l-file, +which gives a description of what deltas were used on a get, +and certain other \*S commands. +.pp +The \*S manual pages +are a good last resort. +These should be read by software managers +and by people who want to know +everything about everything. +.pp +Both of these documents were written without the +.i sccs +front end in mind, +so most of the examples are slightly different from those +in this document. +.bp +.sz 12 +.ce +.b "Quick Reference" +.sz +.sp 2 +.sh 1 Commands 1 +.pp +The following commands should all be preceded with +.q sccs . +This list is not exhaustive; +for more options see +.i "Further Information" . +.ip get 9n +Gets files for compilation (not for editing). +Id keywords are expanded. +.ba 9n +.nr ii 8n +.ip \-r\fI\*I\fP +Version to get. +.ip \-p +Send to standard output rather than to the actual file. +.ip \-k +Don't expand id keywords. +.ip \-i\fIlist\fP +List of deltas to include. +.ip \-x\fIlist\fP +List of deltas to exclude. +.ip \-m +Precede each line with \*I of creating delta. +.ip \-c\fIdate\fP +Don't apply any deltas created after +.i date. +.ba +.ip edit 9n +Gets files for editing. +Id keywords are not expanded. +Should be matched with a +.i delta +command. +.ba 9n +.nr ii 8n +.ip \-r\fI\*I\fP +Same as +.i get . +If +.i \*I +specifies a release that does not yet exist, +the highest numbered delta is retrieved +and the new delta is numbered with +.i \*I . +.ip \-b +Create a branch. +.ip \-i\fIlist\fP +Same as +.i get . +.ip \-x\fIlist\fP +Same as +.i get . +.ba +.ip delta 9n +Merge a file gotten using +.i edit +back into the s-file. +Collect comments about why this delta was made. +.ip unedit 9n +Remove a file that has been edited previously +without merging the changes into the s-file. +.ip prt 9n +Produce a report of changes. +.ba 9n +.nr ii 5n +.ip \-t +Print the descriptive text. +.ip \-e +Print (nearly) everything. +.ba +.ip info 9n +Give a list of all files being edited. +.ba 9n +.nr ii 5n +.ip \-b +Ignore branches. +.ip \-u[\fIuser\fP] +Ignore files not being edited by +.i user . +.ba +.ip check 9n +Same as +.i info , +except that nothing is printed if nothing is being edited +and exit status is returned. +.ip tell 9n +Same as +.i info , +except that one line is produced per file being edited containing +only the file name. +.ip clean 9n +Remove all files that can be regenerated from the +s-file. +.ip what 9n +Find and print id keywords. +.ip admin 9n +Create or set parameters on s-files. +.ba 9n +.nr ii 8n +.ip \-i\fIfile\fP +Create, using +.i file +as the initial contents. +.ip \-z +Rebuild the checksum in case +the file has been trashed. +.ip \-f\fIflag\fP +Turn on the +.i flag . +.ip \-d\fIflag\fP +Turn off (delete) the +.i flag . +.ip \-t\fIfile\fP +Replace the descriptive text +in the s-file with the contents of +.i file . +If +.i file +is omitted, +the text is deleted. +Useful for storing documentation +or +.q "design & implementation" +documents to insure they get distributed with the +s-file. +.lp +Useful flags are: +.ip b +Allow branches to be made using the \-b flag to +.i edit. +.ip d\fI\*I\fP +Default \*I to be used +on a +.i get +or +.i edit . +.ip i +Cause +.q "No Id Keywords" +error message +to be a fatal error rather than a warning. +.ip t +The module +.q type ; +the value of this flag replaces the +.b %\&Y\&% +keyword. +.ba +.ip fix 9n +Remove a delta and reedit it. +.ip delget 9n +Do a +.i delta +followed by a +.i get . +.ip deledit 9n +Do a +.i delta +followed by an +.i edit . +.sh 1 "Id Keywords" +.nr ii 6n +.ip "%\&Z\&%" +Expands to +.q @\&(#) +for the +.i what +command to find. +.ip "%\&M\&%" +The current module name, +.i e.g., +.q prog.c . +.ip "%\&I\&%" +The highest \*I applied. +.ip "%\&W\&%" +A shorthand for +.q "%\&Z\&%%\&M\&% <tab> %\&I\&%" . +.ip "%\&G\&%" +The date of the delta +corresponding to the +.q "%\&I\&%" +keyword. +.ip "%\&R\&%" +The current release number, +.i i.e. , +the first component of the +.q "%\&I\&%" +keyword. +.ip "%\&Y\&%" +Replaced by the value of the +.b t +flag +(set by +.i admin ). |