OS/2 Shareware BBS: 22 gnu/22-gnu.zip/rcs57pc3.zip/README

Text File | 1999-03-28 | 28KB | 646 lines

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 <rcsfile>". 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 *
 * [e-mail] (http://www.ars.de)             Muenchen, Germany *
 * [e-mail] (http://www.leo.org/pub/comp/os/os2 maintenance) */