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, 0 insertions, 1609 deletions
diff --git a/usr.bin/sccs/PSD.doc/sccs.me b/usr.bin/sccs/PSD.doc/sccs.me deleted file mode 100644 index 16dc3fb..0000000 --- a/usr.bin/sccs/PSD.doc/sccs.me +++ /dev/null @@ -1,1609 +0,0 @@ -.\" 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 ). |
