OS/2 Shareware BBS: 10 Tools/10-Tools.zip/rcs567s.zip/README

Text File | 1994-08-01 | 19KB | 429 lines

README for RCS 5.6.7.4 for PC's running under OS/2 or MS-DOS
------------------------------------------------------------

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

  ftp.informatik.tu-muenchen.de:/pub/comp/os/os2/gnu/devtools/rcs567pc.zip

As long as the author of this revision maintains the OS/2 and MS-DOS
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.cdrom.com:/pub/os2/... (see 00index.txt file for exact location)

which is the best known OS/2 ftp archive site on the Internet.

Related packages that may be of interest for RCS users include (all
path names relative to ftp.informatik.tu-muenchen.de:/pub/comp/os/os2/):

- CVS 1.3 (gnu/devtools/cvs13p8b.zip and cvs13p8s.zip)

  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.71 (gnu/devtools/gnumake.zip)

  This is a "make" program that knows how to access source files
  maintained with RCS without need to specify rules.

- GNU Emacs 19.25 (gnu/emacs-19/*)

  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 used to create RCS for OS/2 and MS-DOS:

- the emx programming environment (gnu/emx+gcc/*)

  The emx environment (current version 0.8h, fix level 9) 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,
  gas assembler, gdb debugger and libg++ class library.

- the rsx DOS extender (gnu/emx+gcc/contrib/dpmigcc4.zip)

  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).


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.6.7.4

rcsfront    the source code for RCSFRONT, a small front end tool for
        easier management of a collection of files under RCS control

diff, diff16    the source code for the GNU diff program, an important tool
        required for RCS (two versions, see below)

doc        preformatted documentation (plain text and PostScript format)

bin32        OS/2 2.x executable programs (32-bit)
bin16        OS/2 1.x executable programs (16-bit)
bindos        MS-DOS executable programs (16-bit, but see below)

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"
subdirectory. 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.

b) The TZ environment variable should contain your proper time zone
   definition. If you use the OS/2 32-bit executables, you can also
   use the EMXTZ variable if some other software on your machine
   requires a more complicated value of this variable which programs
   compiled with emx (see below) don't understand.

   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 europe time)

   However, if you work strictly local and do not exchange source code
   with people in other time zones, you may omit the TZ definition,
   although that is NOT recommended.

c) The RCSINIT variable can contain options 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.

   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 have a
   suffix of ",v". For this case, use "SET RCSINIT=-x,v/".

   See the RCS manual pages for details about all available options.

d) (this is optional, for OS/2 2.x 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.

After these steps, you should be able to use the RCS commands.


3. 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). It allows shared use of RCS files in such heterogenous
networks, for example.

* 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/Requester
- Microsoft LAN Manager Server/Client
- 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
- IBM PC Network
- Microsoft LAN Manager Client
- Microsoft Windows for Workgroups
- Novell NetWare Client

and any compatible product.

Note that network support in RCS means only that the RCS commands can
retrieve the current user name from the network software, nothing
more.

* Note 2: binary files

This version of RCS for the PC does not support revision control of
binary files. The main goal 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, breaks binary files. In a future version of
RCS the concept of binary files may be introduced into the syntax of
RCS files, to solve this problem. Until then, you can't check in/out
binary files (such as icons or other resource data files), unless you
use some kind of program to convert them into text format (such as
uuencode).


4. RCSFRONT
-----------

The RCSFRONT program, written by Jason P. Winters and Craig J. Kim is
distributed by the Free Software Foundation. It allows checking in/out
whole collections of files or even whole directory trees with RCS. It
was heavily modified to run on the PC.

Of course, RCSFRONT is no substitute for more sophisticated software
that builds on RCS for similar goals, such as CVS. But it may be
sufficient for use on standalone systems or single-programmer
projects. See its manual page in the "doc" subdirectory for more
details.


5. 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.

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).

The GNU diff program (current version is 2.6), which works very well
with RCS is inherently a 32-bit program (it uses rather large data
structures, for example). It can be compiled for OS/2 2.x 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.

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.6, is included for use under
OS/2 2.x (and MS-DOS on 386 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 in the "bindos" subdirectory 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.6 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, RCSFRONT and diff3 for all three target environments are
made from the same source code, two different versions of GNU diff
(1.15 and 2.6) are used to create the diff program's executables for
the three platforms, 1.15 for 16-bit OS/2 1.x and MS-DOS and 2.6 for
32-bit OS/2 2.x and MS-DOS on 386 and up PC's.


6. The emx toolkit and the emx and rsx DOS extenders
----------------------------------------------------

The 32-bit diff program for dos, diff-32.exe, was created with the
same compiler and toolkit (emx) that was used to create the 32-bit
OS/2 2.x executables. That has saved a lot of extra work.
Specifically, the emx 0.8h kit with patch 8 applied has been used. This
toolkit uses the GNU gcc compiler and is freely available to everyone.

The emx kit includes a DOS extender (emx.exe) that allows to run
32-bit programs like diff-32.exe under plain DOS and in VCPI
environment (certain DOS "memory managers" provide this
environment). To run diff-32.exe in a DPMI environment (such as in DOS
windows under Microsoft Windows 3.x), a different DOS extender is
available, called rsx (rsx.exe). The diff-32.exe program automatically
selects the right extender to run on at runtime. Both extenders are
included in the "bindos" subdirectory in this packages as well as
their COPYING and README files in the root directory of this
package. 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 RCSFRONT 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 emxlibc.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. Also, the GNU regular expression library used by GNU
diff is also linked in a separate DLL, gnuregex.dll, since it is quite
large and many of the FSF's programs use it, which are available for
OS/2. You need only one copy of it on your system too.


7. Documentation
----------------

The manual pages for RCS and RCSFRONT programs and additional
documents are available in the "doc" subdirectory in two formats: as
plain ASCII files for reading with a browser and in PostScript (TM)
format for printing on a PostScript printer or viewing/printing with
GhostScript or GSView/PM. 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" and "rcsfront"
subdirectories).

The documentation for GNU diff and diff3, version 2.6, is available as
a TeXinfo source file in the "diff" subdirectory. A preformatted
version in GNU Info format is in the "doc" subdirectory for reading
with either the GNU Emacs editor or the standalone GNU info browser,
but it can also be viewed with any normal file browser. A PostScript
version of it, made with emTeX and dvips, is also in the "doc"
subdirectory.

If you are not yet familiar with RCS and/or GNU diff, please read this
documentation files.


8. Recompilation
----------------

In case you want to recompile: the 32-bit OS/2 2.x programs and the
32-bit MS-DOS GNU diff program are generated with the emx 0.8h toolkit
(which uses gcc 2.5.7 or 2.5.8). Not only is the 0.8h version of emx
required but also fix level 8 for it is absolutely required or you
will experience crashes in the generated programs.

With emx you could even generate 32-bit versions of all RCS programs
and also RCSFRONT for MS-DOS on a 386 or larger CPU, but you don't
gain anything from them, since these programs do not reach the MS-DOS
640k limit. In addition, when using emx to compile RCS for DOS, no
network support is available for technical reasons.

For the 16-bit OS/2 1.x and MS-DOS programs, Microsoft C 6.00A was
used. For MS-DOS, you should also be able to use MS C/C++ 7.00 or MS
Visual C++ with only minor changes (not tested, but MS's C compilers
are usually upwardly compatible).

In the "diff16" directory, there are separate Makefile.dos and
Makefile.os2 file for use with the NMAKE program included with
Microsoft C. In the "rcsfront" and "diff" directories there is one
Makefile in each with multiple targets.

The Makefile for RCS itself is in the "rcs\src\ms" subdirectory
together with a few more supporting files.


9. 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" subdirectory. Especially the emx/rsx
runtime stuff can be confusing sometimes.

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 distances. :-)


10. Author / Address
--------------------

Walter F. Tichy wrote the original version of RCS.
Paul Eggert wrote the changes for RCS version 5.x, and helps maintain it.

This port of RCS 5.6.7.4 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 DOS and OS/2 related changes for 5.6.7.4, for the new DOS and OS/2
32-bit targets, the new networking support and the ports of RCSFRONT
and GNU diff 1.15 and 2.6 were made by Kai Uwe Rommel.


/* Kai Uwe Rommel                                      Muenchen, Germany *
 * [e-mail]                              CompuServe 100265,2651 *
 * [e-mail]                  Fax [phone] */