rcs/dist/INSTALL.RCS

Installation instructions specific to RCS

	Id: INSTALL.RCS,v 1.14 1995/06/16 06:19:24 eggert Exp

	Copyright 1991, 1992, 1993, 1994, 1995 Paul Eggert
	Distributed under license by the Free Software Foundation, Inc.

	This file is part of RCS.

	RCS is free software; you can redistribute it and/or modify it
	under the terms of the GNU General Public License as published
	by the Free Software Foundation; either version 2, or (at your
	option) any later version.

	RCS is distributed in the hope that it will be useful, but
	WITHOUT ANY WARRANTY; without even the implied warranty of
	MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
	GNU General Public License for more details.

	You should have received a copy of the GNU General Public License
	along with RCS; see the file COPYING.
	If not, write to the Free Software Foundation,
	59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.

	Report problems and direct all questions to:

		rcs-bugs@cs.purdue.edu

__________

This file contains installation instructions specific to RCS.
Please see the file INSTALL for generic installation instructions.


__________

Prerequisites and compatibility issues

RCS requires a diff that supports the -n option.
Get GNU diffutils (version 2.7 or later) if your diff lacks -n.

RCS works best with a diff that supports -a and -L,
and a diff3 that supports -A, -E and -m.
GNU diffutils supports these options.

RCS version 5 reads RCS files written by any RCS version released since 1982.
It also writes RCS files that these older versions of RCS can read,
unless you use one of the following new features:

	checkin dates after 1999-12-31
	checking in non-text files
	identifiers containing `.' or non-Ascii bytes, or starting with a digit
	rcs -bX, where X is nonempty
	rcs -kX, where X is not `kv'
	RCS files that exceed hardcoded limits in older RCS versions

A working file written by RCS 5.5 or later contains four-digit years in its
keyword strings.  If you check out a working file with RCS 5.5 or later,
an older RCS version's `ci -k' may insist on two-digit years.
Similarly, a working file written with -zZONE contains times
in its keyword strings that older `ci -k's may not understand.
Work around this with `co -V4 -z', or edit the working file.

RCS should run on any host that conforms to the Posix 1003.1-1990 standard.
It also runs on a wide variety of non-Posix hosts.


__________

Configuration and installation

See INSTALL for general instructions on configuring and building RCS.
RCS's `configure' script has the option `--with-diffutils',
and is affected by environment variables;
see `Configuration environment' below.

If your system type is in the following list,
look for the corresponding strings in the notes below before configuring.

	system type - identifiers
	------------------------
	AIX 3.2 - --prefix=/usr has_seteuid
	GCC 2.5.8 Intel x86 - CFLAGS
	HP/Apollo DomainOS - has_vfork
	HP-UX 8.07 and 9.* - has_mmap
	Solaris 2.4 - has_mmap
	SCO Unix V.3.2 - has_rename
	Ultrix - has_seteuid

RCS configuration is a two-step process:
general configuration as described in INSTALL,
and the build of src/conf.h, which is done by `make'.
The second step runs several test programs, so if you are cross-compiling,
create a src/conf.h appropriate for the target host before invoking `make'.

If making src/conf.h fails, look in src/conf.err to see what went wrong.
Check the resulting src/conf.h for plausibility,
e.g. by running `diff src/conf.heg src/conf.h'; see ``src/conf.h notes'' below.
If src/conf.h is wrong, and the mistake isn't listed in ``src/conf.h notes'',
there is a bug in src/conf.sh; please report it.
You can patch src/conf.h if you're in a hurry, but it's better to fix it;
look at src/a.h and src/conf.err for ideas.
If all else fails, copy src/conf.heg to src/conf.h and edit it by hand.

If installation succeeds, make `installcheck';
if this fails, make `installdebug' for detailed info.

If you want to test RCS before installing it,
build it from scratch with `cd src; make RCSPREFIX= bindir=. installcheck'.
Be sure rebuild RCS without these options before actually installing it.

If you want to maintain RCS with itself,
preserve the original revision numbers, dates, etc.
by checking the files in with the -k option.


----

Configuration note

Do not configure with --prefix=/ or --prefix=/usr in AIX.
An AIX boot shell script (/etc/rc.boot4 in AIX 3.2) invokes `merge',
meaning /etc/merge, and fails if RCS merge is installed in /bin or /usr/bin.
IBM says that installing new programs into /usr/bin is a customer error (!).


__________

Configuration environment

The configuration procedure normally inspects the current host
to determine how RCS is to be built.
The environment variables listed in this section override this default.
If you configure with the option `--with-diffutils',
unset environment variables whose names start with `DIFF'
are assumed to have values appropriate for a GNU diffutils
installed into the same location as RCS;
this is a recommended configuration.

CC is the name of your C compiler.

CPPFLAGS are C preprocessor options.

CFLAGS are C compiler options that do not affect correctness,
typically options that affect optimization or debugging.
Omit -O if your compiler's optimizer is not trustworthy (e.g. GCC 2.5.8 x86).
If your ancient BSD compiler has the -R option, -R can improve performance by
making all initialized data read-only (not just string literals);
modern compilers don't need this, since they have `const'.

