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