home *** CD-ROM | disk | FTP | other *** search
/ AmigActive 19 / AACD19.BIN / AACD / Programming / cvs-1.11 / cvs-1.11.readme < prev    next >
Text File  |  2001-02-04  |  10KB  |  213 lines
  1. Short:    Concurrent version control system
  2. Author:   Various; ported by Olaf Barthel <olsen@sourcery.han.de>
  3. Uploader: Olaf Barthel <olsen@sourcery.han.de>
  4. Type:     util/gnu
  5.  
  6. CVS 1.11 Amiga port
  7. ===================
  8.  
  9. Introduction
  10. ------------
  11. This is a somewhat rough port of GNU CVS 1.11, a version control system, which
  12. allows you to keep old versions of files (usually source code), keep a log of
  13. who, when, and why changes occurred, etc., like RCS or SCCS. It handles
  14. multiple developers, multiple directories, triggers to enable/log/control
  15. various operations, and can work over a wide area network. The following tasks
  16. are not included; they can be done in conjunction with CVS but will tend to
  17. require some script-writing and software other than CVS: bug-tracking, build
  18. management (that is, make and make-like tools), and automated testing. (Quoted
  19. from the CVS documentation.)
  20.  
  21. I call this a 'rough port' since it is not as polished as, say Heinz Wrobel's
  22. excellent 'RCS' port. It does what it needs to do, but a few features are
  23. sorely lacking, such as support for Amiga file protection bits and code to
  24. communicate with CVS servers via secure channels (Kerberos, SSH). On the other
  25. hand, however, you get everything, and perhaps more, you got with the previous
  26. Amiga ports of CVS: this port does not require 'ixemul.library' to work and it
  27. does not require an RCS installation as it is completely self contained. The
  28. port also probably would win a price as the largest 'pure' executable; it can
  29. be made resident.
  30.  
  31.  
  32. What's in this package?
  33. -----------------------
  34. This distribution contains the Amiga port, the Amiga specific source code and
  35. most of the original GNU CVS 1.11 distribution. 'Most' in this case means that
  36. only the original source code has been omitted in order to keep the
  37. distribution archive small; the documentation and support files are all
  38. provided. The original source code can be downloaded from the Internet at
  39. 'ftp://ftp.cvshome.org/pub/cvs-1.11/cvs-1.11.tar.gz'. I have added two more
  40. files which are converted from the original Unix man pages, namely 'cvs.1.man'
  41. and 'cvs.5.man' whose sources can be found in the 'cvs-1.11/man' directory.
  42.  
  43.  
  44. Installation
  45. ------------
  46. Almost everything you need to get CVS up and running is contained in the
  47. archive which also included the 'README.AMIGA' file you are currently reading.
  48. And that means the 'cvs' executable. You will also need a working
  49. 'pipe-handler' (the one that ships with Workbench 3.1 and beyond is,
  50. unfortunately, broken) which can be found on Aminet. A TCP/IP stack like Miami
  51. or AmiTCP is supported by not strictly required: you can perfectly well keep
  52. your CVS repository on your local machine. Since CVS may ask you to edit the
  53. log entries associated with the files to store, you may want to configure the
  54. 'EDITOR' environment variable. Last, but not least, you must set up an
  55. environment variable which allows CVS to associate you with the changes you
  56. made; this should be the 'USER', 'LOGUSER' or 'USERNAME' variable.
  57.  
  58. Most importantly, this port requires Kickstart 2.04 or higher.
  59.  
  60. Here is how you could set up CVS on your machine. We start by creating two
  61. drawers on the 'Work:' volume:
  62.  
  63.    MakeDir Work:CVS-Root
  64.    MakeDir Work:CVS-Home
  65.  
  66. Next, we add two lines to the 'S:User-Startup' file:
  67.  
  68.    Assign CVSHOME: Work:CVS-Home
  69.    Path CVSHOME: Add
  70.  
  71. The CVS program will need to be copied:
  72.  
  73.    Copy cvs Work:CVS-Home CLONE
  74.  
  75. And the path to the CVS repository needs to be set:
  76.  
  77.    SetEnv CVSROOT :local:Work:CVS-Root
  78.    Copy ENV:CVSROOT ENVARC:
  79.  
  80. Two environment variables need to be set up. Most importantly, CVS will need
  81. your ID to write it into the log and revision files it creates. The Amiga port
  82. will query three environment variables for that information, in the following
  83. order: 'USER', 'LOGUSER' and 'USERNAME'. This means if the variable 'USER' is
  84. not set, it will proceed to check whether 'LOGUSER' is set, and so forth. You
  85. may have already configured these variables, but if you haven't, I suggest you
  86. set up the 'LOGUSER' variable, like this:
  87.  
  88.    SetEnv LOGUSER <Your ID here>
  89.    Copy ENV:LOGUSER ENVARC:
  90.  
  91. Note that <Your ID here> should be replaced by a mnemonic, nick name or short
  92. name that must not contain any blank space characters.
  93.  
  94. You may want to configure the 'EDITOR' environment variable to invoke your
  95. preferred text editor when CVS requests that log messages are added for an
  96. update. If this variable is not set, CVS will default to invoke the 'Ed'
  97. editor. This can be problematic if you have installed 'CygnusEd' whose 'Ed'
  98. program detaches from the Shell that invoked it. When CVS invokes the editor,
  99. it expects it to return only when the user has finished editing the respective
  100. file. Here is an example configuration for CygnusEd:
  101.  
  102.    SetEnv EDITOR Ed -keepio
  103.  
  104. And here is one for TurboText:
  105.  
  106.    SetEnv EDITOR TTX WAIT
  107.  
  108. Don't forget to save the environment variable setting to make it permanent,
  109. like this:
  110.  
  111.    Copy ENV:EDITOR ENVARC:
  112.  
  113. Finally, install the 'pipe-handler' from Aminet and reboot your machine. When
  114. the system is again up and running, initialize the CVS repository like this:
  115.  
  116.    cvs init
  117.  
  118. And that's all. Well, maybe you want to add a few default options to the
  119. configuration file CVS reads upon startup. That file should be placed in the
  120. 'CVSHOME:' directory and called '.cvsrc':
  121.  
  122.  
  123. Usage
  124. -----
  125. I personally found the default CVS documentation to be rather confusing. If
  126. you don't know rather well what CVS is good for, the examples, the
  127. terminology, all this doesn't seem to make great sense. My introduction to CVS
  128. followed with Karl Fogel's book "Open Source Development with CVS" which
  129. describes in compact form what CVS is and how it may be used. I suggest that
  130. you consult the book (portions of which are available from 'www.coriolis.com')
  131. and/or the CVS documentation (which has been included with this archive in the
  132. 'cvs-1.11/doc' drawer) for hints and ideas on how to use the program.
  133.  
  134. What many people fail to realize and what keeps them from using CVS in place
  135. of the revision control system they have used for years is that you do not
  136. need a networked CVS repository in order to use CVS. A local repository will
  137. do. In fact, I switched over most of my current software development projects
  138. to use a single local repository after I realized that CVS does much better
  139. what I had previously used RCS for.
  140.  
  141.  
  142. Notes on the implementation
  143. ---------------------------
  144. The Amiga port implements only the client side of the CVS system. This means
  145. that you can check out projects on remote servers but your local Amiga cannot
  146. be a CVS server itself. This feature was omitted deliberately since I could
  147. not find a safe and useful way to make CVS server mode work on the Amiga.
  148. AmigaOS is not a server operating system and shoehorning the code to make it
  149. work somehow would not have helped. If you need a CVS server, try a dedicated
  150. solution using, for example, 'NetBSD'. The Amiga port can communicate with the
  151. server using the remote shell protocol (rsh), and I have verified that the
  152. process works reasonably well with, for example, the public 'Samba' CVS
  153. repository. If you need a more secure method to communicate with the server
  154. ('rsh' is notoriously insecure and many systems no longer support it for
  155. precisely that reason) such as 'Kerberos IV' or 'Secure Shell' (ssh), you'll
  156. have a problem because there are no Amiga ports of these facilities available
  157. yet.
  158.  
  159. CVS does not have a very sophisticated porting layer. Its file name semantics
  160. all stem from the Unix world and the 'OS/2', 'VMS' and 'Windows NT' ports
  161. merely resort to flipping slashes in file names, if necessary when it comes to
  162. make a name fit the local system's semantics. I had to find a similar way to
  163. make the semantics work on the Amiga. What I did was to add a translation
  164. service in the Amiga specific code which knows how to translate names like '.'
  165. or '..'. But that's where it ends. Any more sophisticated naming schemes like
  166. 'foo/.././bar' may fail to translate properly. But then, those complex
  167. patterns should be pretty rare anyway.
  168.  
  169. Unlike Heinz Wrobel's excellent 'RCS' port, this CVS port does not preserve
  170. Amiga file protection bits for files checked in. When you check in a project
  171. and check it out again, all file and directory protection bits will default to
  172. 'rwed', losing the 'archived', 'pure' and 'script' bits.
  173.  
  174. The Amiga port will expand wild card patterns for file and directory names
  175. specified as command line parameters, such as "#?.c". The wild card pattern
  176. syntax is that of AmigaDOS. It is *not* the syntax of the standard regular
  177. expressions other GNU tools will use.
  178.  
  179. You can access remote CVS repositories by means of a properly configured
  180. TCP/IP stack. This port requires that the stack complies to the AmiTCP V3 API
  181. definition, which all modern Amiga TCP/IP stacks do. It does not work with the
  182. INet-225 TCP/IP stack, though.
  183.  
  184. When CVS resorts to calling external programs, a working 'PIPE:' device is
  185. required, which is not yet part of the AmigaOS Workbench distribution. Do not
  186. underestimate this. The program will fail or behave erratically without a
  187. working 'PIPE:' device. It is strongly recommended to download a working
  188. 'pipe-handler', such as from Aminet.
  189.  
  190. The source code for the Amiga port is included in this distribution. All you
  191. need to know before you can recompile this CVS port is described in the file
  192. 'README.AMIGA' which you can find in the 'source' directory.
  193.  
  194. This is a 'single user' CVS port. There is just one single home directory
  195. (referred to as 'CVSHOME:') and your login name and ID are assumed to be the
  196. same (set in the 'USER', 'LOGUSER' or 'USERNAME' environment variables).
  197.  
  198. There is no 'cvsbug' shell script or program included with this port.
  199.  
  200.  
  201. Contacting the author
  202. ---------------------
  203. If you have any further questions on this port, feel free to contact me:
  204.  
  205.    olsen@sourcery.han.de
  206.  
  207. Or use my postal address:
  208.  
  209.    Olaf Barthel
  210.    Brabeckstr. 35
  211.    D-30559 Hannover
  212.    Federal Republic of Germany
  213.