DIFF is the name of your diff program.
It's normally best to use GNU diffutils.
If DIFF is not an absolute pathname, setuid execution cannot be used,
and execution may be a bit slower.
If you change DIFF after starting a build,
make sure you rebuild conf.h afterwards;
otherwise you may introduce a security hole.
On some versions of Unix, the standard diff does not support RCS
and you must instead use diffutils, or something like /usr/lib/rdiff.

DIFFFLAGS are diff's options for RCS format output, probably -n.
If available, also include the -a option for comparing arbitrary files.

DIFF_L is 1 if diff and diff3 understand the -L LABEL option
for labeling context diff output, 0 otherwise.
This option was introduced with GNU diffutils 2.1.

DIFF_SUCCESS, DIFF_FAILURE, and DIFF_TROUBLE are integer constants
representing diff's exit status when it finds
no differences, some differences, or trouble respectively.
The first two should be <stdlib.h>'s EXIT_SUCCESS and EXIT_FAILURE
but this doesn't work on some broken hosts.

DIFF3 is the name of the diff3 program.
With GNU diffutils, this is simply its user-visible diff3 program.
But with traditional diff3 it is the name of the undocumented diff3 auxiliary,
whose name is /usr/lib/diff3 or /usr/5lib/rdiff3prog or something similar.

DIFF3_BIN is 1 if DIFF3 is the user-visible GNU diff3 program (see DIFF3).
Before setting this to 1, make sure your diff3 understands -a, -L, and and -m;
e.g. the command `echo x | diff3 -m -L 0 -L 1 -L 2 /dev/null /dev/null -'
should output `x'.

ED is the name of the standard Unix line editor.
It is used only if DIFF3_BIN is 0.

INSTALL is the command that installs commands, e.g. `../install-sh'.
INSTALL_DATA installs data, and
INSTALL_PROGRAM installs programs.

PIC is the name of your pic program, configured to avoid extensions
so that a portable man page is generated.
This is typically GNU pic with the `-n' option,
or traditional pic with `-D'.
It is used only if you edit the documentation or make `maintainer-clean'.

prefix and exec_prefix establish the binary installation directory;
they are affected by the --prefix and --exec-prefix option of `configure'.

SENDMAIL is a comma-separated list of strings (using C syntax)
that are a command to send mail.
The name of the addressee will be appended as a separate argument,
and the standard input will be the message
(first line `Subject: xxxx', second line empty).
If your host cannot send mail, leave SENDMAIL empty.


__________

src/Makefile notes

Many of the src/Makefile variables are set by `configure' as described above.
The notes below describe variables that may need to be edited by hand
in unusual installations.

ALL_CFLAGS are all the options passed to the C compiler.

COMPAT2 is 1 if you still have version 2 RCS files around.
(Version 2 became obsolete in 1982, so this isn't likely.)
COMPAT2 assures that version 2 RCS files can still be read.
When you have the new RCS installed, rename old version 2 RCS files as follows.
Suppose the working file was `f.c';
rename the RCS file `f.c.v' to `f.c,v', and the RCS file `f.v' to `f.c,v'.
Thus suffixes are no longer dropped and RCS files end in `,v' rather than `.v'.
After all version 2 RCS files have been updated with new versions of ci or rcs,
you can remake RCS with COMPAT2 set to 0.

DEFS are configuration options for the C preprocessor.
It should include any extra -D and -I options needed on your system.

LDFLAGS are the loader flags you need, e.g. -i, -n, -s, -x.

LIBOBJS are any other object files you need to link.

LIBS are the loader libraries you need, e.g. -lbsd, -lBSD, -ljobs, -lPW, -lx.

LINK is the command used to link together an executable.

LINT is the name and usual arguments of your lint program.

RCSPREFIX is the prefix for subsidiary RCS commands like ci.
If empty, RCS will search the PATH for these commands;
this lets you move RCS commands after building them, and permits
multiple instances of setuid RCS commands on the same host for different users.
If nonempty, it should be a path followed by /;
this makes RCS look in just one place, and makes execution faster.

REMOVE is how to remove a file.

o is the filename extension your host uses for object files.
It includes the `.'.  It is typically `.o' on Unix hosts.

