RCS configuration and installation instructions

	$Id: INSTALL,v 1.11 1994/03/17 14:05:48 eggert Exp $

	Copyright 1991, 1992, 1993, 1994 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, 675 Mass Ave, Cambridge, MA
	02139, USA.

	Report problems and direct all questions to:

		rcs-bugs@cs.purdue.edu


__________

Prerequisites and compatibility issues

RCS requires a diff that supports the -n option.
Get GNU diffutils (version 1.15 or later) if your diff lacks -n.
For best results, use GNU diffutils 2.6 or later.

RCS works best with a diff that supports -a and -L,
and a diff3 that supports -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 times after 1999/12/31 23:59:59 UTC
	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.


__________

Configuration and installation

For Posix and near-Posix hosts, configure by editing Makefile,
commenting out wrong lines and uncommenting right ones.
See ``Makefile notes'' below for advice.

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

	system type - identifiers
	------------------------
	AIX 3.2 - BINDIR has_seteuid
	HP/Apollo DomainOS - has_vfork
	SCO Unix V.3.2 - has_rename
	Ultrix - has_seteuid

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

If all went well, make `install'.
If installation succeeds, make `installtest';
if this fails, make `installdebug' for detailed info.

If you want to test RCS before installing it,
you must set RCSPREFIX to be empty, make RCS from scratch,
and run `make BINDIR=. installtest'.
Be sure to restore RCSPREFIX and rebuild RCS before 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.


__________

Makefile notes

BINDIR is where the RCS commands will be installed.
Do not set this to /bin or /usr/bin 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 (!).

CC is the name of your C compiler.

CC_D is a list of extra options for the C preprocessor.
It should include any extra -D and -I options needed on your system.

CC_O is the C compiler options that affect just compilation and assembly;
not preprocessing, linking or linting.
If your compiler has the BSD -R option, -R can improve performance by
making all initialized data read-only (not just string literals);
this is not worth worrying about if your compiler also supports `const'.

CC_W is the list of C compiler options to enable
warnings about questionable constructs in the RCS source code.

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.

DESTBINDIR is where RCS executables are copied when you type `make install'.
This may be different from BINDIR due to installation staging.

DIFF is the name of your diff program.
It's normally best to use GNU diffutils.
If you override DIFF, 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 use something like /usr/lib/rdiff instead.

DIFFPREFIX act likes RCSPREFIX, except it applies to subsidiary diffs,
not to subsidiary RCS commands.  It must be nonempty if setuid is to be used.

DIFF_FLAGS 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 understands the -L option for labeling context diff output.

DIFF_SUCCESS, DIFF_FAILURE, 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 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.
With traditional diff3, this is not the user-visible diff3 program;
instead, it this is the name of the undocumented diff3 auxiliary program,
whose name is /usr/lib/diff3 or /usr/5lib/rdiff3prog or something similar.

DIFF3_A is 1 if diff3 understands the -A (--show-all) option, 0 otherwise.

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 /dev/null /dev/null -' should output `x'.

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

EXECUTABLE_PERMISSIONS are the options given to INSTALL for executable files
on BSD Unix sites.  Watch out for `-g staff' if you don't have a staff group,
or if your installation program doesn't have a -g option.

INSTALL is the command that installs commands.

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

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

MAKE is defined here because ancient `make' programs don't define it.

OTHER_OBJECT are any other object files you need to link.

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.

SENDMAIL is a comma-separated list of strings 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.

TESTPREFIX is the prefix for test commands.

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 the `.'.  It is empty on Unix hosts,
which traditionally lack extensions on executables.


__________

conf.h notes

See conf.sh for details about the definitions in conf.h.
Comments below cover unusual situations that can require hand patches to conf.h.

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_NFS - Set this if the target host might use NFS.
You should make sure that your NFS uses UDP checksums, if it uses UDP.
Most modern systems checksum by default; ask your vendor if you're not sure.
NFS's stateless server model has well-known problems with
the non-idempotent operations link(), rename(), and unlink().
For example, unlink() can run twice on the file server,
causing the client to think that the unlink failed with errno==ENOENT.
has_NFS enables code that works around these problems.

has_rename - This should be 0 in SCO Unix V.3.2.  Its NFS rename() is broken,
but if you run conf.sh in a non-NFS filesystem, conf.sh 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 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 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 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 names 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.

text_work_stdio - This option makes sense only on non-Posix hosts that
distinguish between text and binary I/O, e.g. DOS.  Set this option if
you want to use text I/O for working files, but binary I/O for RCS
files.  If set, RCS does not support non-text working files, but RCS
files are portable to other hosts across binary network file systems
like NFS.  If not set, RCS supports non-text working files, but RCS
files are not portable to Posix hosts.

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.
