home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 22 gnu / 22-gnu.zip / rcs567x.zip / README < prev    next >
Text File  |  1995-05-01  |  20KB  |  457 lines
  1. README for RCS 5.6.7.4 for PC's running under OS/2 or MS-DOS
  2. ------------------------------------------------------------
  3.  
  4. Release date: May 1st 1995
  5.  
  6. Changes: - the cii (rcsfront) indirect invocation method did not 
  7.            work for DOS, now just use the real executable
  8.          - cii itself did not work correctly on FAT file system
  9.          - integrated fix from Paul Eggert for "rcs -o"
  10.          - minor adjustments for emx 0.9a
  11.          - added a second 32-bit diff for DOS, created with
  12.            Watcom C 10.0 and the PMODE/W extender, for those
  13.            that have trouble with the emx generated one
  14.  
  15. Release date: December 16th 1994
  16.  
  17. Changes: - fixed another problem with 32-bit executables for OS/2,
  18.            they seem to work fine now
  19.          - updated emx and rsx DOS extender runtime modules
  20.  
  21. Release date: September 17th 1994 (never made public)
  22.  
  23. Changes: - fixed problem with checkout failures for 32-bit executables
  24.      - significant speedup for checkout of old revisions with
  25.            the 32-bit executables (side effect of above fix)
  26.  
  27. Release date: August 1st 1994
  28.  
  29. Changes: - added workaround for bug in MS-DOS SHARE.EXE
  30.      - new MS-DOS executables
  31.      - slightly corrected rcs/src/ms/Makefile and README files
  32.  
  33. Initial Release date: July 11th 1994
  34.  
  35.  
  36. 0. Archive Locations
  37. --------------------
  38.  
  39. This package is primarily distributed as
  40.  
  41.   ftp.informatik.tu-muenchen.de:/pub/comp/os/os2/gnu/devtools/rcs567pc.zip
  42.  
  43. As long as the author of this revision maintains the OS/2 and MS-DOS
  44. versions of RCS and has access to this archive site, the latest
  45. version can be found there (with file names indicating higher
  46. revisions, perhaps).
  47.  
  48. Other sites will have copies of this archive too, such as
  49.  
  50.   ftp.cdrom.com:/pub/os2/... (see 00index.txt file for exact location)
  51.  
  52. which is the best known OS/2 ftp archive site on the Internet.
  53.  
  54. Related packages that may be of interest for RCS users include (all
  55. path names relative to ftp.informatik.tu-muenchen.de:/pub/comp/os/os2/): 
  56.  
  57. - CVS 1.3 (gnu/devtools/cvs13p8b.zip and cvs13p8s.zip)
  58.  
  59.   CVS is a more advanced revision control system for multi user access
  60.   to shared source code without locks and with conflict resolution, it
  61.   works on top of RCS.
  62.  
  63. - GNU make 3.71 or newer (gnu/devtools/gnumake.zip)
  64.  
  65.   This is a "make" program that knows how to access source files
  66.   maintained with RCS without need to specify rules.
  67.  
  68. - GNU Emacs 19.25 or newer (gnu/emacs-19/*)
  69.  
  70.   The GNU Emacs editor is a very powerful programmer's editor that
  71.   provides easy access to files maintained with RCS via its included
  72.   "vc" package.
  73.  
  74. And, because used to create RCS for OS/2 and MS-DOS:
  75.  
  76. - the emx programming environment (gnu/emx+gcc/*)
  77.  
  78.   The emx environment (current version 0.9a, fix level 1) provides
  79.   tools to create and run 32-bit programs under OS/2 2.x and
  80.   MS-DOS. It uses many GNU programs, such as the gcc C/C++ compiler,
  81.   gas assembler, gdb debugger and libg++ class library.
  82.  
  83. - the RSX DOS extender, currently V4 (gnu/emx+gcc/contrib/dpmigcc4.zip)
  84.  
  85.   This is an alternative DOS extender for emx to let emx programs run
  86.   in a MS-DOS DPMI environment (such as Microsoft Windows 3.x).
  87.  
  88.  
  89. 1. Overview
  90. -----------
  91.  
  92. RCS is a revision control system, usually used by software developers
  93. to maintain revisions of the source code for the software they write.
  94.  
  95. This package contains in subdirectories:
  96.  
  97. rcs         the source code for RCS 5.6.7.4
  98.  
  99. rcsfront    the source code for RCSFRONT, a small front end tool for
  100.         easier management of a collection of files under RCS control
  101.  
  102. diff, diff16    the source code for the GNU diff program, an important tool 
  103.         required for RCS (two versions, see below)
  104.  
  105. doc        preformatted documentation (plain text and PostScript format)
  106.  
  107. bin32        OS/2 2.x executable programs (32-bit)
  108. bin16        OS/2 1.x executable programs (16-bit)
  109. bindos        MS-DOS executable programs (16-bit, but see below)
  110.  
  111. It is assumed that you are familiar with the concept and usage of
  112. RCS. If that is not the case, please read (or print and read) the
  113. original RCS documentation and manual pages available in the "doc"
  114. subdirectory. This file only documents platform and/or release
  115. specific information.
  116.  
  117.  
  118. 2. Installation
  119. ---------------
  120.  
  121. First, just pick the right set of executable programs and put them in
  122. a directory, which should be listed in the PATH environment
  123. variable. For the OS/2 32-bit executables, since they use a few DLL's
  124. (dynamic link libraries), this directory should also be listed in the
  125. LIBPATH statement in CONFIG.SYS.
  126.  
  127. Second, you need to set/check a few environment variables:
  128.  
  129. a) Either the USER or LOGNAME variable must contain the user's
  130.    (i.e. your) last name, unless you have network software installed
  131.    and want to use the name with which the user is logged on to the
  132.    network (see below). In this latter case, you need not set one of
  133.    these variables.
  134.  
  135. b) The TZ environment variable should contain your proper time zone
  136.    definition. If you use the OS/2 32-bit executables, you can also
  137.    use the EMXTZ variable if some other software on your machine
  138.    requires a more complicated value of this variable which programs
  139.    compiled with emx (see below) don't understand. 
  140.  
  141.    The TZ variable usually contains, the time zone name, the time zone
  142.    offset in hours to GMT and optionally the daylight savings time
  143.    zone name, examples are:
  144.  
  145.     SET TZ=PST8PDT        (pacific standard time)
  146.     SET TZ=CET-1        (central europe time)
  147.  
  148.    However, if you work strictly local and do not exchange source code
  149.    with people in other time zones, you may omit the TZ definition,
  150.    although that is NOT recommended.
  151.  
  152. c) The RCSINIT variable can contain options you want to use all the
  153.    time. The default value is suitable for work under DOS and on FAT
  154.    file systems under OS/2, i.e. all RCS files go into a subdirectory
  155.    RCS of the working directory. 
  156.  
  157.    If you work under OS/2 on a HPFS file system (or any other file
  158.    system that can handle long names), you may want to follow the Unix
  159.    convention of using RCS files in the working directory that have a
  160.    suffix of ",v". For this case, use "SET RCSINIT=-x,v/".
  161.  
  162.    See the RCS manual pages for details about all available options.
  163.  
  164. d) (this is optional, for OS/2 2.x only)
  165.  
  166.    The RCSLOAD environment variable can be set to a decimal number
  167.    specifying the amount of minutes to keep the RCS (and diff)
  168.    executables preloaded in memory. This requires that you have the
  169.    emx runtime package installed (emxload.exe is required). This
  170.    method may speed up the use of RCS from within GNU Emacs or with
  171.    CVS if many files are checked in/out.
  172.  
  173. After these steps, you should be able to use the RCS commands.
  174.  
  175.  
  176. 3. RCS
  177. ------
  178.  
  179. RCS is a widely used revision control system available for most Unix
  180. systems and several other platforms (such as in this package, for OS/2
  181. and MS-DOS). It allows shared use of RCS files in such heterogenous
  182. networks, for example.
  183.  
  184. * Note 1: Network Software
  185.  
  186. The RCS programs recognize certain PC networking software and query it
  187. for the name of the logged on user. The result can be overridden by
  188. the value of the USER or LOGNAME environment variables. The LOGNAME
  189. variable has precedence over the USER variable.
  190.  
  191. Under OS/2, the RCS programs recognize the following networking
  192. products:
  193.  
  194. - IBM LAN Server/Requester
  195. - Microsoft LAN Manager Server/Client
  196. - Novell NetWare Client
  197.  
  198. In addition, the installation of the IBM TCP/IP for OS/2 product
  199. usually sets the USER environment variable in CONFIG.SYS.
  200.  
  201. Under MS-DOS, the following networking products are recognized:
  202.  
  203. - IBM DOS LAN Requester
  204. - IBM PC Network
  205. - Microsoft LAN Manager Client
  206. - Microsoft Windows for Workgroups
  207. - Novell NetWare Client
  208.  
  209. and any compatible product.
  210.  
  211. Note that network support in RCS means only that the RCS commands can
  212. retrieve the current user name from the network software, nothing
  213. more.
  214.  
  215. * Note 2: binary files
  216.  
  217. This version of RCS for the PC does not support revision control of
  218. binary files. The main goal is to allow control of source files in
  219. heterogenous environments. In such environments, the systems can have
  220. different conventions for line separation in source code files. To
  221. allow shared use of RCS files between systems with different line
  222. separators, a conversion must take place when checking in/out
  223. files. This, naturally, breaks binary files. In a future version of
  224. RCS the concept of binary files may be introduced into the syntax of
  225. RCS files, to solve this problem. Until then, you can't check in/out
  226. binary files (such as icons or other resource data files), unless you
  227. use some kind of program to convert them into text format (such as
  228. uuencode).
  229.  
  230.  
  231. 4. RCSFRONT
  232. -----------
  233.  
  234. The RCSFRONT program, written by Jason P. Winters and Craig J. Kim is
  235. distributed by the Free Software Foundation. It allows checking in/out
  236. whole collections of files or even whole directory trees with RCS. It
  237. was heavily modified to run on the PC.
  238.  
  239. Of course, RCSFRONT is no substitute for more sophisticated software
  240. that builds on RCS for similar goals, such as CVS. But it may be
  241. sufficient for use on standalone systems or single-programmer
  242. projects. See its manual page in the "doc" subdirectory for more
  243. details.
  244.  
  245.  
  246. 5. GNU DIFF
  247. -----------
  248.  
  249. The RCS programs depend on the availability of the diff command under
  250. Unix, to compare two files (or two different revisions of a file in
  251. the context of RCS). Since that is not a standard command on PC
  252. operating systems, a version of it, the Free Software Foundation's GNU
  253. diff program, is included in this package.
  254.  
  255. Since the reliability of RCS depends on that of the diff program very
  256. heavily, a few more words on this topic:
  257.  
  258. This package supports PC's running OS/2 2.x (a 32-bit operating
  259. system), OS/2 1.x (a 16-bit operating system) and MS-DOS (a 16-bit
  260. operating system which, due to lack of any protection, allows
  261. implementing so-called DOS-extenders to run 32-bit programs on top of
  262. it).
  263.  
  264. The GNU diff program (current version is 2.6), which works very well
  265. with RCS is inherently a 32-bit program (it uses rather large data
  266. structures, for example). It can be compiled for OS/2 2.x without much
  267. effort. However, that is not the case for the 16-bit target
  268. systems. Because of this fact, long time ago I put a LOT of effort
  269. into porting the then current version (1.15) to let it run under OS/2
  270. 1.x and under MS-DOS and testing it thoroughly. As you can see from
  271. the version numbers, it has undergone quite some development since
  272. then and porting the current version again to OS/2 1.x and MS-DOS
  273. would be a lot of work.
  274.  
  275. Because the functionality of diff that is used by RCS has not changed
  276. since 1.15 and since it does not make sense to spend a lot of time for
  277. the 16-bit target operating systems any longer, I decided to include
  278. *two* versions of GNU diff in this package. The old version, 1.15, is
  279. included for use under OS/2 1.x and MS-DOS in the "diff16"
  280. subdirectory and the current version, 2.6, is included for use under
  281. OS/2 2.x (and MS-DOS on 386 CPU's, see below) in the "diff"
  282. subdirectory.
  283.  
  284. Since MS-DOS can be used to also run 32-bit programs with some kind of
  285. DOS extender, this current version of GNU diff can also be used under
  286. MS-DOS, if a 386 or higher CPU is available. This is very important
  287. because MS-DOS limits normal DOS programs to use only up to 640k of
  288. memory less the amount used for MS-DOS itself. And since some RCS
  289. programs call diff as a subprogram, even less memory is available for
  290. diff. So, naturally, the diff program when running under DOS can fail
  291. with "out of memory"-type errors if you try to use RCS commands on
  292. larger files. If that occurs, you should switch to the 32-bit version
  293. of diff, diff-32.exe in the "bindos" subdirectory and rename that to
  294. diff.exe. There is another 32-bit diff program, diff-pw.exe, generated
  295. with a different compiler and DOS extender, in case the diff-32.exe
  296. fails for you.
  297.  
  298. The RCS commands merge and rcsmerge depend on the availability of
  299. another related command, the diff3 program. This program is a
  300. three-way file comparison/merge program that in turn uses the diff
  301. program as a subprogram. A version of it is included with the GNU diff
  302. program in the same package. 
  303.  
  304. The user interface of the diff3 program was changed noticable between
  305. versions 1.15 and 2.6 and the RCS programs merge and rcsmerge require
  306. at least the diff3 program included with GNU diff 2.1. For this reason
  307. and since it is a much smaller program than diff itself, the GNU diff
  308. 2.6's diff3 program has been "ported back" to GNU diff 1.15 and is
  309. also used in the 16-bit target environments.
  310.  
  311. To make a long story short, while the executables for the RCS
  312. programs, RCSFRONT and diff3 for all three target environments are
  313. made from the same source code, two different versions of GNU diff
  314. (1.15 and 2.6) are used to create the diff program's executables for
  315. the three platforms, 1.15 for 16-bit OS/2 1.x and MS-DOS and 2.6 for
  316. 32-bit OS/2 2.x and MS-DOS on 386 and up PC's.
  317.  
  318.  
  319. 6. The emx toolkit and the emx and rsx DOS extenders
  320. ----------------------------------------------------
  321.  
  322. The 32-bit diff program for dos, diff-32.exe, was created with the
  323. same compiler and toolkit (emx) that was used to create the 32-bit
  324. OS/2 2.x executables. That has saved a lot of extra work.
  325. Specifically, the emx 0.9a kit with patch 1 applied has been used. This
  326. toolkit uses the GNU gcc compiler and is freely available to everyone.
  327.  
  328. The emx kit includes a DOS extender (emx.exe) that allows to run
  329. 32-bit programs like diff-32.exe under plain DOS and in VCPI
  330. environment (certain DOS "memory managers" provide this
  331. environment). To run diff-32.exe in a DPMI environment (such as in DOS
  332. windows under Microsoft Windows 3.x), a different DOS extender is
  333. available, called rsx (rsx.exe). The diff-32.exe program automatically
  334. selects the right extender to run on at runtime. Both extenders are
  335. included in the "bindos" subdirectory in this packages as well as
  336. their COPYING and README files in the root directory of this
  337. package. You should be able to find the full packages of emx and rsx
  338. at the same places where you got this RCS package.
  339.  
  340. Note that you may already have either emx.exe or rsx.exe or even both
  341. on your MS-DOS system because they are popular and you may be using
  342. some other software that depends on them. In such a case, make sure
  343. you have only one copy (the newest one) on your system available via
  344. the PATH environment variable.
  345.  
  346. If you encounter problems with diff-32.exe under a DOS environment,
  347. you could give the diff-pw.exe in the bindos subdirectory a try. It
  348. uses a different DOS extender.
  349.  
  350. I mentioned that the emx toolkit was used to create the OS/2 2.x
  351. 32-bit executables. To save disk space, the RCS (and RCSFRONT and GNU
  352. diff/diff3) programs are linked with the shared runtime library of
  353. emx, so you have only copy of it on disk and not one in each separate
  354. executable. This emx runtime consists of emx.dll and emxlibc.dll. If
  355. you followed the installation instructions above, you should not
  356. notice any difference to "normal", statically linked programs. Since
  357. many free programs for OS/2 2.x are compiled with this
  358. compiler/toolkit, chances are big that you already have a copy of
  359. these DLL's on your system. Make sure you keep only one of them (the
  360. newest one) in a directory listed in the LIBPATH statement in your
  361. CONFIG.SYS.
  362.  
  363. In addition, because the RCS programs use a common set of utility
  364. functions, these have been put into another shared library,
  365. rcslib.dll. This further reduces disk space requirements
  366. considerably. Also, the GNU regular expression library used by GNU
  367. diff is also linked in a separate DLL, gnuregex.dll, since it is quite
  368. large and many of the FSF's programs use it, which are available for
  369. OS/2. You need only one copy of it on your system too.
  370.  
  371.  
  372. 7. Documentation
  373. ----------------
  374.  
  375. The manual pages for RCS and RCSFRONT programs and additional
  376. documents are available in the "doc" subdirectory in two formats: as
  377. plain ASCII files for reading with a browser and in PostScript (TM)
  378. format for printing on a PostScript printer or viewing/printing with
  379. GhostScript or GSView/PM. They were all created with the OS/2 version
  380. of the GNU groff text formatter from the "source" documents also
  381. included in this package (in the "rcs\man" and "rcsfront"
  382. subdirectories).
  383.  
  384. The documentation for GNU diff and diff3, version 2.6, is available as
  385. a TeXinfo source file in the "diff" subdirectory. A preformatted
  386. version in GNU Info format is in the "doc" subdirectory for reading
  387. with either the GNU Emacs editor or the standalone GNU info browser,
  388. but it can also be viewed with any normal file browser. A PostScript
  389. version of it, made with emTeX and dvips, is also in the "doc"
  390. subdirectory.
  391.  
  392. If you are not yet familiar with RCS and/or GNU diff, please read this
  393. documentation files.
  394.  
  395.  
  396. 8. Recompilation
  397. ----------------
  398.  
  399. In case you want to recompile: the 32-bit OS/2 2.x programs and the
  400. 32-bit MS-DOS GNU diff program are generated with the emx 0.9a toolkit
  401. (which uses gcc 2.5.7 or 2.5.8). The 0.9a version is absolutely required
  402. or you can experience loss of data with the generated programs.
  403.  
  404. With emx you could even generate 32-bit versions of all RCS programs
  405. and also RCSFRONT for MS-DOS on a 386 or larger CPU, but you don't
  406. gain anything from them, since these programs do not reach the MS-DOS
  407. 640k limit. In addition, when using emx to compile RCS for DOS, no
  408. network support is available for technical reasons.
  409.  
  410. For the 16-bit OS/2 1.x and MS-DOS programs, Microsoft C 6.00A was
  411. used. For MS-DOS, you should also be able to use MS C/C++ 7.00 or MS
  412. Visual C++ with only minor changes (not tested, but MS's C compilers
  413. are usually upwardly compatible).
  414.  
  415. In the "diff16" directory, there are separate Makefile.dos and
  416. Makefile.os2 file for use with the NMAKE program included with
  417. Microsoft C. In the "rcsfront" and "diff" directories there is one
  418. Makefile in each with multiple targets.
  419.  
  420. The Makefile for RCS itself is in the "rcs\src\ms" subdirectory
  421. together with a few more supporting files.
  422.  
  423.  
  424. 9. Problems
  425. -----------
  426.  
  427. Please read this file carefully. If you have problems using RCS, please
  428. first check it again to see if you forgot something and also check the
  429. RCS documentation in the "doc" subdirectory. Especially the emx/rsx
  430. runtime stuff can be confusing sometimes.
  431.  
  432. If that doesn't help, send a short and descriptive e-mail
  433. message. Don't laugh, you don't know how often I get e-mail with
  434. contents like "the foobar program you ported to OS/2 does not work,
  435. what should I do?" without any more details. Remember that I can't
  436. read your mind, especially not over such distances. :-)
  437.  
  438.  
  439. 10. Author / Address
  440. --------------------
  441.  
  442. Walter F. Tichy wrote the original version of RCS.
  443. Paul Eggert wrote the changes for RCS version 5.x, and helps maintain it.
  444.  
  445. This port of RCS 5.6.7.4 to MS-DOS and OS/2 is based on an earlier
  446. release (RCS 5.6.3) made by Paul Eggert, Frank Whaley and Kai Uwe
  447. Rommel.
  448.  
  449. The DOS and OS/2 related changes for 5.6.7.4, for the new DOS and OS/2
  450. 32-bit targets, the new networking support and the ports of RCSFRONT
  451. and GNU diff 1.15 and 2.6 were made by Kai Uwe Rommel.
  452.  
  453.  
  454. /* Kai Uwe Rommel                                      Muenchen, Germany *
  455.  * rommel@ars.muc.de                              CompuServe 100265,2651 *
  456.  * rommel@informatik.tu-muenchen.de                  Fax +49 89 324 4524 */
  457.