README for RCS 5.7 for PC's running under OS/2, DOS or Win32 ------------------------------------------------------------ Release date: March 28th 1999 Changes: - replaced runtime library popen code with my own - added IBM C/C++ compiler support for OS/2 and Win32 - added MinGW32 and CygWin compiler support - updated RSXNT compiler support to 1.42 - removed rcsfront - fixed all reported bugs - added RCS_LF_ONLY environment variable support - use MinGW32 as compiler for distributed Win32 executables Release date: April 4th 1997 Changes: - fixed working file mode buglet for rcsdiff - other minor fixes - updated hypertext RCS docs from K.H. Marbaise - updated RSXNT to 1.31 Release date: Jan 26th 1997 Changes: - fixed Win95/NT bug with export of const data items from RSXNT-built DLL Release date: Jan 12th 1997 Changes: - added binary mode support to cii/coo (from Hans-Otto Ultes) - fixed bug causing "ci -f" to fail if no headers to expand - fixed bug causing crash with pseudo symlinks - fixed bug causing misleading error message due to nobody being logged on to networking software recognized by RCS - include GNU info, TeX DVI and OS/2 IPF formatted docs (from K.H. Marbaise) - make Win95/NT executables with RSXNT 1.3, a few source changes were required Release date: May 20th 1996 Changes: - fixed serious bug with every other file argument often not working Release date: May 14th 1996 Changes: - upgraded RCS to GNU RCS 5.7 - upgraded diff to GNU diff 2.7.2 - DOS 32-bit diff now only supplied in Watcom+PMODE/W version - support for binary files working now, see below - support for pseudo symbolic links - support for Windows 95 and Windows NT Release date: May 1st 1995 Changes: - the cii (rcsfront) indirect invocation method did not work for DOS, now just use the real executable - cii itself did not work correctly on FAT file system - integrated fix from Paul Eggert for "rcs -o" - minor adjustments for emx 0.9a - added a second 32-bit diff for DOS, created with Watcom C 10.0 and the PMODE/W extender, for those that have trouble with the emx generated one Release date: December 16th 1994 Changes: - fixed another problem with 32-bit executables for OS/2, they seem to work fine now - updated emx and rsx DOS extender runtime modules Release date: September 17th 1994 (never made public) Changes: - fixed problem with checkout failures for 32-bit executables - significant speedup for checkout of old revisions with the 32-bit executables (side effect of above fix) Release date: August 1st 1994 Changes: - added workaround for bug in MS-DOS SHARE.EXE - new MS-DOS executables - slightly corrected rcs/src/ms/Makefile and README files Initial Release date: July 11th 1994 0. Archive Locations -------------------- This package is primarily distributed as rcs57pc1.zip, rcs57pc2.zip and rcs57pc3.zip on ftp://ftp.leo.org/pub/comp/os/os2/gnu/devtools/ and ftp://ftp.cs.purdue.edu/pub/RCS/ The first archive contains the executable files, the second contains the formatted documentation files and the third one contains the source code and documentation source files. As long as the author of this revision maintains the PC versions of RCS and has access to this archive site, the latest version can be found there (with file names indicating higher revisions, perhaps). Other sites will have copies of this archive too, such as ftp://ftp-os2.nmsu.edu/pub/os2/unix ftp://ftp-os2.cdrom.com/pub/os2/unix which are the best known OS/2 ftp archive sites on the Internet. In addition, one should be able to find it in the Simtel and Coast-to-Coast archives: ftp://ftp.simtel.net/pub/simtelnet/msdos/pgmutl ftp://ftp.coast.net/simtel/msdos/pgmutil ftp://ftp.coast.net/simtel/os2/pgmtools ftp://ftp.coast.net/simtel/nt/pgmtools Related packages that may be of interest for RCS users include: - CVS 1.9 or newer CVS is a more advanced revision control system for multi user access to shared source code without locks and with conflict resolution. It works on top of RCS. - GNU make 3.74 or newer This is a "make" program that knows how to access source files maintained with RCS without need to specify special rules. - GNU Emacs 19.30 or newer The GNU Emacs editor is a very powerful programmer's editor that provides easy access to files maintained with RCS via its included "vc" package. And, because they can be used to create executables of this RCS version: - emx programming environment The emx environment (current version 0.9d) provides tools to create and run 32-bit programs under OS/2 2.x and MS-DOS. It uses many GNU programs, such as the gcc C/C++ compiler, the gas assembler, the gdb debugger and so on. - RSX DOS extender and Win32 runtime environment for emx This is an alternative DOS extender for emx to let emx programs run in a MS-DOS DPMI environment (such as Microsoft Windows 3.x) as well as a kind of "emx runtime for Win32". - CygWin and MinGW32 compiler kits The CygWin and MinGW32 compiler kits use many GNU programs, such as the gcc C/C++ compiler, the gas assembler, the gdb debugger and more. They support the creation of native Win32 applications as well, of course. 1. Overview ----------- RCS is a revision control system, usually used by software developers to maintain revisions of the source code for the software they write. This package contains in subdirectories: rcs the source code for RCS 5.7 diff, diff16 the source code for the GNU diff program, an important tool required for RCS (two versions, see below) doc preformatted documentation files (in HTML, IBM .INF, GNU info and postScript formats) man preformatted manual pages (in HTML, plain text and postScript formats) bin/dos MS-DOS executable programs (16-bit, but see below) bin/win32 Windows 95/98 and NT executable programs (32-bit) bin/os2-32 OS/2 2.x executable programs (32-bit) bin/os2-16 OS/2 1.x executable programs (16-bit) It is assumed that you are familiar with the concept and usage of RCS. If that is not the case, please read (or print and read) the original RCS documentation and manual pages available in the "doc" and "man" subdirectories. This file only documents platform and/or release specific information. 2. Installation --------------- First, just pick the right set of executable programs and put them in a directory, which should be listed in the PATH environment variable. For the OS/2 32-bit executables, since they use a few DLL's (dynamic link libraries), this directory should also be listed in the LIBPATH statement in CONFIG.SYS. Second, you need to set/check a few environment variables: a) Either the USER or LOGNAME variable must contain the user's (i.e. your) last name, unless you have network software installed and want to use the name with which the user is logged on to the network (see below). In this latter case, you need not set one of these variables, if RCS is able to detect the logged on user name. b) The TZ environment variable should contain your proper time zone definition. The TZ variable usually contains the time zone name, the time zone offset in hours to GMT and optionally the daylight savings time zone name. Examples are: SET TZ=PST8PDT (pacific standard time) SET TZ=CET-1 (central european time) On OS/2, see the emx runtime documentation for a description of the full TZ value syntax. c) The RCSINIT variable can contain options for RCS you want to use all the time. The default value is suitable for work under DOS and on FAT file systems under OS/2, i.e. all RCS files go into a subdirectory RCS of the working directory and have no special suffix. If you work under OS/2 on a HPFS file system (or any other file system that can handle long names), you may want to follow the Unix convention of using RCS files in the working directory that may also have a suffix of ",v". For this case, use "SET RCSINIT=-x,v/". Windows 95 and NT also support long file names and the ,v suffix, but the ,v suffix not on FAT file systems, only on network drives (that reside on OS/2 HPFS or NT NTFS servers or on Unix NFS servers). See the RCS manual pages for details about all other available options. d) Make sure you have a properly set the TMP and TEMP environment variables that point to a directory where temporary files should be stored. e) (this is optional, for OS/2 32-bit executables only) The RCSLOAD environment variable can be set to a decimal number specifying the amount of minutes to keep the RCS (and diff) executables preloaded in memory. This requires that you have the emx runtime package installed (emxload.exe is required). This method may speed up the use of RCS from within GNU Emacs or with CVS if many files are checked in/out in a batch because that can result in a large number of executed subprocesses with RCS programs. f) The RCS_LF_ONLY environment variable may be used in mixed platform environments concurrently accessing RCS working files. See below for details. After these steps, you should be able to use the RCS commands. 3. About RCS ------------ RCS is a widely used revision control system available for most Unix systems and several other platforms (such as in this package, for OS/2 and MS-DOS/Windows, Windows 95 and Windows NT). It allows shared use of RCS files in heterogenous networks, for example. A few notes on PC specific details, however: * Note 1: Network Software The RCS programs recognize certain PC networking software and query it for the name of the logged on user. The result can be overridden by the value of the USER or LOGNAME environment variables. The LOGNAME variable has precedence over the USER variable. Under OS/2, the RCS programs recognize the following networking products: - IBM LAN Server and LAN Requester - IBM Peer LAN (Warp Connect and Warp 4) - Microsoft LAN Manager - Novell NetWare Client In addition, the installation of the IBM TCP/IP for OS/2 product usually sets the USER environment variable in CONFIG.SYS. Under MS-DOS, the following networking products are recognized: - IBM DOS LAN Requester or DOS LAN Services - IBM PC Network - Microsoft LAN Manager Client - Novell NetWare Client Also the locally logged on user name is recognized if networking components are used in: - Microsoft Windows for Workgroups - Microsoft Windows 95/98 - Microsoft Windows NT Any product compatible to those mentioned should work as well. Note that network support in RCS means only that the RCS commands can retrieve the current user name from the networking software, nothing more. In particular, RCS relies on correct support for file locking and "strange" file modes (such as creating a read-only file and writing to it before closing it for the first time) on network drives. RCS only uses regular OS file system services on network drives. * Note 2: binary files This version of RCS for the PC does now support revision control of binary files. The main goal, however, is to allow control of source files in heterogenous environments. In such environments, the systems can have different conventions for line separation in source code files. To allow shared use of RCS files between systems with different line separators, a conversion must take place when checking in/out files. This, naturally, would break many binary files. Therefore a special option, -kb, must be used for binary files with this RCS version to mark them as binary files. Before you can check in a binary file you must initialize an empty RCS file with "rcs -i -kb ". Do not use -kb for plain text files because it makes those RCS files non-portable to other operating environments. The way how RCS currently stores "differences" between the revisions of a binary file is quite inefficient (but more or less portable). Future version of RCS may support better methods. * Note 3: using working files from different platforms In case you are working in a heterogeneous environment where multiple users access RCS working files concurrently, you may encounter problems with different line separation conventions, as mentioned above in Note 2. Particularly, Unix systems use a LF character for line separations while PC operating systems (except Linux etc.) usually use a CR/LF sequence. If you access RCS working files from PCs as well as from Unix systems, you will usually have no problems if the files were checked out by Unix users. While the working files will have LF characters only separating lines, PC tools and editors generally can work fine with such text files. And when checking back in such files, both platforms will handle this type of files correctly. However, if you check out working files on PC systems, only PC users can normally access/edit these files while the extra CR line separation character will probably confuse Unix users, tools and editors. In this case, set the environment variable RCS_LF_ONLY to any value (the exact value is not relevant, the RCS tools only check for the presence of this variable). This causes the RCS tools on the PC to check out the working files with Unix line separation conventions, with LF characters only separating the lines. You have to be sure, of course, that all the tools you use on PC systems to access/edit these working files can use files with that line separation convention (which is generally the case). And Unix users can access/edit these files as if they were checked out by a Unix system. If, in such a setup, some PC editor does read such a text file with LF only line separators but writes it back to the file system with CR/LF line separators, you need to make sure you check it in from a PC afterwards. The PC version of "ci" will accept files with CR/LF line separators just fine even if RCS_LF_ONLY is used. But a Unix version of "ci" will probably not do that correctly and may even screw up the RCS file. * Note 4: RCS file path names Whenever a path name passed to a RCS program has /RCS/ in it, it is treated as a RCS (rather than a working) file. However, that /RCS/ component must be specified in upper case even on the PC operating systems where path names normally are not case sensitive. So, d:/work/RCS/foo.c and e:/proj/RCS/subproj/bar.c are recognized as RCS files while e:/proj/free/rcs/src/ci.c is recognized as a working file. In addition, all PC operating systems treat / in path names exactly like \ as a path name separator even though \ is much more widely known and used as such. However, under Unix / is the only path name separator and thus RCS uses it in both the programs and the documentation. Please don't be confused by this fact and keep in mind that it simply doesn't matter which one is used on the PC, at least as far as RCS is concerned. * Note 5: pseudo symbolic links RCS usually uses the ./RCS directory for separating the RCS files from the working files. There are tools like CVS to separate them further (allowing to put them in entirely different locations). For users of plain RCS, under Unix it is a widely used practice to make ./RCS a symbolic link to a different location in the directory tree in order to separate working and RCS files. There is now a new feature in RCS for the PC that mimics Unix-style symbolic links for the PC operating systems because they don't support symbolic links natively in most cases (you can have symbolic links if you use TVFS under OS/2 and you can use links under Windows NT on NTFS volumes). How does it work? When, instead of the ./RCS subdirectory, a regular file ./RCS exists, a single line of text is read from it and treated as the actual path name of the RCS directory. This can be either an absolute path name or a path name relative to the current directory. So if you are currently working in the directory E:\Work and have a file RCS there that contains the line N:\Project\Repository, then a command like "ci foobar.c" will check in foobar.c into the RCS file N:\Project\Repository\foobar.c,v as if ./RCS were a Unix-style symbolic link to that location. (Note: the ,v suffix is only available when long file names and the , character in file names are supported and the RCSINIT environment variable is set accordingly.) However, you must either use the ,v suffix for the RCS file names (set RCSINIT accordingly) or specify a path name in the ./RCS file that contains a /RCS/ component (/RCS/ must be in upper case), otherwise the RCS programs will abort because they can't determine where to store the RCS file (see above Note 4). * Note 6: rcsfreeze RCS contains one utility program (rcsfreeze) not written in the C language but as a bourne shell script. Even with a bourne shell for the PC it is not advisable to use it on the PC. Instead, I have rewritten the exact same semantics as a REXX procedure which can be used under OS/2 (1.x or 2.x). This REXX procedure is, of course, useless on MS-DOS for two reasons. First, unless you have IBM PC-DOS 7 (or newer) or a free REXX interpreter for DOS, you cannot even get it to run. Second, it depends on long filenames. If you have a REXX interpreter for Windows 95 or Windows NT, you may get it to run with some changes, but that has not been attempted so far. If you have IBM's ObjectRexx for Windows, that should work fine. Rewriting the program in C would solve that problem but would also cause extra work ... 4. About GNU diff ----------------- The RCS programs depend on the availability of the diff command under Unix, to compare two files (or two different revisions of a file in the context of RCS). Since that is not a standard command on PC operating systems, a version of it, the Free Software Foundation's GNU diff program, is included in this package. Please use only this diff program with RCS if possible. Since the reliability of RCS depends on that of the diff program very heavily, a few more words on this topic: This package supports PC's running OS/2 2.x (a 32-bit operating system), OS/2 1.x (a 16-bit operating system) and MS-DOS (a 16-bit operating system which, due to lack of any protection, allows implementing so-called DOS-extenders to run 32-bit programs on top of it). Windows 95/98 and NT are also supported. The GNU diff program (current version is 2.7.1), which works very well with RCS, makes assumptions about the programming model and addressing scheme in the operating system that only hold true for (at least) 32-bit environments (it uses rather large data structures, for example). It can be compiled for OS/2 2.x and Windows 95/NT without much effort. However, that is not the case for the 16-bit target systems. Because of this fact, long time ago I put a LOT of effort into porting the then current version (1.15) to let it run under OS/2 1.x and under MS-DOS, and testing it thoroughly. As you can see from the version numbers, it has undergone quite some development since then and porting the current version again to OS/2 1.x and MS-DOS would be a lot of work again. Because the functionality of diff that is used by RCS has not changed since 1.15 and since it does not make sense to spend a lot of time for the 16-bit target operating systems any longer, I decided to include *two* versions of GNU diff in this package. The old version, 1.15, is included for use under OS/2 1.x and MS-DOS in the "diff16" subdirectory and the current version (2.7.1) is included for use under OS/2 2.x and Win32 (and MS-DOS on 386 or better CPU's, see below) in the "diff" subdirectory. Since MS-DOS can be used to also run 32-bit programs with some kind of DOS extender, this current version of GNU diff can also be used under MS-DOS, if a 386 or higher CPU is available. This is very important because MS-DOS limits normal DOS programs to use only up to 640k of memory less the amount used for MS-DOS itself. And since some RCS programs call diff as a subprogram, even less memory is available for diff. So, naturally, the diff program when running under DOS can fail with "out of memory"-type errors if you try to use RCS commands on larger files. If that occurs, you should switch to the 32-bit version of diff, diff-32.exe and rename that to diff.exe. The RCS commands merge and rcsmerge depend on the availability of another related command, the diff3 program. This program is a three-way file comparison/merge program that in turn uses the diff program as a subprogram. A version of it is included with the GNU diff program in the same package. The user interface of the diff3 program was changed noticable between versions 1.15 and 2.1 and the RCS programs merge and rcsmerge require at least the diff3 program included with GNU diff 2.1. For this reason and since it is a much smaller program than diff itself, the GNU diff 2.6's diff3 program has been "ported back" to GNU diff 1.15 and is also used in the 16-bit target environments. To make a long story short, while the executables for the RCS programs for all target environments are made from the same source code, two different versions of GNU diff (1.15 and 2.7.1) are used to create the diff program's executables for the target platforms, 1.15 for 16-bit OS/2 1.x and MS-DOS and 2.7.1 for 32-bit OS/2 2.x, Win32 and MS-DOS on 386 and up PC's. 5. The emx toolkit and the emx and rsx DOS extenders ---------------------------------------------------- The emx 0.9d kit was used to create the 32-bit OS/2 2.x executables. This toolkit uses the GNU gcc compiler and is freely available to everyone. At least the 0.9b version is absolutely required or you can experience loss of data with the generated programs, if you want to recompile yourself. The emx kit also includes a DOS extender (emx.exe) that allows to run 32-bit emx-compiled programs under plain DOS and in VCPI environment (certain DOS "memory managers" provide this environment). To run them in a DPMI environment (such as in DOS windows under Microsoft Windows 3.x, OS/2 2.x, Windows 95 or NT), a different DOS extender is available, called rsx (rsx.exe). The emx-compiled 32-bit DOS programs automatically select the right extender to run on at runtime. So should you want to use 32-bit DOS emx-compiled RCS executables, you should make yourself familiar with those two extenders. The 32-bit DOS executables are not included in this package since the 16-bit ones should fit well in almost all DOS situations. If you want the 32-bit ones, you will have to recompile yourself. When using emx to compile RCS for DOS, no network support is available for technical reasons, however. But then, you don't gain much from them, since the RCS programs (as opposed to GNU diff) do not reach the MS-DOS 640k limit. You should be able to find the full packages of emx and rsx at the same places where you got this RCS package. Note that you may already have either emx.exe or rsx.exe or even both on your MS-DOS system because they are popular and you may be using some other software that depends on them. In such a case make sure you have only one copy (the newest one) on your system available via the PATH environment variable. I mentioned that the emx toolkit was used to create the OS/2 2.x 32-bit executables. To save disk space, the RCS (and GNU diff/diff3) programs are linked with the shared runtime library of emx, so you have only copy of it on disk and not one in each separate executable. This emx runtime consists of emx.dll and emxlibcs.dll. If you followed the installation instructions above, you should not notice any difference to "normal" statically linked programs. Since many free programs for OS/2 2.x are compiled with this compiler/toolkit, chances are big that you already have a copy of these DLL's on your system. Make sure you keep only one of them (the newest one) in a directory listed in the LIBPATH statement in your CONFIG.SYS. In addition, because the RCS programs use a common set of utility functions, these have been put into another shared library, rcslib.dll. This further reduces disk space requirements considerably. 6. Other compilers ------------------ The 16-bit DOS and OS/2 executables are compiled with Microsoft C 6.00A, an environment that is no longer maintained by Microsoft but works well enough to keep it. Newer Microsoft compilers may work for DOS but are untested. The Visual C++ 4.0 (Microsoft C/C++ 10.0) can be used for Win32 executables, it supports even the shared rcslib.dll method like emx does for OS/2 and RSX/Win32. However, I haven't tested that recently and have no idea if newer Microsoft compilers work for RCS. The Watcom C/C++ 11.0 compiler can be used for all target environments. However, the code it generates is less compact than that created by the other compilers so no included executable sets were generated with it, with one exception. The diff-32.exe in tbe bindos subdirectory was created with the 32-bit DOS (DOS4G/W) target of the Watcom compiler, but a different (free) DOS extender was used instead of the huge DOS4GW.EXE extender that Watcom includes with their compiler. Instead of that, PMODE/W 1.33 has been used. 7. Documentation ---------------- The manual pages for the RCS and GNU diff programs and additional documents are available in the "doc" and "man" subdirectories in various formats. There are plain ASCII files for reading with any file browser or editor and PostScript (TM) files for printing on a PostScript printer or viewing/printing with GhostScript or GSView. They were all created with the OS/2 version of the GNU groff text formatter from the "source" documents also included in this package (in the "rcs\man" subdirectory). Several documents have also been converted to and provided in GNU info, IBM .INF and HTML format. If you are not yet familiar with RCS and/or GNU diff, please read these documentation files very carefully. I repeat, read them and read them entirely and carefully before starting to use these tools. OK? 8. Problems ----------- Please read this file carefully. If you have problems using RCS, please first check it again to see if you forgot something and also check the RCS documentation in the "doc" and "man" subdirectories. If that doesn't help, send a short and descriptive e-mail message. Don't laugh, you don't know how often I get e-mail with contents like "the foobar program you ported to OS/2 does not work, what should I do?" without any more details. Remember that I can't read your mind, especially not over such long distances. :-) 9. Author / Address ------------------- Walter F. Tichy wrote the original version of RCS. Paul Eggert wrote the changes for RCS version 5.x, and maintains it. This port of RCS 5.7 to MS-DOS and OS/2 is based on an earlier release (RCS 5.6.3) made by Paul Eggert, Frank Whaley and Kai Uwe Rommel. The PC related changes for 5.7, for the DOS, Win32 and OS/2 32-bit targets, the networking support and the ports of GNU diff 1.15 and 2.7.1 were made by Kai Uwe Rommel. /* Kai Uwe Rommel ARS Computer & Consulting GmbH * * rommel@ars.de (http://www.ars.de) Muenchen, Germany * * rommel@leo.org (http://www.leo.org/pub/comp/os/os2 maintenance) */