rsalz@uunet.uu.net (Rich Salz) (05/04/90)
Submitted-by: Brian Berliner <berliner@prisma.com>
Posting-number: Volume 22, Issue 20
Archive-name: cvs-berliner/part06
#! /bin/sh
# This is a shell archive. Remove anything before this line, then unpack
# it by saving it into a file and typing "sh file". To overwrite existing
# files, type "sh file -c". You can also feed this as standard input via
# unshar, or by typing "sh <file", e.g.. If this archive is complete, you
# will see the following message at the end:
# "End of archive 6 (of 7)."
# Contents: doc/cvs.ms
# Wrapped by rsalz@litchi.bbn.com on Thu May 3 16:59:06 1990
PATH=/bin:/usr/bin:/usr/ucb ; export PATH
if test -f 'doc/cvs.ms' -a "${1}" != "-c" ; then
echo shar: Will not clobber existing file \"'doc/cvs.ms'\"
else
echo shar: Extracting \"'doc/cvs.ms'\" \(37780 characters\)
sed "s/^X//" >'doc/cvs.ms' <<'END_OF_FILE'
X.\" soelim cvs.ms | pic | tbl | troff -ms
X.\" $Id: cvs.ms,v 1.1 89/11/19 23:16:42 berliner Exp $
X.\"
X.\" troff source to the cvs USENIX article, Winter 1990, Washington, D.C.
X.\" Copyright (c) 1989, Brian Berliner
X.\"
X.\" This program is free software; you can redistribute it and/or modify
X.\" it under the terms of the GNU General Public License as published by
X.\" the Free Software Foundation; either version 1, or (at your option)
X.\" any later version.
X.\"
X.\" This program is distributed in the hope that it will be useful,
X.\" but WITHOUT ANY WARRANTY; without even the implied warranty of
X.\" MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
X.\" GNU General Public License for more details.
X.\"
X.\" You should have received a copy of the GNU General Public License
X.\" along with this program; if not, write to the Free Software
X.\" Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
X.\"
X.\" The author can be reached at: berliner@prisma.com
X.\"
X.de SP
X.if n .sp
X.if t .sp .5
X..
X.de hl
X.br
X.in +0.5i
X\l'\\n(LLu-1i'
X.in -0.5i
X.sp
X..
X.OH ""
X.nr PS 11
X.nr PO 1.25i
X.pl -0.2i
X.TL
X.ps 14
X.ft B
X.nf
XCVS II:
XParallelizing Software Development
X.fi
X.ft
X.ps
X.AU
X.ps 12
X.ft I
XBrian Berliner
X.ft
X.ps
X.AI
X.ps 12
X.ft I
XPrisma, Inc.
X5465 Mark Dabling Blvd.
XColorado Springs, CO 80918
Xberliner@prisma.com
X.ft
X.ps
X.AB
XThe program described in this paper fills a need in the UNIX
Xcommunity for a freely available tool to manage software revision and
Xrelease control in a multi-developer, multi-directory, multi-group
Xenvironment.
XThis tool also addresses the increasing need for tracking third-party vendor
Xsource distributions while trying to maintain local modifications to
Xearlier releases.
X.AE
X.NH
XBackground
X.PP
XIn large software development projects, it is usually necessary for more
Xthan one software developer to be modifying (usually different) modules of the
Xcode at the same time.
XSome of these code modifications are done in an
Xexperimental sense, at least until the code functions correctly, and some
Xtesting of the entire program is usually necessary.
XThen, the modifications are returned to a master source repository
Xso that others in the project can
Xenjoy the new bug-fix or functionality.
XIn order to manage such a project, some sort of revision control system is
Xnecessary.
X.PP
XSpecifically, UNIX\**
X.FS
XUNIX is a registered trademark of AT&T.
X.FE
Xkernel development is an excellent example of the
Xproblems that an adequate revision control system must address.
XThe SunOS\**
X.FS
XSunOS is a trademark of Sun Microsystems, Inc.
X.FE
Xkernel is composed of over a thousand files spread across a
Xhierarchy of dozens of directories.\**
X.FS
XYes, the SunOS 4.0 kernel is composed of over a \fIthousand\fP files!
X.FE
XPieces of the kernel must be edited
Xby many software developers within an organization.
XWhile undesirable in
Xtheory, it is not uncommon to have two or more people making
Xmodifications to the same file within the kernel sources in
Xorder to facilitate a desired change.
XExisting revision control systems like
X.SM
XRCS
X.LG
X[Tichy] or
X.SM
XSCCS
X.LG
X[Bell] serialize file modifications by
Xallowing only one developer to have a writable copy of a particular file at
Xany one point in time.
XThat developer is said to
Xhave \*Qlocked\*U the file for his exclusive use, and no other developer is
Xallowed to check out a writable copy of the file until the locking
Xdeveloper has finished impeding others' productivity.
XDevelopment pressures of productivity and deadlines
Xoften force organizations to require that multiple developers be able to
Xsimultaneously edit
Xcopies of the same revision controlled file.
X.PP
XThe necessity for multiple developers to modify the same file concurrently
Xquestions the value of serialization-based policies in traditional revision
Xcontrol.
XThis paper discusses the approach that
XPrisma took in adapting a standard revision control system,
X.SM
XRCS\c
X.LG
X, along with an existing public-domain collection of shell scripts that sits
Xatop
X.SM
XRCS
X.LG
Xand provides the basic conflict-resolution algorithms.
XThe resulting
Xprogram, \fBcvs\fP, addresses not only the issue of conflict-resolution in
Xa multi-developer open-editing environment, but also the issues of
Xsoftware release control and vendor source support and integration.
X.NH
XThe CVS Program
X.PP
X\fBcvs\fP
X(Concurrent Versions System)
Xis a front end to the
X.SM
XRCS
X.LG
Xrevision control system which extends
Xthe notion of revision control from a collection of files in a single
Xdirectory to a hierarchical collection of directories each containing
Xrevision controlled files.
XDirectories and files in the \fBcvs\fP system can be combined together in
Xmany ways to form a software release.
X\fBcvs\fP
Xprovides the functions necessary to manage these software releases and to
Xcontrol the concurrent editing of source files among multiple software
Xdevelopers.
X.PP
XThe six major features of \fBcvs\fP are listed below, and will be
Xdescribed in more detail in the following sections:
X.RS
X.IP 1.
XConcurrent access and conflict-resolution algorithms to guarantee that
Xsource changes are not \*Qlost.\*U
X.IP 2.
XSupport for tracking third-party vendor source distributions while
Xmaintaining the local modifications made to those sources.
X.IP 3.
XA flexible module database that provides a symbolic mapping of names to
Xcomponents of a larger software distribution.
XThis symbolic mapping provides for location independence within the software
Xrelease and, for example, allows one to check out a copy of the \*Qdiff\*U
Xprogram without ever knowing that the sources to \*Qdiff\*U actually reside
Xin the \*Qbin/diff\*U directory.
X.IP 4.
XConfigurable logging support allows all \*Qcommitted\*U source file changes
Xto be logged using an arbitrary program to save the log messages in a file,
Xnotesfile, or news database.
X.IP 5.
XA software release can be symbolically tagged and checked out at any time
Xbased on that tag.
XAn exact copy of a previous software release can be checked out at
Xany time, \fIregardless\fP of whether files or directories have been
Xadded/removed from the \*Qcurrent\*U software release.
XAs well,
Xa \*Qdate\*U can be used to check out the \fIexact\fP version of the software
Xrelease as of the specified date.
X.IP 6.
XA \*Qpatch\*U format file [Wall] can be produced between two software
Xreleases, even if the releases span multiple directories.
X.RE
X.PP
XThe sources maintained by \fBcvs\fP are kept within a single directory
Xhierarchy known as the \*Qsource repository.\*U
XThis \*Qsource repository\*U holds the actual
X.SM
XRCS
X.LG
X\*Q,v\*U files directly, as well as a special per-repository directory
X(\c
X.SM
XCVSROOT.adm\c
X.LG
X) which contains a small number of administrative files that describe the
Xrepository and how it can be accessed.
XSee Figure 1 for a picture of the \fBcvs\fP tree.
X.KF
X.hl
X.DS B
X.PS
Xline from 4.112,9.200 to 5.550,8.887
Xline from 5.447,8.884 to 5.550,8.887 to 5.458,8.933
Xline from 4.112,9.200 to 4.550,8.950
Xline from 4.451,8.978 to 4.550,8.950 to 4.476,9.021
Xline from 4.112,9.200 to 3.737,8.887
Xline from 3.798,8.971 to 3.737,8.887 to 3.830,8.932
Xline from 3.612,8.762 to 4.737,8.137
Xline from 4.638,8.164 to 4.737,8.137 to 4.662,8.208
Xline from 3.612,8.762 to 3.737,8.137
Xline from 3.693,8.231 to 3.737,8.137 to 3.742,8.240
Xline from 3.612,8.762 to 2.612,8.200
Xline from 2.687,8.271 to 2.612,8.200 to 2.712,8.227
Xline from 2.362,9.262 to 2.737,8.950
Xline from 2.645,8.995 to 2.737,8.950 to 2.677,9.033
Xline from 2.362,9.262 to 1.925,8.950
Xline from 1.992,9.028 to 1.925,8.950 to 2.021,8.988
Xline from 3.362,9.762 to 4.050,9.387
Xline from 3.950,9.413 to 4.050,9.387 to 3.974,9.457
Xline from 3.362,9.762 to 2.487,9.387
Xline from 2.570,9.450 to 2.487,9.387 to 2.589,9.404
X.ps 11
X"newfs.c,v" at 4.487,8.043 ljust
X.ps 11
X"mkfs.c,v" at 3.487,8.043 ljust
X.ps 11
X"Makefile,v" at 2.237,8.043 ljust
X.ps 11
X"newfs" at 3.487,8.793 ljust
X.ps 11
X"halt.c,v" at 5.487,8.793 ljust
X.ps 11
X"Makefile,v" at 4.237,8.793 ljust
X.ps 11
X"modules,v" at 2.487,8.793 ljust
X.ps 11
X"loginfo,v" at 1.488,8.793 ljust
X.ps 11
X"etc" at 3.987,9.293 ljust
X.ps 11
X"CVSROOT.adm" at 1.988,9.293 ljust
X.ps 11
X"/src/master" at 2.987,9.793 ljust
X.PE
X.DE
X.hl
X.ce 100
X.LG
X\fBFigure 1.\fP
X.SM
X\fBcvs\fP Source Repository
X.ce 0
X.sp
X.KE
X.NH 2
XSoftware Conflict Resolution\**
X.FS
XThe basic conflict-resolution algorithms
Xused in the \fBcvs\fP program find their roots
Xin the original work done by Dick Grune at Vrije Universiteit in Amsterdam
Xand posted to \fBcomp.sources.unix\fP in the volume 6 release sometime in 1986.
XThis original version of \fBcvs\fP was a collection of shell scripts that
Xcombined to form a front end to the
X.SM
XRCS
X.LG
Xprograms.
X.FE
X.PP
X\fBcvs\fP allows several software developers to edit personal copies of a
Xrevision controlled file concurrently.
XThe revision number of each checked out file is maintained independently
Xfor each user, and \fBcvs\fP forces the checked out file to be current with
Xthe \*Qhead\*U revision before it can be \*Qcommitted\*U as a permanent change.
XA checked out file is brought up-to-date with the \*Qhead\*U revision using
Xthe \*Qupdate\*U command of \fBcvs\fP.
XThis command compares the \*Qhead\*U revision number with that of the user's
Xfile and performs an
X.SM
XRCS
X.LG
Xmerge operation if they are not the same.
XThe result of the merge is a file that contains the user's modifications
Xand those modifications that were \*Qcommitted\*U after the user
Xchecked out his version of the file (as well as a backup copy of the
Xuser's original file).
X\fBcvs\fP points out any conflicts during the merge.
XIt is the user's responsibility to resolve these conflicts
Xand to \*Qcommit\*U his/her changes when ready.
X.PP
XAlthough the \fBcvs\fP conflict-resolution algorithm was defined in 1986,
Xit is remarkably similar to the \*QCopy-Modify-Merge\*U scenario included
Xwith NSE\**
X.FS
XNSE is the Network Software Environment, a product of Sun Microsystems, Inc.
X.FE
Xand described in [Honda] and [Courington].
XThe following explanation from [Honda] also applies to \fBcvs\fP:
X.QP
XSimply stated, a developer copies an object without locking it, modifies
Xthe copy, and then merges the modified copy with the original.
XThis paradigm allows developers to work in isolation from one another since
Xchanges are made to copies of objects.
XBecause locks are not used, development is not serialized and can proceed
Xin parallel.
XDevelopers, however, must merge objects after the changes have been made.
XIn particular, a developer must resolve conflicts when the same object has
Xbeen modified by someone else.
X.PP
XIn practice, Prisma has found that conflicts that occur when the same
Xobject has been modified by someone else are quite rare.
XWhen they do happen, the changes made by the other developer are usually
Xeasily resolved.
XThis practical use has shown that the \*QCopy-Modify-Merge\*U paradigm is a
Xcorrect and useful one.
X.NH 2
XTracking Third-Party Source Distributions
X.PP
XCurrently, a large amount of software is based on source
Xdistributions from a third-party distributor.
XIt is often the case that local modifications are to be made to this
Xdistribution, \fIand\fP that the vendor's future releases should be
Xtracked.
XRolling your local modifications forward into the new vendor release is a
Xtime-consuming task, but \fBcvs\fP can ease this burden somewhat.
XThe \fBcheckin\fP program of \fBcvs\fP initially sets up a source
Xrepository by integrating the source modules directly from the vendor's
Xrelease, preserving the directory hierarchy of the vendor's distribution.
XThe branch support of
X.SM
XRCS
X.LG
Xis used to build this vendor release as a branch of the main
X.SM
XRCS
X.LG
Xtrunk.
XFigure 2 shows how the \*Qhead\*U tracks a sample vendor
Xbranch when no local modifications have been made to the file.
X.KF
X.hl
X.DS B
X.PS
Xellipse at 3.237,6.763 wid 1.000 ht 0.500
Xdashwid = 0.050i
Xline dashed from 3.237,7.513 to 3.737,7.513 to 3.737,9.762 to 4.237,9.762
Xline from 4.138,9.737 to 4.237,9.762 to 4.138,9.787
Xline dashed from 2.237,8.262 to 3.237,8.262 to 3.237,7.013
Xline from 3.212,7.112 to 3.237,7.013 to 3.262,7.112
Xline from 3.737,6.763 to 4.237,6.763
Xline from 4.138,6.737 to 4.237,6.763 to 4.138,6.788
Xline from 2.237,6.763 to 2.737,6.763
Xline from 2.637,6.737 to 2.737,6.763 to 2.637,6.788
Xline from 1.738,6.013 to 1.738,6.513
Xline from 1.762,6.413 to 1.738,6.513 to 1.713,6.413
Xline from 1.238,7.013 to 2.237,7.013 to 2.237,6.513 to 1.238,6.513 to 1.238,7.013
Xline from 4.237,9.012 to 5.237,9.012 to 5.237,8.512 to 4.237,8.512 to 4.237,9.012
Xline from 4.237,8.012 to 5.237,8.012 to 5.237,7.513 to 4.237,7.513 to 4.237,8.012
Xline from 4.237,7.013 to 5.237,7.013 to 5.237,6.513 to 4.237,6.513 to 4.237,7.013
Xline from 4.737,7.013 to 4.737,7.513
Xline from 4.763,7.413 to 4.737,7.513 to 4.712,7.413
Xline from 4.737,8.012 to 4.737,8.512
Xline from 4.763,8.412 to 4.737,8.512 to 4.712,8.412
Xline from 4.237,10.012 to 5.237,10.012 to 5.237,9.512 to 4.237,9.512 to 4.237,10.012
Xline from 4.737,9.012 to 4.737,9.512
Xline from 4.763,9.412 to 4.737,9.512 to 4.712,9.412
Xline from 5.987,5.013 to 5.987,6.013 to 0.988,6.013 to 0.988,5.013 to 5.987,5.013
X.ps 11
X"\"HEAD\"" at 1.550,8.231 ljust
X.ps 11
X"'SunOS'" at 2.987,6.293 ljust
X.ps 11
X"1.1.1" at 3.050,6.793 ljust
X.ps 11
X"1.1" at 1.613,6.793 ljust
X.ps 11
X"1.1.1.1" at 4.487,6.793 ljust
X.ps 11
X"1.1.1.2" at 4.487,7.793 ljust
X.ps 11
X"1.1.1.3" at 4.487,8.793 ljust
X.ps 11
X"1.1.1.4" at 4.487,9.793 ljust
X.ps 11
X"'SunOS_4_0'" at 5.487,6.793 ljust
X.ps 11
X"'SunOS_4_0_1'" at 5.487,7.793 ljust
X.ps 11
X"'YAPT_5_5C'" at 5.487,8.793 ljust
X.ps 11
X"'SunOS_4_0_3'" at 5.487,9.793 ljust
X.ps 11
X"rcsfile.c,v" at 2.987,5.543 ljust
X.PE
X.DE
X.hl
X.ce 100
X.LG
X\fBFigure 2.\fP
X.SM
X\fBcvs\fP Vendor Branch Example
X.ce 0
X.sp .3
X.KE
XOnce this is done, developers can check out files and make local changes to
Xthe vendor's source distribution.
XThese local changes form a new branch to the tree which is then used as the
Xsource for future check outs.
XFigure 3 shows how the \*Qhead\*U moves to the main
X.SM
XRCS
X.LG
Xtrunk when a local modification is made.
X.KF
X.hl
X.DS B
X.PS
Xellipse at 3.237,6.763 wid 1.000 ht 0.500
Xdashwid = 0.050i
Xline dashed from 2.800,9.075 to 1.738,9.075 to 1.738,8.012
Xline from 1.713,8.112 to 1.738,8.012 to 1.762,8.112
Xline from 1.738,7.013 to 1.738,7.513
Xline from 1.762,7.413 to 1.738,7.513 to 1.713,7.413
Xline from 1.238,8.012 to 2.237,8.012 to 2.237,7.513 to 1.238,7.513 to 1.238,8.012
Xline from 3.737,6.763 to 4.237,6.763
Xline from 4.138,6.737 to 4.237,6.763 to 4.138,6.788
Xline from 2.237,6.763 to 2.737,6.763
Xline from 2.637,6.737 to 2.737,6.763 to 2.637,6.788
Xline from 1.738,6.013 to 1.738,6.513
Xline from 1.762,6.413 to 1.738,6.513 to 1.713,6.413
Xline from 1.238,7.013 to 2.237,7.013 to 2.237,6.513 to 1.238,6.513 to 1.238,7.013
Xline from 4.237,9.012 to 5.237,9.012 to 5.237,8.512 to 4.237,8.512 to 4.237,9.012
Xline from 4.237,8.012 to 5.237,8.012 to 5.237,7.513 to 4.237,7.513 to 4.237,8.012
Xline from 4.237,7.013 to 5.237,7.013 to 5.237,6.513 to 4.237,6.513 to 4.237,7.013
Xline from 4.737,7.013 to 4.737,7.513
Xline from 4.763,7.413 to 4.737,7.513 to 4.712,7.413
Xline from 4.737,8.012 to 4.737,8.512
Xline from 4.763,8.412 to 4.737,8.512 to 4.712,8.412
Xline from 4.237,10.012 to 5.237,10.012 to 5.237,9.512 to 4.237,9.512 to 4.237,10.012
Xline from 4.737,9.012 to 4.737,9.512
Xline from 4.763,9.412 to 4.737,9.512 to 4.712,9.412
Xline from 5.987,5.013 to 5.987,6.013 to 0.988,6.013 to 0.988,5.013 to 5.987,5.013
X.ps 11
X"1.2" at 1.613,7.793 ljust
X.ps 11
X"\"HEAD\"" at 2.862,9.043 ljust
X.ps 11
X"'SunOS'" at 2.987,6.293 ljust
X.ps 11
X"1.1.1" at 3.050,6.793 ljust
X.ps 11
X"1.1" at 1.613,6.793 ljust
X.ps 11
X"1.1.1.1" at 4.487,6.793 ljust
X.ps 11
X"1.1.1.2" at 4.487,7.793 ljust
X.ps 11
X"1.1.1.3" at 4.487,8.793 ljust
X.ps 11
X"1.1.1.4" at 4.487,9.793 ljust
X.ps 11
X"'SunOS_4_0'" at 5.487,6.793 ljust
X.ps 11
X"'SunOS_4_0_1'" at 5.487,7.793 ljust
X.ps 11
X"'YAPT_5_5C'" at 5.487,8.793 ljust
X.ps 11
X"'SunOS_4_0_3'" at 5.487,9.793 ljust
X.ps 11
X"rcsfile.c,v" at 2.987,5.543 ljust
X.PE
X.DE
X.hl
X.ce 100
X.LG
X\fBFigure 3.\fP
X.SM
X\fBcvs\fP Local Modification to Vendor Branch
X.ce 0
X.sp
X.KE
X.PP
XWhen a new version of the vendor's source distribution arrives, the
X\fBcheckin\fP program adds the new and changed vendor's files to the
Xalready existing source repository.
XFor files that have not been changed locally, the new file from the
Xvendor becomes the current \*Qhead\*U revision.
XFor files that have been modified locally, \fBcheckin\fP warns that the
Xfile must be merged with the new vendor release.
XThe \fBcvs\fP \*Qjoin\*U command is a useful tool that aids this process by
Xperforming the necessary
X.SM
XRCS
X.LG
Xmerge, as is done above when performing an \*Qupdate.\*U
X.PP
XThere is also limited support for \*Qdual\*U derivations for source files.
XSee Figure 4 for a sample dual-derived file.
X.KF
X.hl
X.DS B
X.PS
Xellipse at 2.337,8.575 wid 0.700 ht 0.375
Xellipse at 2.312,9.137 wid 0.700 ht 0.375
Xline from 1.225,9.012 to 1.225,9.363
Xline from 1.250,9.263 to 1.225,9.363 to 1.200,9.263
Xline from 0.875,9.725 to 1.600,9.725 to 1.600,9.363 to 0.875,9.363 to 0.875,9.725
Xline from 0.875,9.012 to 1.600,9.012 to 1.600,8.650 to 0.875,8.650 to 0.875,9.012
Xline from 4.050,10.200 to 4.775,10.200 to 4.775,9.850 to 4.050,9.850 to 4.050,10.200
Xline from 4.050,9.475 to 4.775,9.475 to 4.775,9.113 to 4.050,9.113 to 4.050,9.475
Xline from 4.050,8.762 to 4.775,8.762 to 4.775,8.400 to 4.050,8.400 to 4.050,8.762
Xline from 4.425,8.762 to 4.425,9.113
Xline from 4.450,9.013 to 4.425,9.113 to 4.400,9.013
Xline from 4.425,9.475 to 4.425,9.850
Xline from 4.450,9.750 to 4.425,9.850 to 4.400,9.750
Xline from 3.050,10.000 to 3.775,10.000 to 3.775,9.637 to 3.050,9.637 to 3.050,10.000
Xline from 3.050,9.312 to 3.775,9.312 to 3.775,8.950 to 3.050,8.950 to 3.050,9.312
Xline from 0.713,7.325 to 0.713,8.075 to 4.925,8.075 to 4.925,7.325 to 0.713,7.325
Xline from 1.238,8.075 to 1.238,8.637
Xline from 1.262,8.537 to 1.238,8.637 to 1.213,8.537
Xline from 1.613,8.825 to 1.975,8.575
Xline from 1.878,8.611 to 1.975,8.575 to 1.907,8.652
Xline from 2.675,8.575 to 4.050,8.575
Xline from 3.950,8.550 to 4.050,8.575 to 3.950,8.600
Xline from 2.675,9.137 to 3.050,9.137
Xline from 2.950,9.112 to 3.050,9.137 to 2.950,9.162
Xline from 3.425,9.325 to 3.425,9.637
Xline from 3.450,9.537 to 3.425,9.637 to 3.400,9.537
Xline from 1.613,8.825 to 1.925,9.137
Xline from 1.872,9.049 to 1.925,9.137 to 1.837,9.084
X.ps 11
X"'BSD'" at 2.138,9.481 ljust
X.ps 11
X"1.2" at 1.113,9.543 ljust
X.ps 11
X"1.1" at 1.125,8.831 ljust
X.ps 11
X"1.1.1.1" at 4.175,8.543 ljust
X.ps 11
X"1.1.1.2" at 4.175,9.281 ljust
X.ps 11
X"1.1.1.3" at 4.175,9.993 ljust
X.ps 11
X"1.1.2.2" at 3.175,9.793 ljust
X.ps 11
X"1.1.2.1" at 3.175,9.106 ljust
X.ps 11
X"rcsfile.c,v" at 2.425,7.706 ljust
X.ps 11
X"1.1.1" at 2.175,8.568 ljust
X.ps 11
X"'SunOS'" at 2.125,8.243 ljust
X.ps 11
X"1.1.2" at 2.163,9.131 ljust
X.PE
X.DE
X.hl
X.ce 100
X.LG
X\fBFigure 4.\fP
X.SM
X\fBcvs\fP Support For \*QDual\*U Derivations
X.ce 0
X.sp
X.KE
XThis example tracks the SunOS distribution but includes major changes from
XBerkeley.
XThese BSD files are saved directly in the
X.SM
XRCS
X.LG
Xfile off a new branch.
X.NH 2
XLocation Independent Module Database
X.PP
X\fBcvs\fP contains support for a simple, yet powerful, \*Qmodule\*U database.
XFor reasons of efficiency, this database is stored in \fBndbm\fP\|(3) format.
XThe module database is used to apply names to collections of directories
Xand files as a matter of convenience for checking out pieces of a large
Xsoftware distribution.
XThe database records the physical location of the sources as a form of
Xinformation hiding, allowing one to check out whole directory hierarchies
Xor individual files without regard for their actual location within the
Xglobal source distribution.
X.PP
XConsider the following small sample of a module database, which must be
Xtailored manually to each specific source repository environment:
X.DS
X\f(CW #key [-option argument] directory [files...]
X diff bin/diff
X libc lib/libc
X sys -o sys/tools/make_links sys
X modules -i mkmodules CVSROOT.adm modules
X kernel -a sys lang/adb
X ps bin Makefile ps.c\fP
X.DE
X.PP
XThe \*Qdiff\*U and \*Qlibc\*U modules refer to whole directory hierarchies that
Xare extracted on check out.
XThe \*Qsys\*U module extracts the \*Qsys\*U hierarchy, and runs the
X\*Qmake_links\*U program at the end of the check out process (the \fI-o\fP
Xoption specifies a program to run on check\fIo\fPut).
XThe \*Qmodules\*U module allows one to edit the module database file and
Xruns the \*Qmkmodules\*U program on check\fIi\fPn to regenerate the
X\fBndbm\fP database that \fBcvs\fP uses.
XThe \*Qkernel\*U module is an alias (as the \fI-a\fP option specifies)
Xwhich causes the remaining arguments after the \fI-a\fP to be interpreted
Xexactly as if they had been specified on the command line.
XThis is useful for objects that require shared pieces of code from far away
Xplaces to be compiled (as is the case with the kernel debugger, \fBkadb\fP,
Xwhich shares code with the standard \fBadb\fP debugger).
XThe \*Qps\*U module shows that the source for \*Qps\*U lives in the \*Qbin\*U
Xdirectory, but only \fIMakefile\fP and \fIps.c\fP are required to build the
Xobject.
X.PP
XThe module database at Prisma is now populated for the entire UNIX
Xdistribution and thereby allows us to issue the
Xfollowing convenient commands to check out components of the UNIX
Xdistribution without regard for their actual location within the master source
Xrepository:
X.DS
X\f(CW example% cvs checkout diff
X example% cvs checkout libc ps
X example% cd diff; make\fP
X.DE
X.PP
XIn building the module database file, it is quite possible to have name
Xconflicts within a global software distribution.
XFor example, SunOS provides two \fBcat\fP programs:
Xone for the standard environment, \fI/bin/cat\fP, and one for the System V
Xenvironment, \fI/usr/5bin/cat\fP.
XWe resolved this conflict by naming the standard \fBcat\fP module
X\*Qcat\*U, and the System V \fBcat\fP module \*Q5cat\*U.
XSimilar name modifications must be applied to other conflicting names, as
Xmight be found between a utility program and a library function, though
XPrisma chose not to include individual library functions within the module
Xdatabase at this time.
X.NH 2
XConfigurable Logging Support
X.PP
XThe \fBcvs\fP \*Qcommit\*U command is used to make a permanent change to the
Xmaster source repository (where the
X.SM
XRCS
X.LG
X\*Q,v\*U files live).
XWhenever a \*Qcommit\*U is done, the log message for the change is carefully
Xlogged by an arbitrary program (in a file, notesfile, news database, or
Xmail).
XFor example, a collection of these updates can be used to produce release
Xnotices.
X\fBcvs\fP can be configured to send log updates through one or more filter
Xprograms, based on a regular expression match on the directory that is
Xbeing changed.
XThis allows multiple related or unrelated projects to exist within a single
X\fBcvs\fP source repository tree, with each different project sending its
X\*Qcommit\*U reports to a unique log device.
X.PP
XA sample logging configuration file might look as follows:
X.DS
X\f(CW #regex filter-program
X DEFAULT /usr/local/bin/nfpipe -t %s utils.updates
X ^diag /usr/local/bin/nfpipe -t %s diag.updates
X ^local /usr/local/bin/nfpipe -t %s local.updates
X ^perf /usr/local/bin/nfpipe -t %s perf.updates
X ^sys /usr/local/bin/nfpipe -t %s kernel.updates\fP
X.DE
X.PP
XThis sample allows the diagnostics and performance groups to
Xshare the same source repository with the kernel and utilities groups.
XChanges that they make are sent directly to their own notesfile [Essick]
Xthrough the \*Qnfpipe\*U program.
XA sufficiently simple title is substituted for the \*Q%s\*U argument before
Xthe filter program is executed.
XThis logging configuration file is tailored manually to each specific
Xsource repository environment.
X.NH 2
XTagged Releases and Dates
X.PP
XAny release can be given a symbolic tag name that is stored directly in the
X.SM
XRCS
X.LG
Xfiles.
XThis tag can be used at any time to get an exact copy of any previous
Xrelease.
XWith equal ease, one can also extract an exact copy of the source files as
Xof any arbitrary date in the past as well.
XThus, all that's required to tag the current kernel, and to tag the kernel
Xas of the Fourth of July is:
X.DS
X\f(CW example% cvs tag TEST_KERNEL kernel
X example% cvs tag -D 'July 4' PATRIOTIC_KERNEL kernel\fP
X.DE
XThe following command would retrieve an exact copy of the test kernel at
Xsome later date:
X.DS
X\f(CW example% cvs checkout -fp -rTEST_KERNEL kernel\fP
X.DE
XThe \fI-f\fP option causes only files that match the specified tag to be
Xextracted, while the \fI-p\fP option automatically prunes empty directories.
XConsequently, directories added to the kernel after the test kernel was
Xtagged are not included in the newly extracted copy of the test kernel.
X.PP
XThe \fBcvs\fP date support has exactly the same interface as that provided
Xwith
X.SM
XRCS\c
X.LG
X, however \fBcvs\fP must process the \*Q,v\*U files directly due to the
Xspecial handling required by the vendor branch support.
XThe standard
X.SM
XRCS
X.LG
Xdate handling only processes one branch (or the main trunk) when checking
Xout based on a date specification.
X\fBcvs\fP must instead process the current \*Qhead\*U branch and, if a
Xmatch is not found, proceed to look for a match on the vendor branch.
XThis, combined with reasons of performance, is why \fBcvs\fP processes
Xrevision (symbolic and numeric) and date specifications directly from the
X\*Q,v\*U files.
X.NH 2
XBuilding \*Qpatch\*U Source Distributions
X.PP
X\fBcvs\fP can produce a \*Qpatch\*U format [Wall] output file which can be
Xused to bring a previously released software distribution current with the
Xnewest release.
XThis patch file supports an entire directory hierarchy within a single
Xpatch, as well as being able to add whole new files to the previous
Xrelease.
XOne can combine symbolic revisions and dates together to display changes in
Xa very generic way:
X.DS
X\f(CW example% cvs patch -D 'December 1, 1988' \e
X -D 'January 1, 1989' sys\fP
X.DE
XThis example displays the kernel changes made in the month of December,
X1988.
XTo release a patch file, for example, to take the \fBcvs\fP distribution
Xfrom version 1.0 to version 1.4 might be done as follows:
X.DS
X\f(CW example% cvs patch -rCVS_1_0 -rCVS_1_4 cvs\fP
X.DE
X.NH
XCVS Experience
X.NH 2
XStatistics
X.PP
XA quick summary of the scale that \fBcvs\fP is addressing today
Xcan be found in Table 1.
X.KF
X.TS
Xbox center tab(:);
Xc s
Xc s
Xc | c
Xl | n .
X\fB\s+2Revision Control Statistics at Prisma
Xas of 11/11/89\fP\s-2
X_
XHow Many...:Total
X=
XFiles:17243
XDirectories:1005
XLines of code:3927255
XRemoved files:131
XSoftware developers:14
XSoftware groups:6
XMegabytes of source:128
X.TE
X.ce 100
X.LG
X\fBTable 1.\fP
X.SM
X\fBcvs\fP Statistics
X.ce 0
X.sp .3
X.KE
XTable 2 shows the history of files changed or added and the number
Xof source lines affected by the change at Prisma.
XOnly changes made to the kernel sources are included.
X.KF
X.TS
Xbox center tab(:);
Xc s s s s
Xc s s s s
Xc || c | c || c | c
Xc || c | c || c | c
Xl || n | n || n | n.
X\fB\s+2Prisma Kernel Source File Changes
XBy Month, 1988-1989\fP\s-2
X_
XMonth:# Changed:# Lines:# Added:# Lines
X\^:Files:Changed:Files:Added
X=
XDec:87:3619:68:9266
XJan:39:4324:0:0
XFeb:73:1578:5:3550
XMar:99:5301:18:11461
XApr:112:7333:11:5759
XMay:138:5371:17:13986
XJun:65:2261:27:12875
XJul:34:2000:1:58
XAug:65:6378:8:4724
XSep:266:23410:113:39965
XOct:22:621:1:155
XTotal:1000:62196:269:101799
X.TE
X.ce 100
X.LG
X\fBTable 2.\fP
X.SM
X\fBcvs\fP Usage History for the Kernel
X.ce 0
X.sp
X.KE
XThe large number of source file changes made in September are the result of
Xmerging the SunOS 4.0.3 sources into the kernel.
XThis merge process is described in section 3.3.
X.NH 2
XPerformance
X.PP
XThe performance of \fBcvs\fP is currently quite reasonable.
XLittle effort has been expended on tuning \fBcvs\fP, although performance
Xrelated decisions were made during the \fBcvs\fP design.
XFor example, \fBcvs\fP parses the
X.SM
XRCS
X.LG
X\*Q,v\*U files directly instead of running an
X.SM
XRCS
X.LG
Xprocess.
XThis includes following branches as well as integrating with the vendor
Xsource branches and the main trunk when checking out files based on a date.
X.PP
XChecking out the entire kernel source tree (1223 files/59 directories)
Xcurrently takes 16 wall clock minutes on a Sun-4/280.
XHowever, bringing the tree up-to-date with the current kernel sources, once
Xit has been checked out, takes only 1.5 wall clock minutes.
XUpdating the \fIcomplete\fP 128 MByte source tree under \fBcvs\fP control
X(17243 files/1005 directories) takes roughly 28 wall clock minutes and
Xutilizes one-third of the machine.
XFor now this is entirely acceptable; improvements on these numbers will
Xpossibly be made in the future.
X.NH 2
XThe SunOS 4.0.3 Merge
X.PP
XThe true test of the \fBcvs\fP vendor branch support came with the arrival
Xof the SunOS 4.0.3 source upgrade tape.
XAs described above, the \fBcheckin\fP program was used to install the new
Xsources and the resulting output file listed the files that had been
Xlocally modified, needing to be merged manually.
XFor the kernel, there were 94 files in conflict.
XThe \fBcvs\fP \*Qjoin\*U command was used on each of the 94 conflicting
Xfiles, and the remaining conflicts were resolved.
X.PP
XThe \*Qjoin\*U command performs an \fBrcsmerge\fP operation.
XThis in turn uses \fI/usr/lib/diff3\fP to produce a three-way diff file.
XAs it happens, the \fBdiff3\fP program has a hard-coded limit of 200
Xsource-file changes maximum.
XThis proved to be too small for a few of the kernel files that needed
Xmerging by hand, due to the large number of local changes that Prisma had
Xmade.
XThe \fBdiff3\fP problem was solved by increasing the hard-coded limit by an
Xorder of magnitude.
X.PP
XThe SunOS 4.0.3 kernel source upgrade distribution contained
X346 files, 233 of which were modifications to previously released files,
Xand 113 of which were newly added files.
X\fBcheckin\fP added the 113 new files to the source repository
Xwithout intervention.
XOf the 233 modified files, 139 dropped in cleanly by \fBcheckin\fP, since
XPrisma had not made any local changes to them, and 94 required manual
Xmerging due to local modifications.
XThe 233 modified files consisted of 20,766 lines of differences.
XIt took one developer two days to manually merge the 94 files using the
X\*Qjoin\*U command and resolving conflicts manually.
XAn additional day was required for kernel debugging.
XThe entire process of merging over 20,000 lines of differences was
Xcompleted in less than a week.
XThis one time-savings alone was justification enough for the \fBcvs\fP
Xdevelopment effort; we expect to gain even more when tracking future SunOS
Xreleases.
X.NH
XFuture Enhancements and Current Bugs
X.PP
XSince \fBcvs\fP was designed to be incomplete, for reasons of design
Xsimplicity, there are naturally a good
Xnumber of enhancements that can be made to make it more useful.
XAs well, some nuisances exist in the current implementation.
X.RS
X.IP \(bu 3
X\fBcvs\fP does not currently \*Qremember\*U who has a checked out a copy of a
Xmodule.
XAs a result, it is impossible to know who might be working on the same
Xmodule that you are.
XA simple-minded database that is updated nightly would likely suffice.
X.IP \(bu 3
XSignal processing, keyboard interrupt handling in particular, is currently
Xsomewhat weak.
XThis is due to the heavy use of the \fBsystem\fP\|(3) library
Xfunction to execute
X.SM
XRCS
X.LG
Xprograms like \fBco\fP and \fBci\fP.
XIt sometimes takes multiple interrupts to make \fBcvs\fP quit.
XThis can be fixed by using a home-grown \fBsystem\fP\|() replacement.
X.IP \(bu 3
XSecurity of the source repository is currently not dealt with directly.
XThe usual UNIX approach of user-group-other security permissions through
Xthe file system is utilized, but nothing else.
X\fBcvs\fP could likely be a set-group-id executable that checks a
Xprotected database to verify user access permissions for particular objects
Xbefore allowing any operations to affect those objects.
X.IP \(bu 3
XWith every checked-out directory, \fBcvs\fP maintains some administrative
Xfiles that record the current revision numbers of the checked-out files as
Xwell as the location of the respective source repository.
X\fBcvs\fP does not recover nicely at all if these administrative files are
Xremoved.
X.IP \(bu 3
XThe source code for \fBcvs\fP has been tested extensively on Sun-3 and
XSun-4 systems, all running SunOS 4.0 or later versions of the operating
Xsystem.
XSince the code has not yet been compiled under other platforms, the overall
Xportability of the code is still questionable.
X.IP \(bu 3
XAs witnessed in the previous section, the \fBcvs\fP method for tracking
Xthird party vendor source distributions can work quite nicely.
XHowever, if the vendor changes the directory structure or the file names
Xwithin the source distribution, \fBcvs\fP has no way of matching the old
Xrelease with the new one.
XIt is currently unclear as to how to solve this, though it is certain to
Xhappen in practice.
X.RE
X.NH
XAvailability
X.PP
XThe \fBcvs\fP program sources can be found in a recent posting to the
X\fBcomp.sources.unix\fP newsgroup.
XIt is also currently available via anonymous ftp from \*Qprisma.com\*U.
XCopying rights for \fBcvs\fP will be covered by the GNU General Public
XLicense.
X.NH
XSummary
X.PP
XPrisma has used \fBcvs\fP since December, 1988.
XIt has evolved to meet our specific needs of revision and release control.
XWe will make our code freely available so that others can
Xbenefit from our work, and can enhance \fBcvs\fP to meet broader needs yet.
X.PP
XMany of the other software release and revision control systems, like the
Xone described in [Glew], appear to use a collection of tools that are
Xgeared toward specific environments \(em one set of tools for the kernel,
Xone set for \*Qgeneric\*U software, one set for utilities, and one set for
Xkernel and utilities.
XEach of these tool sets apparently handle some specific aspect of the
Xproblem uniquely.
X\fBcvs\fP took a somewhat different approach.
XFile sharing through symbolic or hard links is not addressed; instead, the
Xdisk space is simply burned since it is \*Qcheap.\*U
XSupport for producing objects for multiple architectures is not addressed;
Xinstead, a parallel checked-out source tree must be used for each
Xarchitecture, again wasting disk space to simplify complexity and ease of
Xuse \(em punting on this issue allowed \fIMakefile\fPs to remain
Xunchanged, unlike the approach taken in [Mahler], thereby maintaining closer
Xcompatibility with the third-party vendor sources.
X\fBcvs\fP is essentially a source-file server, making no assumptions or
Xspecial handling of the sources that it controls.
XTo \fBcvs\fP:
X.QP
XA source is a source, of course, of course, unless of course the source is
XMr. Ed.\**
X.FS
X\fBcvs\fP, of course, does not really discriminate against Mr. Ed.\**
X.FE
X.FS
XYet.
X.FE
X.LP
XSources are maintained, saved, and retrievable at any time based on
Xsymbolic or numeric revision or date in the past.
XIt is entirely up to \fBcvs\fP wrapper programs to provide for release
Xenvironments and such.
X.PP
XThe major advantage of \fBcvs\fP over the
Xmany other similar systems that have already been designed is the
Xsimplicity of \fBcvs\fP.
X\fBcvs\fP contains only three programs that do all the work of release
Xand revision control, and two manually-maintained administrative
Xfiles for each source repository.
XOf course, the deciding factor of any tool is whether people use it, and if
Xthey even \fIlike\fP to use it.
XAt Prisma, \fBcvs\fP prevented members of the kernel
Xgroup from killing each other.
X.NH
XAcknowledgements
X.PP
XMany thanks to Dick Grune at Vrije Universiteit in Amsterdam for his work
Xon the original version of \fBcvs\fP and for making it available to the
Xworld.
XThanks to Jeff Polk of Prisma for helping with the design of the module
Xdatabase, vendor branch support, and for writing the \fBcheckin\fP shell
Xscript.
XThanks also to the entire software group at Prisma for taking the
Xtime to review the paper and correct my grammar.
X.NH
XReferences
X.IP [Bell] 12
XBell Telephone Laboratories.
X\*QSource Code Control System User's Guide.\*U
X\fIUNIX System III Programmer's Manual\fP, October 1981.
X.IP [Courington] 12
XCourington, W.
X\fIThe Network Software Environment\fP,
XSun Technical Report FE197-0, Sun Microsystems Inc, February 1989.
X.IP [Essick] 12
XEssick, Raymond B. and Robert Bruce Kolstad.
X\fINotesfile Reference Manual\fP,
XDepartment of Computer Science Technical Report #1081,
XUniversity of Illinois at Urbana-Champaign, Urbana, Illinois,
X1982, p. 26.
X.IP [Glew] 12
XGlew, Andy.
X\*QBoxes, Links, and Parallel Trees:
XElements of a Configuration Management System.\*U
X\fIWorkshop Proceedings of the Software Management Conference\fP, USENIX,
XNew Orleans, April 1989.
X.IP [Grune] 12
XGrune, Dick.
XDistributed the original shell script version of \fBcvs\fP in the
X\fBcomp.sources.unix\fP volume 6 release in 1986.
X.IP [Honda] 12
XHonda, Masahiro and Terrence Miller.
X\*QSoftware Management Using a CASE Environment.\*U
X\fIWorkshop Proceedings of the Software Management Conference\fP, USENIX,
XNew Orleans, April 1989.
X.IP [Mahler] 12
XMahler, Alex and Andreas Lampen.
X\*QAn Integrated Toolset for Engineering Software Configurations.\*U
X\fIProceedings of the ACM SIGSOFT/SIGPLAN Software Engineering Symposium on
XPractical Software Development Environments\fP, ACM, Boston, November 1988.
XDescribed is the \fBshape\fP toolkit posted to the
X\fBcomp.sources.unix\fP newsgroup in the volume 19 release.
X.IP [Tichy] 12
XTichy, Walter F.
X\*QDesign, Implementation, and Evaluation of a Revision Control System.\*U
X\fIProceedings of the 6th International Conference on Software
XEngineering\fP, IEEE, Tokyo, September 1982.
X.IP [Wall] 12
XWall, Larry.
XThe \fBpatch\fP program is an indispensable tool for applying a diff file
Xto an original.
XCan be found on uunet.uu.net in ~ftp/pub/patch.tar.
END_OF_FILE
if test 37780 -ne `wc -c <'doc/cvs.ms'`; then
echo shar: \"'doc/cvs.ms'\" unpacked with wrong size!
fi
# end of 'doc/cvs.ms'
fi
echo shar: End of archive 6 \(of 7\).
cp /dev/null ark6isdone
MISSING=""
for I in 1 2 3 4 5 6 7 ; do
if test ! -f ark${I}isdone ; then
MISSING="${MISSING} ${I}"
fi
done
if test "${MISSING}" = "" ; then
echo You have unpacked all 7 archives.
rm -f ark[1-9]isdone
else
echo You still need to unpack the following archives:
echo " " ${MISSING}
fi
## End of shell archive.
exit 0
exit 0 # Just in case...
--
Please send comp.sources.unix-related mail to rsalz@uunet.uu.net.
Use a domain-based address or give alternate paths, or you may lose out.