x is the filename extension your host uses for executables.
It includes any `.'.  It is empty on Unix hosts,
which traditionally lack extensions on executables.


__________

src/conf.h notes

See src/conf.sh for details about the definitions in src/conf.h.
Comments below cover unusual situations requiring hand patches to src/conf.h.

bad_NFS_rename - Some buggy NFS file servers (e.g. some NAC releases)
can report that rename(A,B) succeeded even though it failed.
Set bad_NFS_rename to nonzero to work around the problem.
Warning: the workaround introduces a rare race condition
that can falsely report I/O errors;
this is why the workaround is disabled unless you specify otherwise.

const - Some hosts support `const' but complain about it, perhaps because
system headers are wrong.  If you can't stand the complaints,
try `#define const /*empty*/'.

has_mmap - For speed, RCS uses the `mmap' system call
if it is available and the Mach `map_fd' system call is not.
Unfortunately, many mmap implementations are broken.
src/conf.sh guesses based on tests and on mmap bugs reported by RCS users;
you may want to double-check its results.
For instance, mmap does not work properly in HP-UX 8 or 9, or in Solaris 2.4,
without kernel patches; see src/conf.sh for details.
We don't know details about the bugs, so we can't test for them automatically.

has_NFS - Set this if the target host might use NFS.
NFS's ``stateless server'' protocol has well-known problems with
the non-idempotent operations link(), rename(), and unlink().
For example, unlink() can run twice on the NFS server,
causing the client to think that the unlink failed with errno==ENOENT.
has_NFS enables code that works around these problems.
However, has_NFS does not work around NFS implementation bugs;
if your NFS implementation is buggy, get another!
For example, make sure that your NFS uses UDP checksums, if it uses UDP.
Modern systems checksum by default; ask your vendor if you're not sure.

has_rename - This should be 0 in SCO Unix V.3.2.  Its NFS rename() is broken,
but if you run src/conf.sh in a non-NFS filesystem, it thinks rename() works.

has_seteuid - You have to worry about this only if you plan to run RCS setuid.
has_seteuid should be 1 only if your seteuid lets you switch back and
forth between any pair of users as specified in Posix 1003.1a Draft 5.
On some older systems (e.g. SunOS 3.5) seteuid doesn't allow this.
One must be root to test this reliably, so src/conf.sh just guesses.
If has_seteuid==0, perhaps you can use setreuid instead (see below).
Otherwise, the next best thing is saved setuid semantics
(a Posix 1003.1-1990 option), because this fails only if you run as root.
You may need to compile with `cc -systype sysv' (some Mips OS variants)
or `cc -YPOSIX' (some Ultrix variants) for best results here.
Don't run RCS setuid under AIX 3.2 if you use NFS, since it's badly broken.
To see the AIX 3.2 bug, run the following program setuid X where the NFS file
"abc" already exists, owned by X, permission -rw-r--r--, and where
the invoker is not X.  The program fails with "fclose: Permission denied".
	#include <stdio.h>
	int main() {
		 FILE *f = fopen("abc", "w");
		 setuid(getuid());
		 fputc('\n', f);
		 if (fclose(f) != 0)
			 perror("fclose");
	}

has_setreuid - You have to worry about this only if you plan to run RCS setuid
and if has_seteuid==0.  On some older BSDish systems, the setreuid system
call lets you swap real and effective users even if one of them is root.
One must be root to test this reliably, so src/conf.sh always guesses that
it doesn't work.  Set it to 1 by hand if you know that it works.

has_vfork - This should be 0 in some variants of HP/Apollo DomainOS.
(The `uname -a' command reported `10.3.5 sys5.3' on one such variant.)
Its vfork causes a system crash; you'll have to change src/conf.sh to output
`#define has_vfork 0' without actually trying vfork.

large_memory - This should be 1 if main memory is large enough to hold entire
copies of RCS files, perhaps because virtual memory is available.

_POSIX_SOURCE must be #defined in a strict Standard C environment,
because otherwise <stdio.h> cannot define useful identifiers like fileno.
Avoid defining _POSIX_SOURCE if possible,
because it can disable useful non-Posix features in your host.
Perhaps you can remove the need for _POSIX_SOURCE
by supplying an option to your compiler to makes it less strict.
You may also have to pay attention to other symbols, e.g. _XOPEN_SOURCE.

TZ_must_be_set - set this to 1 on hosts where gmtime() yields bogus
values unless the TZ environment variable is set.

volatile - See `const'.  E.g. `volatile sig_atomic_t' is conforming, but some
buggy hosts complain.  Also, Ultrix 4.0 Mips CC 2.0 has buggy volatile support.

X_DEFAULT - This is normally ",v/" on Unix hosts, and "" on hosts that
do not allow commas in file names (e.g. DOS).