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