sync with .orig.tar.gz after removing all CLEANFILES
[alioth/cvs.git] / doc / cvs-paper.ms
1 .\" soelim cvs.ms | pic | tbl | troff -ms
2 .\" @(#)cvs.ms 1.2 92/01/30
3 .\"
4 .\"     troff source to the cvs USENIX article, Winter 1990, Washington, D.C.
5 .\"     Copyright (c) 1989, Brian Berliner
6 .\"
7 .\"     This program is free software; you can redistribute it and/or modify
8 .\"     it under the terms of the GNU General Public License as published by
9 .\"     the Free Software Foundation; either version 1, or (at your option)
10 .\"     any later version.
11 .\"
12 .\"     This program is distributed in the hope that it will be useful,
13 .\"     but WITHOUT ANY WARRANTY; without even the implied warranty of
14 .\"     MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
15 .\"     GNU General Public License for more details.
16 .\"
17 .\"     The author can be reached at:  berliner@prisma.com
18 .\"
19 .de SP
20 .if n .sp
21 .if t .sp .5
22 ..
23 .de hl
24 .br
25 .in +0.5i
26 \l'\\n(LLu-1i'
27 .in -0.5i
28 .sp
29 ..
30 .OH ""
31 .nr PS 11
32 .nr PO 1.25i
33 .pl -0.2i
34 .TL
35 .ps 14
36 .ft B
37 .nf
38 CVS II:
39 Parallelizing Software Development
40 .fi
41 .ft
42 .ps
43 .AU
44 .ps 12
45 .ft I
46 Brian Berliner
47 .ft
48 .ps
49 .AI
50 .ps 12
51 .ft I
52 Prisma, Inc.
53 5465 Mark Dabling Blvd.
54 Colorado Springs, CO  80918
55 berliner@prisma.com
56 .ft
57 .ps
58 .AB
59 The program described in this paper fills a need in the UNIX
60 community for a freely available tool to manage software revision and
61 release control in a multi-developer, multi-directory, multi-group
62 environment.
63 This tool also addresses the increasing need for tracking third-party vendor
64 source distributions while trying to maintain local modifications to
65 earlier releases.
66 .AE
67 .NH
68 Background
69 .PP
70 In large software development projects, it is usually necessary for more
71 than one software developer to be modifying (usually different) modules of the
72 code at the same time.
73 Some of these code modifications are done in an
74 experimental sense, at least until the code functions correctly, and some
75 testing of the entire program is usually necessary.
76 Then, the modifications are returned to a master source repository
77 so that others in the project can
78 enjoy the new bug-fix or functionality.
79 In order to manage such a project, some sort of revision control system is
80 necessary.
81 .PP
82 Specifically, UNIX\**
83 .FS
84 UNIX is a registered trademark of AT&T.
85 .FE
86 kernel development is an excellent example of the
87 problems that an adequate revision control system must address.
88 The SunOS\**
89 .FS
90 SunOS is a trademark of Sun Microsystems, Inc.
91 .FE
92 kernel is composed of over a thousand files spread across a
93 hierarchy of dozens of directories.\**
94 .FS
95 Yes, the SunOS 4.0 kernel is composed of over a \fIthousand\fP files!
96 .FE
97 Pieces of the kernel must be edited
98 by many software developers within an organization.
99 While undesirable in
100 theory, it is not uncommon to have two or more people making
101 modifications to the same file within the kernel sources in
102 order to facilitate a desired change.
103 Existing revision control systems like
104 .SM
105 RCS
106 .LG
107 [Tichy] or
108 .SM
109 SCCS
110 .LG
111 [Bell] serialize file modifications by
112 allowing only one developer to have a writable copy of a particular file at
113 any one point in time.
114 That developer is said to
115 have \*Qlocked\*U the file for his exclusive use, and no other developer is
116 allowed to check out a writable copy of the file until the locking
117 developer has finished impeding others' productivity.
118 Development pressures of productivity and deadlines
119 often force organizations to require that multiple developers be able to
120 simultaneously edit
121 copies of the same revision controlled file.
122 .PP
123 The necessity for multiple developers to modify the same file concurrently
124 questions the value of serialization-based policies in traditional revision
125 control.
126 This paper discusses the approach that
127 Prisma took in adapting a standard revision control system,
128 .SM
129 RCS\c
130 .LG
131 , along with an existing public-domain collection of shell scripts that sits
132 atop
133 .SM
134 RCS
135 .LG
136 and provides the basic conflict-resolution algorithms.
137 The resulting
138 program, \fBcvs\fP, addresses not only the issue of conflict-resolution in
139 a multi-developer open-editing environment, but also the issues of
140 software release control and vendor source support and integration.
141 .NH
142 The CVS Program
143 .PP
144 \fBcvs\fP
145 (Concurrent Versions System)
146 is a front end to the
147 .SM
148 RCS
149 .LG
150 revision control system which extends
151 the notion of revision control from a collection of files in a single
152 directory to a hierarchical collection of directories each containing
153 revision controlled files.
154 Directories and files in the \fBcvs\fP system can be combined together in
155 many ways to form a software release.
156 \fBcvs\fP
157 provides the functions necessary to manage these software releases and to
158 control the concurrent editing of source files among multiple software
159 developers.
160 .PP
161 The six major features of \fBcvs\fP are listed below, and will be
162 described in more detail in the following sections:
163 .RS
164 .IP 1.
165 Concurrent access and conflict-resolution algorithms to guarantee that
166 source changes are not \*Qlost.\*U
167 .IP 2.
168 Support for tracking third-party vendor source distributions while
169 maintaining the local modifications made to those sources.
170 .IP 3.
171 A flexible module database that provides a symbolic mapping of names to
172 components of a larger software distribution.
173 This symbolic mapping provides for location independence within the software
174 release and, for example, allows one to check out a copy of the \*Qdiff\*U
175 program without ever knowing that the sources to \*Qdiff\*U actually reside
176 in the \*Qbin/diff\*U directory.
177 .IP 4.
178 Configurable logging support allows all \*Qcommitted\*U source file changes
179 to be logged using an arbitrary program to save the log messages in a file,
180 notesfile, or news database.
181 .IP 5.
182 A software release can be symbolically tagged and checked out at any time
183 based on that tag.
184 An exact copy of a previous software release can be checked out at
185 any time, \fIregardless\fP of whether files or directories have been
186 added/removed from the \*Qcurrent\*U software release.
187 As well,
188 a \*Qdate\*U can be used to check out the \fIexact\fP version of the software
189 release as of the specified date.
190 .IP 6.
191 A \*Qpatch\*U format file [Wall] can be produced between two software
192 releases, even if the releases span multiple directories.
193 .RE
194 .PP
195 The sources maintained by \fBcvs\fP are kept within a single directory
196 hierarchy known as the \*Qsource repository.\*U
197 This \*Qsource repository\*U holds the actual
198 .SM
199 RCS
200 .LG
201 \*Q,v\*U files directly, as well as a special per-repository directory
202 (\c
203 .SM
204 CVSROOT.adm\c
205 .LG
206 ) which contains a small number of administrative files that describe the
207 repository and how it can be accessed.
208 See Figure 1 for a picture of the \fBcvs\fP tree.
209 .KF
210 .hl
211 .DS B
212 .PS
213 line from 4.112,9.200 to 5.550,8.887
214 line from 5.447,8.884 to 5.550,8.887 to 5.458,8.933
215 line from 4.112,9.200 to 4.550,8.950
216 line from 4.451,8.978 to 4.550,8.950 to 4.476,9.021
217 line from 4.112,9.200 to 3.737,8.887
218 line from 3.798,8.971 to 3.737,8.887 to 3.830,8.932
219 line from 3.612,8.762 to 4.737,8.137
220 line from 4.638,8.164 to 4.737,8.137 to 4.662,8.208
221 line from 3.612,8.762 to 3.737,8.137
222 line from 3.693,8.231 to 3.737,8.137 to 3.742,8.240
223 line from 3.612,8.762 to 2.612,8.200
224 line from 2.687,8.271 to 2.612,8.200 to 2.712,8.227
225 line from 2.362,9.262 to 2.737,8.950
226 line from 2.645,8.995 to 2.737,8.950 to 2.677,9.033
227 line from 2.362,9.262 to 1.925,8.950
228 line from 1.992,9.028 to 1.925,8.950 to 2.021,8.988
229 line from 3.362,9.762 to 4.050,9.387
230 line from 3.950,9.413 to 4.050,9.387 to 3.974,9.457
231 line from 3.362,9.762 to 2.487,9.387
232 line from 2.570,9.450 to 2.487,9.387 to 2.589,9.404
233 .ps 11
234 "newfs.c,v" at 4.487,8.043 ljust
235 .ps 11
236 "mkfs.c,v" at 3.487,8.043 ljust
237 .ps 11
238 "Makefile,v" at 2.237,8.043 ljust
239 .ps 11
240 "newfs" at 3.487,8.793 ljust
241 .ps 11
242 "halt.c,v" at 5.487,8.793 ljust
243 .ps 11
244 "Makefile,v" at 4.237,8.793 ljust
245 .ps 11
246 "modules,v" at 2.487,8.793 ljust
247 .ps 11
248 "loginfo,v" at 1.488,8.793 ljust
249 .ps 11
250 "etc" at 3.987,9.293 ljust
251 .ps 11
252 "CVSROOT.adm" at 1.988,9.293 ljust
253 .ps 11
254 "/src/master" at 2.987,9.793 ljust
255 .PE
256 .DE
257 .hl
258 .ce 100
259 .LG
260 \fBFigure 1.\fP
261 .SM
262 \fBcvs\fP Source Repository
263 .ce 0
264 .sp
265 .KE
266 .NH 2
267 Software Conflict Resolution\**
268 .FS
269 The basic conflict-resolution algorithms
270 used in the \fBcvs\fP program find their roots
271 in the original work done by Dick Grune at Vrije Universiteit in Amsterdam
272 and posted to \fBcomp.sources.unix\fP in the volume 6 release sometime in 1986.
273 This original version of \fBcvs\fP was a collection of shell scripts that
274 combined to form a front end to the
275 .SM
276 RCS
277 .LG
278 programs.
279 .FE
280 .PP
281 \fBcvs\fP allows several software developers to edit personal copies of a
282 revision controlled file concurrently.
283 The revision number of each checked out file is maintained independently
284 for each user, and \fBcvs\fP forces the checked out file to be current with
285 the \*Qhead\*U revision before it can be \*Qcommitted\*U as a permanent change.
286 A checked out file is brought up-to-date with the \*Qhead\*U revision using
287 the \*Qupdate\*U command of \fBcvs\fP.
288 This command compares the \*Qhead\*U revision number with that of the user's
289 file and performs an
290 .SM
291 RCS
292 .LG
293 merge operation if they are not the same.
294 The result of the merge is a file that contains the user's modifications
295 and those modifications that were \*Qcommitted\*U after the user
296 checked out his version of the file (as well as a backup copy of the
297 user's original file).
298 \fBcvs\fP points out any conflicts during the merge.
299 It is the user's responsibility to resolve these conflicts
300 and to \*Qcommit\*U his/her changes when ready.
301 .PP
302 Although the \fBcvs\fP conflict-resolution algorithm was defined in 1986,
303 it is remarkably similar to the \*QCopy-Modify-Merge\*U scenario included
304 with NSE\**
305 .FS
306 NSE is the Network Software Environment, a product of Sun Microsystems, Inc.
307 .FE
308 and described in [Honda] and [Courington].
309 The following explanation from [Honda] also applies to \fBcvs\fP:
310 .QP
311 Simply stated, a developer copies an object without locking it, modifies
312 the copy, and then merges the modified copy with the original.
313 This paradigm allows developers to work in isolation from one another since
314 changes are made to copies of objects.
315 Because locks are not used, development is not serialized and can proceed
316 in parallel.
317 Developers, however, must merge objects after the changes have been made.
318 In particular, a developer must resolve conflicts when the same object has
319 been modified by someone else.
320 .PP
321 In practice, Prisma has found that conflicts that occur when the same
322 object has been modified by someone else are quite rare.
323 When they do happen, the changes made by the other developer are usually
324 easily resolved.
325 This practical use has shown that the \*QCopy-Modify-Merge\*U paradigm is a
326 correct and useful one.
327 .NH 2
328 Tracking Third-Party Source Distributions
329 .PP
330 Currently, a large amount of software is based on source
331 distributions from a third-party distributor.
332 It is often the case that local modifications are to be made to this
333 distribution, \fIand\fP that the vendor's future releases should be
334 tracked.
335 Rolling your local modifications forward into the new vendor release is a
336 time-consuming task, but \fBcvs\fP can ease this burden somewhat.
337 The \fBcheckin\fP program of \fBcvs\fP initially sets up a source
338 repository by integrating the source modules directly from the vendor's
339 release, preserving the directory hierarchy of the vendor's distribution.
340 The branch support of
341 .SM
342 RCS
343 .LG
344 is used to build this vendor release as a branch of the main
345 .SM
346 RCS
347 .LG
348 trunk.
349 Figure 2 shows how the \*Qhead\*U tracks a sample vendor
350 branch when no local modifications have been made to the file.
351 .KF
352 .hl
353 .DS B
354 .PS
355 ellipse at 3.237,6.763 wid 1.000 ht 0.500
356 dashwid = 0.050i
357 line dashed from 3.237,7.513 to 3.737,7.513 to 3.737,9.762 to 4.237,9.762
358 line from 4.138,9.737 to 4.237,9.762 to 4.138,9.787
359 line dashed from 2.237,8.262 to 3.237,8.262 to 3.237,7.013
360 line from 3.212,7.112 to 3.237,7.013 to 3.262,7.112
361 line from 3.737,6.763 to 4.237,6.763
362 line from 4.138,6.737 to 4.237,6.763 to 4.138,6.788
363 line from 2.237,6.763 to 2.737,6.763
364 line from 2.637,6.737 to 2.737,6.763 to 2.637,6.788
365 line from 1.738,6.013 to 1.738,6.513
366 line from 1.762,6.413 to 1.738,6.513 to 1.713,6.413
367 line 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
368 line 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
369 line 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
370 line 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
371 line from 4.737,7.013 to 4.737,7.513
372 line from 4.763,7.413 to 4.737,7.513 to 4.712,7.413
373 line from 4.737,8.012 to 4.737,8.512
374 line from 4.763,8.412 to 4.737,8.512 to 4.712,8.412
375 line 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
376 line from 4.737,9.012 to 4.737,9.512
377 line from 4.763,9.412 to 4.737,9.512 to 4.712,9.412
378 line 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
379 .ps 11
380 "\"HEAD\"" at 1.550,8.231 ljust
381 .ps 11
382 "'SunOS'" at 2.987,6.293 ljust
383 .ps 11
384 "1.1.1" at 3.050,6.793 ljust
385 .ps 11
386 "1.1" at 1.613,6.793 ljust
387 .ps 11
388 "1.1.1.1" at 4.487,6.793 ljust
389 .ps 11
390 "1.1.1.2" at 4.487,7.793 ljust
391 .ps 11
392 "1.1.1.3" at 4.487,8.793 ljust
393 .ps 11
394 "1.1.1.4" at 4.487,9.793 ljust
395 .ps 11
396 "'SunOS_4_0'" at 5.487,6.793 ljust
397 .ps 11
398 "'SunOS_4_0_1'" at 5.487,7.793 ljust
399 .ps 11
400 "'YAPT_5_5C'" at 5.487,8.793 ljust
401 .ps 11
402 "'SunOS_4_0_3'" at 5.487,9.793 ljust
403 .ps 11
404 "rcsfile.c,v" at 2.987,5.543 ljust
405 .PE
406 .DE
407 .hl
408 .ce 100
409 .LG
410 \fBFigure 2.\fP
411 .SM
412 \fBcvs\fP Vendor Branch Example
413 .ce 0
414 .sp .3
415 .KE
416 Once this is done, developers can check out files and make local changes to
417 the vendor's source distribution.
418 These local changes form a new branch to the tree which is then used as the
419 source for future check outs.
420 Figure 3 shows how the \*Qhead\*U moves to the main
421 .SM
422 RCS
423 .LG
424 trunk when a local modification is made.
425 .KF
426 .hl
427 .DS B
428 .PS
429 ellipse at 3.237,6.763 wid 1.000 ht 0.500
430 dashwid = 0.050i
431 line dashed from 2.800,9.075 to 1.738,9.075 to 1.738,8.012
432 line from 1.713,8.112 to 1.738,8.012 to 1.762,8.112
433 line from 1.738,7.013 to 1.738,7.513
434 line from 1.762,7.413 to 1.738,7.513 to 1.713,7.413
435 line 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
436 line from 3.737,6.763 to 4.237,6.763
437 line from 4.138,6.737 to 4.237,6.763 to 4.138,6.788
438 line from 2.237,6.763 to 2.737,6.763
439 line from 2.637,6.737 to 2.737,6.763 to 2.637,6.788
440 line from 1.738,6.013 to 1.738,6.513
441 line from 1.762,6.413 to 1.738,6.513 to 1.713,6.413
442 line 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
443 line 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
444 line 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
445 line 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
446 line from 4.737,7.013 to 4.737,7.513
447 line from 4.763,7.413 to 4.737,7.513 to 4.712,7.413
448 line from 4.737,8.012 to 4.737,8.512
449 line from 4.763,8.412 to 4.737,8.512 to 4.712,8.412
450 line 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
451 line from 4.737,9.012 to 4.737,9.512
452 line from 4.763,9.412 to 4.737,9.512 to 4.712,9.412
453 line 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
454 .ps 11
455 "1.2" at 1.613,7.793 ljust
456 .ps 11
457 "\"HEAD\"" at 2.862,9.043 ljust
458 .ps 11
459 "'SunOS'" at 2.987,6.293 ljust
460 .ps 11
461 "1.1.1" at 3.050,6.793 ljust
462 .ps 11
463 "1.1" at 1.613,6.793 ljust
464 .ps 11
465 "1.1.1.1" at 4.487,6.793 ljust
466 .ps 11
467 "1.1.1.2" at 4.487,7.793 ljust
468 .ps 11
469 "1.1.1.3" at 4.487,8.793 ljust
470 .ps 11
471 "1.1.1.4" at 4.487,9.793 ljust
472 .ps 11
473 "'SunOS_4_0'" at 5.487,6.793 ljust
474 .ps 11
475 "'SunOS_4_0_1'" at 5.487,7.793 ljust
476 .ps 11
477 "'YAPT_5_5C'" at 5.487,8.793 ljust
478 .ps 11
479 "'SunOS_4_0_3'" at 5.487,9.793 ljust
480 .ps 11
481 "rcsfile.c,v" at 2.987,5.543 ljust
482 .PE
483 .DE
484 .hl
485 .ce 100
486 .LG
487 \fBFigure 3.\fP
488 .SM
489 \fBcvs\fP Local Modification to Vendor Branch
490 .ce 0
491 .sp
492 .KE
493 .PP
494 When a new version of the vendor's source distribution arrives, the
495 \fBcheckin\fP program adds the new and changed vendor's files to the
496 already existing source repository.
497 For files that have not been changed locally, the new file from the
498 vendor becomes the current \*Qhead\*U revision.
499 For files that have been modified locally, \fBcheckin\fP warns that the
500 file must be merged with the new vendor release.
501 The \fBcvs\fP \*Qjoin\*U command is a useful tool that aids this process by
502 performing the necessary
503 .SM
504 RCS
505 .LG
506 merge, as is done above when performing an \*Qupdate.\*U
507 .PP
508 There is also limited support for \*Qdual\*U derivations for source files.
509 See Figure 4 for a sample dual-derived file.
510 .KF
511 .hl
512 .DS B
513 .PS
514 ellipse at 2.337,8.575 wid 0.700 ht 0.375
515 ellipse at 2.312,9.137 wid 0.700 ht 0.375
516 line from 1.225,9.012 to 1.225,9.363
517 line from 1.250,9.263 to 1.225,9.363 to 1.200,9.263
518 line 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
519 line 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
520 line 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
521 line 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
522 line 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
523 line from 4.425,8.762 to 4.425,9.113
524 line from 4.450,9.013 to 4.425,9.113 to 4.400,9.013
525 line from 4.425,9.475 to 4.425,9.850
526 line from 4.450,9.750 to 4.425,9.850 to 4.400,9.750
527 line 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
528 line 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
529 line 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
530 line from 1.238,8.075 to 1.238,8.637
531 line from 1.262,8.537 to 1.238,8.637 to 1.213,8.537
532 line from 1.613,8.825 to 1.975,8.575
533 line from 1.878,8.611 to 1.975,8.575 to 1.907,8.652
534 line from 2.675,8.575 to 4.050,8.575
535 line from 3.950,8.550 to 4.050,8.575 to 3.950,8.600
536 line from 2.675,9.137 to 3.050,9.137
537 line from 2.950,9.112 to 3.050,9.137 to 2.950,9.162
538 line from 3.425,9.325 to 3.425,9.637
539 line from 3.450,9.537 to 3.425,9.637 to 3.400,9.537
540 line from 1.613,8.825 to 1.925,9.137
541 line from 1.872,9.049 to 1.925,9.137 to 1.837,9.084
542 .ps 11
543 "'BSD'" at 2.138,9.481 ljust
544 .ps 11
545 "1.2" at 1.113,9.543 ljust
546 .ps 11
547 "1.1" at 1.125,8.831 ljust
548 .ps 11
549 "1.1.1.1" at 4.175,8.543 ljust
550 .ps 11
551 "1.1.1.2" at 4.175,9.281 ljust
552 .ps 11
553 "1.1.1.3" at 4.175,9.993 ljust
554 .ps 11
555 "1.1.2.2" at 3.175,9.793 ljust
556 .ps 11
557 "1.1.2.1" at 3.175,9.106 ljust
558 .ps 11
559 "rcsfile.c,v" at 2.425,7.706 ljust
560 .ps 11
561 "1.1.1" at 2.175,8.568 ljust
562 .ps 11
563 "'SunOS'" at 2.125,8.243 ljust
564 .ps 11
565 "1.1.2" at 2.163,9.131 ljust
566 .PE
567 .DE
568 .hl
569 .ce 100
570 .LG
571 \fBFigure 4.\fP
572 .SM
573 \fBcvs\fP Support For \*QDual\*U Derivations
574 .ce 0
575 .sp
576 .KE
577 This example tracks the SunOS distribution but includes major changes from
578 Berkeley.
579 These BSD files are saved directly in the
580 .SM
581 RCS
582 .LG
583 file off a new branch.
584 .NH 2
585 Location Independent Module Database
586 .PP
587 \fBcvs\fP contains support for a simple, yet powerful, \*Qmodule\*U database.
588 For reasons of efficiency, this database is stored in \fBndbm\fP\|(3) format.
589 The module database is used to apply names to collections of directories
590 and files as a matter of convenience for checking out pieces of a large
591 software distribution.
592 The database records the physical location of the sources as a form of
593 information hiding, allowing one to check out whole directory hierarchies
594 or individual files without regard for their actual location within the
595 global source distribution.
596 .PP
597 Consider the following small sample of a module database, which must be
598 tailored manually to each specific source repository environment:
599 .DS
600 \f(CW           #key      [-option argument] directory [files...]
601                 diff      bin/diff
602                 libc      lib/libc
603                 sys       -o sys/tools/make_links sys
604                 modules   -i mkmodules CVSROOT.adm modules
605                 kernel    -a sys lang/adb
606                 ps        bin Makefile ps.c\fP
607 .DE
608 .PP
609 The \*Qdiff\*U and \*Qlibc\*U modules refer to whole directory hierarchies that
610 are extracted on check out.
611 The \*Qsys\*U module extracts the \*Qsys\*U hierarchy, and runs the
612 \*Qmake_links\*U program at the end of the check out process (the \fI-o\fP
613 option specifies a program to run on check\fIo\fPut).
614 The \*Qmodules\*U module allows one to edit the module database file and
615 runs the \*Qmkmodules\*U program on check\fIi\fPn to regenerate the
616 \fBndbm\fP database that \fBcvs\fP uses.
617 The \*Qkernel\*U module is an alias (as the \fI-a\fP option specifies)
618 which causes the remaining arguments after the \fI-a\fP to be interpreted
619 exactly as if they had been specified on the command line.
620 This is useful for objects that require shared pieces of code from far away
621 places to be compiled (as is the case with the kernel debugger, \fBkadb\fP,
622 which shares code with the standard \fBadb\fP debugger).
623 The \*Qps\*U module shows that the source for \*Qps\*U lives in the \*Qbin\*U
624 directory, but only \fIMakefile\fP and \fIps.c\fP are required to build the
625 object.
626 .PP
627 The module database at Prisma is now populated for the entire UNIX
628 distribution and thereby allows us to issue the
629 following convenient commands to check out components of the UNIX
630 distribution without regard for their actual location within the master source
631 repository:
632 .DS
633 \f(CW           example% cvs checkout diff
634                 example% cvs checkout libc ps
635                 example% cd diff; make\fP
636 .DE
637 .PP
638 In building the module database file, it is quite possible to have name
639 conflicts within a global software distribution.
640 For example, SunOS provides two \fBcat\fP programs:
641 one for the standard environment, \fI/bin/cat\fP, and one for the System V
642 environment, \fI/usr/5bin/cat\fP.
643 We resolved this conflict by naming the standard \fBcat\fP module
644 \*Qcat\*U, and the System V \fBcat\fP module \*Q5cat\*U.
645 Similar name modifications must be applied to other conflicting names, as
646 might be found between a utility program and a library function, though
647 Prisma chose not to include individual library functions within the module
648 database at this time.
649 .NH 2
650 Configurable Logging Support
651 .PP
652 The \fBcvs\fP \*Qcommit\*U command is used to make a permanent change to the
653 master source repository (where the
654 .SM
655 RCS
656 .LG
657 \*Q,v\*U files live).
658 Whenever a \*Qcommit\*U is done, the log message for the change is carefully
659 logged by an arbitrary program (in a file, notesfile, news database, or
660 mail).
661 For example, a collection of these updates can be used to produce release
662 notices.
663 \fBcvs\fP can be configured to send log updates through one or more filter
664 programs, based on a regular expression match on the directory that is
665 being changed.
666 This allows multiple related or unrelated projects to exist within a single
667 \fBcvs\fP source repository tree, with each different project sending its
668 \*Qcommit\*U reports to a unique log device.
669 .PP
670 A sample logging configuration file might look as follows:
671 .DS
672 \f(CW   #regex      filter-program
673         DEFAULT     /usr/local/bin/nfpipe -t %s utils.updates
674         ^diag       /usr/local/bin/nfpipe -t %s diag.updates
675         ^local      /usr/local/bin/nfpipe -t %s local.updates
676         ^perf       /usr/local/bin/nfpipe -t %s perf.updates
677         ^sys        /usr/local/bin/nfpipe -t %s kernel.updates\fP
678 .DE
679 .PP
680 This sample allows the diagnostics and performance groups to
681 share the same source repository with the kernel and utilities groups.
682 Changes that they make are sent directly to their own notesfile [Essick]
683 through the \*Qnfpipe\*U program.
684 A sufficiently simple title is substituted for the \*Q%s\*U argument before
685 the filter program is executed.
686 This logging configuration file is tailored manually to each specific
687 source repository environment.
688 .NH 2
689 Tagged Releases and Dates
690 .PP
691 Any release can be given a symbolic tag name that is stored directly in the
692 .SM
693 RCS
694 .LG
695 files.
696 This tag can be used at any time to get an exact copy of any previous
697 release.
698 With equal ease, one can also extract an exact copy of the source files as
699 of any arbitrary date in the past as well.
700 Thus, all that's required to tag the current kernel, and to tag the kernel
701 as of the Fourth of July is:
702 .DS
703 \f(CW   example% cvs tag TEST_KERNEL kernel
704         example% cvs tag -D 'July 4' PATRIOTIC_KERNEL kernel\fP
705 .DE
706 The following command would retrieve an exact copy of the test kernel at
707 some later date:
708 .DS
709 \f(CW   example% cvs checkout -fp -rTEST_KERNEL kernel\fP
710 .DE
711 The \fI-f\fP option causes only files that match the specified tag to be
712 extracted, while the \fI-p\fP option automatically prunes empty directories.
713 Consequently, directories added to the kernel after the test kernel was
714 tagged are not included in the newly extracted copy of the test kernel.
715 .PP
716 The \fBcvs\fP date support has exactly the same interface as that provided
717 with
718 .SM
719 RCS\c
720 .LG
721 , however \fBcvs\fP must process the \*Q,v\*U files directly due to the
722 special handling required by the vendor branch support.
723 The standard
724 .SM
725 RCS
726 .LG
727 date handling only processes one branch (or the main trunk) when checking
728 out based on a date specification.
729 \fBcvs\fP must instead process the current \*Qhead\*U branch and, if a
730 match is not found, proceed to look for a match on the vendor branch.
731 This, combined with reasons of performance, is why \fBcvs\fP processes
732 revision (symbolic and numeric) and date specifications directly from the
733 \*Q,v\*U files.
734 .NH 2
735 Building \*Qpatch\*U Source Distributions
736 .PP
737 \fBcvs\fP can produce a \*Qpatch\*U format [Wall] output file which can be
738 used to bring a previously released software distribution current with the
739 newest release.
740 This patch file supports an entire directory hierarchy within a single
741 patch, as well as being able to add whole new files to the previous
742 release.
743 One can combine symbolic revisions and dates together to display changes in
744 a very generic way:
745 .DS
746 \f(CW   example% cvs patch -D 'December 1, 1988' \e
747                            -D 'January 1, 1989' sys\fP
748 .DE
749 This example displays the kernel changes made in the month of December,
750 1988.
751 To release a patch file, for example, to take the \fBcvs\fP distribution
752 from version 1.0 to version 1.4 might be done as follows:
753 .DS
754 \f(CW   example% cvs patch -rCVS_1_0 -rCVS_1_4 cvs\fP
755 .DE
756 .NH
757 CVS Experience
758 .NH 2
759 Statistics
760 .PP
761 A quick summary of the scale that \fBcvs\fP is addressing today
762 can be found in Table 1.
763 .KF
764 .TS
765 box center tab(:);
766 c s
767 c s
768 c | c
769 l | n .
770 \fB\s+2Revision Control Statistics at Prisma
771 as of 11/11/89\fP\s-2
772 _
773 How Many...:Total
774 =
775 Files:17243
776 Directories:1005
777 Lines of code:3927255
778 Removed files:131
779 Software developers:14
780 Software groups:6
781 Megabytes of source:128
782 .TE
783 .ce 100
784 .LG
785 \fBTable 1.\fP
786 .SM
787 \fBcvs\fP Statistics
788 .ce 0
789 .sp .3
790 .KE
791 Table 2 shows the history of files changed or added and the number
792 of source lines affected by the change at Prisma.
793 Only changes made to the kernel sources are included.
794 .KF
795 .TS
796 box center tab(:);
797 c s s s s
798 c s s s s
799 c || c | c || c | c
800 c || c | c || c | c
801 l || n | n || n | n.
802 \fB\s+2Prisma Kernel Source File Changes
803 By Month, 1988-1989\fP\s-2
804 _
805 Month:# Changed:# Lines:# Added:# Lines
806 \^:Files:Changed:Files:Added
807 =
808 Dec:87:3619:68:9266
809 Jan:39:4324:0:0
810 Feb:73:1578:5:3550
811 Mar:99:5301:18:11461
812 Apr:112:7333:11:5759
813 May:138:5371:17:13986
814 Jun:65:2261:27:12875
815 Jul:34:2000:1:58
816 Aug:65:6378:8:4724
817 Sep:266:23410:113:39965
818 Oct:22:621:1:155
819 Total:1000:62196:269:101799
820 .TE
821 .ce 100
822 .LG
823 \fBTable 2.\fP
824 .SM
825 \fBcvs\fP Usage History for the Kernel
826 .ce 0
827 .sp
828 .KE
829 The large number of source file changes made in September are the result of
830 merging the SunOS 4.0.3 sources into the kernel.
831 This merge process is described in section 3.3.
832 .NH 2
833 Performance
834 .PP
835 The performance of \fBcvs\fP is currently quite reasonable.
836 Little effort has been expended on tuning \fBcvs\fP, although performance
837 related decisions were made during the \fBcvs\fP design.
838 For example, \fBcvs\fP parses the
839 .SM
840 RCS
841 .LG
842 \*Q,v\*U files directly instead of running an
843 .SM
844 RCS
845 .LG
846 process.
847 This includes following branches as well as integrating with the vendor
848 source branches and the main trunk when checking out files based on a date.
849 .PP
850 Checking out the entire kernel source tree (1223 files/59 directories)
851 currently takes 16 wall clock minutes on a Sun-4/280.
852 However, bringing the tree up-to-date with the current kernel sources, once
853 it has been checked out, takes only 1.5 wall clock minutes.
854 Updating the \fIcomplete\fP 128 MByte source tree under \fBcvs\fP control
855 (17243 files/1005 directories) takes roughly 28 wall clock minutes and
856 utilizes one-third of the machine.
857 For now this is entirely acceptable; improvements on these numbers will
858 possibly be made in the future.
859 .NH 2
860 The SunOS 4.0.3 Merge
861 .PP
862 The true test of the \fBcvs\fP vendor branch support came with the arrival
863 of the SunOS 4.0.3 source upgrade tape.
864 As described above, the \fBcheckin\fP program was used to install the new
865 sources and the resulting output file listed the files that had been
866 locally modified, needing to be merged manually.
867 For the kernel, there were 94 files in conflict.
868 The \fBcvs\fP \*Qjoin\*U command was used on each of the 94 conflicting
869 files, and the remaining conflicts were resolved.
870 .PP
871 The \*Qjoin\*U command performs an \fBrcsmerge\fP operation.
872 This in turn uses \fI/usr/lib/diff3\fP to produce a three-way diff file.
873 As it happens, the \fBdiff3\fP program has a hard-coded limit of 200
874 source-file changes maximum.
875 This proved to be too small for a few of the kernel files that needed
876 merging by hand, due to the large number of local changes that Prisma had
877 made.
878 The \fBdiff3\fP problem was solved by increasing the hard-coded limit by an
879 order of magnitude.
880 .PP
881 The SunOS 4.0.3 kernel source upgrade distribution contained
882 346 files, 233 of which were modifications to previously released files,
883 and 113 of which were newly added files.
884 \fBcheckin\fP added the 113 new files to the source repository
885 without intervention.
886 Of the 233 modified files, 139 dropped in cleanly by \fBcheckin\fP, since
887 Prisma had not made any local changes to them, and 94 required manual
888 merging due to local modifications.
889 The 233 modified files consisted of 20,766 lines of differences.
890 It took one developer two days to manually merge the 94 files using the
891 \*Qjoin\*U command and resolving conflicts manually.
892 An additional day was required for kernel debugging.
893 The entire process of merging over 20,000 lines of differences was
894 completed in less than a week.
895 This one time-savings alone was justification enough for the \fBcvs\fP
896 development effort; we expect to gain even more when tracking future SunOS
897 releases.
898 .NH
899 Future Enhancements and Current Bugs
900 .PP
901 Since \fBcvs\fP was designed to be incomplete, for reasons of design
902 simplicity, there are naturally a good
903 number of enhancements that can be made to make it more useful.
904 As well, some nuisances exist in the current implementation.
905 .RS
906 .IP \(bu 3
907 \fBcvs\fP does not currently \*Qremember\*U who has a checked out a copy of a
908 module.
909 As a result, it is impossible to know who might be working on the same
910 module that you are.
911 A simple-minded database that is updated nightly would likely suffice.
912 .IP \(bu 3
913 Signal processing, keyboard interrupt handling in particular, is currently
914 somewhat weak.
915 This is due to the heavy use of the \fBsystem\fP\|(3) library
916 function to execute
917 .SM
918 RCS
919 .LG
920 programs like \fBco\fP and \fBci\fP.
921 It sometimes takes multiple interrupts to make \fBcvs\fP quit.
922 This can be fixed by using a home-grown \fBsystem\fP\|() replacement.
923 .IP \(bu 3
924 Security of the source repository is currently not dealt with directly.
925 The usual UNIX approach of user-group-other security permissions through
926 the file system is utilized, but nothing else.
927 \fBcvs\fP could likely be a set-group-id executable that checks a
928 protected database to verify user access permissions for particular objects
929 before allowing any operations to affect those objects.
930 .IP \(bu 3
931 With every checked-out directory, \fBcvs\fP maintains some administrative
932 files that record the current revision numbers of the checked-out files as
933 well as the location of the respective source repository.
934 \fBcvs\fP does not recover nicely at all if these administrative files are
935 removed.
936 .IP \(bu 3
937 The source code for \fBcvs\fP has been tested extensively on Sun-3 and
938 Sun-4 systems, all running SunOS 4.0 or later versions of the operating
939 system.
940 Since the code has not yet been compiled under other platforms, the overall
941 portability of the code is still questionable.
942 .IP \(bu 3
943 As witnessed in the previous section, the \fBcvs\fP method for tracking
944 third party vendor source distributions can work quite nicely.
945 However, if the vendor changes the directory structure or the file names
946 within the source distribution, \fBcvs\fP has no way of matching the old
947 release with the new one.
948 It is currently unclear as to how to solve this, though it is certain to
949 happen in practice.
950 .RE
951 .NH
952 Availability
953 .PP
954 The \fBcvs\fP program sources can be found in a recent posting to the
955 \fBcomp.sources.unix\fP newsgroup.
956 It is also currently available via anonymous ftp from \*Qprisma.com\*U.
957 Copying rights for \fBcvs\fP will be covered by the GNU General Public
958 License.
959 .NH
960 Summary
961 .PP
962 Prisma has used \fBcvs\fP since December, 1988.
963 It has evolved to meet our specific needs of revision and release control.
964 We will make our code freely available so that others can
965 benefit from our work, and can enhance \fBcvs\fP to meet broader needs yet.
966 .PP
967 Many of the other software release and revision control systems, like the
968 one described in [Glew], appear to use a collection of tools that are
969 geared toward specific environments \(em one set of tools for the kernel,
970 one set for \*Qgeneric\*U software, one set for utilities, and one set for
971 kernel and utilities.
972 Each of these tool sets apparently handle some specific aspect of the
973 problem uniquely.
974 \fBcvs\fP took a somewhat different approach.
975 File sharing through symbolic or hard links is not addressed; instead, the
976 disk space is simply burned since it is \*Qcheap.\*U
977 Support for producing objects for multiple architectures is not addressed;
978 instead, a parallel checked-out source tree must be used for each
979 architecture, again wasting disk space to simplify complexity and ease of
980 use \(em punting on this issue allowed \fIMakefile\fPs to remain
981 unchanged, unlike the approach taken in [Mahler], thereby maintaining closer
982 compatibility with the third-party vendor sources.
983 \fBcvs\fP is essentially a source-file server, making no assumptions or
984 special handling of the sources that it controls.
985 To \fBcvs\fP:
986 .QP
987 A source is a source, of course, of course, unless of course the source is
988 Mr. Ed.\**
989 .FS
990 \fBcvs\fP, of course, does not really discriminate against Mr. Ed.\**
991 .FE
992 .FS
993 Yet.
994 .FE
995 .LP
996 Sources are maintained, saved, and retrievable at any time based on
997 symbolic or numeric revision or date in the past.
998 It is entirely up to \fBcvs\fP wrapper programs to provide for release
999 environments and such.
1000 .PP
1001 The major advantage of \fBcvs\fP over the
1002 many other similar systems that have already been designed is the
1003 simplicity of \fBcvs\fP.
1004 \fBcvs\fP contains only three programs that do all the work of release
1005 and revision control, and two manually-maintained administrative
1006 files for each source repository.
1007 Of course, the deciding factor of any tool is whether people use it, and if
1008 they even \fIlike\fP to use it.
1009 At Prisma, \fBcvs\fP prevented members of the kernel
1010 group from killing each other.
1011 .NH
1012 Acknowledgements
1013 .PP
1014 Many thanks to Dick Grune at Vrije Universiteit in Amsterdam for his work
1015 on the original version of \fBcvs\fP and for making it available to the
1016 world.
1017 Thanks to Jeff Polk of Prisma for helping with the design of the module
1018 database, vendor branch support, and for writing the \fBcheckin\fP shell
1019 script.
1020 Thanks also to the entire software group at Prisma for taking the
1021 time to review the paper and correct my grammar.
1022 .NH
1023 References
1024 .IP [Bell] 12
1025 Bell Telephone Laboratories.
1026 \*QSource Code Control System User's Guide.\*U
1027 \fIUNIX System III Programmer's Manual\fP, October 1981.
1028 .IP [Courington] 12
1029 Courington, W.
1030 \fIThe Network Software Environment\fP,
1031 Sun Technical Report FE197-0, Sun Microsystems Inc, February 1989.
1032 .IP [Essick] 12
1033 Essick, Raymond B. and Robert Bruce Kolstad.
1034 \fINotesfile Reference Manual\fP,
1035 Department of Computer Science Technical Report #1081,
1036 University of Illinois at Urbana-Champaign, Urbana, Illinois,
1037 1982, p. 26.
1038 .IP [Glew] 12
1039 Glew, Andy.
1040 \*QBoxes, Links, and Parallel Trees:
1041 Elements of a Configuration Management System.\*U
1042 \fIWorkshop Proceedings of the Software Management Conference\fP, USENIX,
1043 New Orleans, April 1989.
1044 .IP [Grune] 12
1045 Grune, Dick.
1046 Distributed the original shell script version of \fBcvs\fP in the
1047 \fBcomp.sources.unix\fP volume 6 release in 1986.
1048 .IP [Honda] 12
1049 Honda, Masahiro and Terrence Miller.
1050 \*QSoftware Management Using a CASE Environment.\*U
1051 \fIWorkshop Proceedings of the Software Management Conference\fP, USENIX,
1052 New Orleans, April 1989.
1053 .IP [Mahler] 12
1054 Mahler, Alex and Andreas Lampen.
1055 \*QAn Integrated Toolset for Engineering Software Configurations.\*U
1056 \fIProceedings of the ACM SIGSOFT/SIGPLAN Software Engineering Symposium on
1057 Practical Software Development Environments\fP, ACM, Boston, November 1988.
1058 Described is the \fBshape\fP toolkit posted to the
1059 \fBcomp.sources.unix\fP newsgroup in the volume 19 release.
1060 .IP [Tichy] 12
1061 Tichy, Walter F.
1062 \*QDesign, Implementation, and Evaluation of a Revision Control System.\*U
1063 \fIProceedings of the 6th International Conference on Software
1064 Engineering\fP, IEEE, Tokyo, September 1982.
1065 .IP [Wall] 12
1066 Wall, Larry.
1067 The \fBpatch\fP program is an indispensable tool for applying a diff file
1068 to an original.
1069 Can be found on uunet.uu.net in ~ftp/pub/patch.tar.