source: trunk/third/rcs/INSTALL.RCS @ 9047

Revision 9047, 14.4 KB checked in by ghudson, 28 years ago (diff)
This commit was generated by cvs2svn to compensate for changes in r9046, which included commits to RCS files with non-trunk default branches.
Line 
1Installation instructions specific to RCS
2
3        $Id: INSTALL.RCS,v 1.1.1.1 1996-10-04 05:52:41 ghudson Exp $
4
5        Copyright 1991, 1992, 1993, 1994, 1995 Paul Eggert
6        Distributed under license by the Free Software Foundation, Inc.
7
8        This file is part of RCS.
9
10        RCS is free software; you can redistribute it and/or modify it
11        under the terms of the GNU General Public License as published
12        by the Free Software Foundation; either version 2, or (at your
13        option) any later version.
14
15        RCS is distributed in the hope that it will be useful, but
16        WITHOUT ANY WARRANTY; without even the implied warranty of
17        MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
18        GNU General Public License for more details.
19
20        You should have received a copy of the GNU General Public License
21        along with RCS; see the file COPYING.
22        If not, write to the Free Software Foundation,
23        59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.
24
25        Report problems and direct all questions to:
26
27                rcs-bugs@cs.purdue.edu
28
29__________
30
31This file contains installation instructions specific to RCS.
32Please see the file INSTALL for generic installation instructions.
33
34
35__________
36
37Prerequisites and compatibility issues
38
39RCS requires a diff that supports the -n option.
40Get GNU diffutils (version 2.7 or later) if your diff lacks -n.
41
42RCS works best with a diff that supports -a and -L,
43and a diff3 that supports -A, -E and -m.
44GNU diffutils supports these options.
45
46RCS version 5 reads RCS files written by any RCS version released since 1982.
47It also writes RCS files that these older versions of RCS can read,
48unless you use one of the following new features:
49
50        checkin dates after 1999-12-31
51        checking in non-text files
52        identifiers containing `.' or non-Ascii bytes, or starting with a digit
53        rcs -bX, where X is nonempty
54        rcs -kX, where X is not `kv'
55        RCS files that exceed hardcoded limits in older RCS versions
56
57A working file written by RCS 5.5 or later contains four-digit years in its
58keyword strings.  If you check out a working file with RCS 5.5 or later,
59an older RCS version's `ci -k' may insist on two-digit years.
60Similarly, a working file written with -zZONE contains times
61in its keyword strings that older `ci -k's may not understand.
62Work around this with `co -V4 -z', or edit the working file.
63
64RCS should run on any host that conforms to the Posix 1003.1-1990 standard.
65It also runs on a wide variety of non-Posix hosts.
66
67
68__________
69
70Configuration and installation
71
72See INSTALL for general instructions on configuring and building RCS.
73RCS's `configure' script has the option `--with-diffutils',
74and is affected by environment variables;
75see `Configuration environment' below.
76
77If your system type is in the following list,
78look for the corresponding strings in the notes below before configuring.
79
80        system type - identifiers
81        ------------------------
82        AIX 3.2 - --prefix=/usr has_seteuid
83        GCC 2.5.8 Intel x86 - CFLAGS
84        HP/Apollo DomainOS - has_vfork
85        HP-UX 8.07 and 9.* - has_mmap
86        Solaris 2.4 - has_mmap
87        SCO Unix V.3.2 - has_rename
88        Ultrix - has_seteuid
89
90RCS configuration is a two-step process:
91general configuration as described in INSTALL,
92and the build of src/conf.h, which is done by `make'.
93The second step runs several test programs, so if you are cross-compiling,
94create a src/conf.h appropriate for the target host before invoking `make'.
95
96If making src/conf.h fails, look in src/conf.err to see what went wrong.
97Check the resulting src/conf.h for plausibility,
98e.g. by running `diff src/conf.heg src/conf.h'; see ``src/conf.h notes'' below.
99If src/conf.h is wrong, and the mistake isn't listed in ``src/conf.h notes'',
100there is a bug in src/conf.sh; please report it.
101You can patch src/conf.h if you're in a hurry, but it's better to fix it;
102look at src/a.h and src/conf.err for ideas.
103If all else fails, copy src/conf.heg to src/conf.h and edit it by hand.
104
105If installation succeeds, make `installcheck';
106if this fails, make `installdebug' for detailed info.
107
108If you want to test RCS before installing it,
109build it from scratch with `cd src; make RCSPREFIX= bindir=. installcheck'.
110Be sure rebuild RCS without these options before actually installing it.
111
112If you want to maintain RCS with itself,
113preserve the original revision numbers, dates, etc.
114by checking the files in with the -k option.
115
116
117----
118
119Configuration note
120
121Do not configure with --prefix=/ or --prefix=/usr in AIX.
122An AIX boot shell script (/etc/rc.boot4 in AIX 3.2) invokes `merge',
123meaning /etc/merge, and fails if RCS merge is installed in /bin or /usr/bin.
124IBM says that installing new programs into /usr/bin is a customer error (!).
125
126
127__________
128
129Configuration environment
130
131The configuration procedure normally inspects the current host
132to determine how RCS is to be built.
133The environment variables listed in this section override this default.
134If you configure with the option `--with-diffutils',
135unset environment variables whose names start with `DIFF'
136are assumed to have values appropriate for a GNU diffutils
137installed into the same location as RCS;
138this is a recommended configuration.
139
140CC is the name of your C compiler.
141
142CPPFLAGS are C preprocessor options.
143
144CFLAGS are C compiler options that do not affect correctness,
145typically options that affect optimization or debugging.
146Omit -O if your compiler's optimizer is not trustworthy (e.g. GCC 2.5.8 x86).
147If your ancient BSD compiler has the -R option, -R can improve performance by
148making all initialized data read-only (not just string literals);
149modern compilers don't need this, since they have `const'.
150
151DIFF is the name of your diff program.
152It's normally best to use GNU diffutils.
153If DIFF is not an absolute pathname, setuid execution cannot be used,
154and execution may be a bit slower.
155If you change DIFF after starting a build,
156make sure you rebuild conf.h afterwards;
157otherwise you may introduce a security hole.
158On some versions of Unix, the standard diff does not support RCS
159and you must instead use diffutils, or something like /usr/lib/rdiff.
160
161DIFFFLAGS are diff's options for RCS format output, probably -n.
162If available, also include the -a option for comparing arbitrary files.
163
164DIFF_L is 1 if diff and diff3 understand the -L LABEL option
165for labeling context diff output, 0 otherwise.
166This option was introduced with GNU diffutils 2.1.
167
168DIFF_SUCCESS, DIFF_FAILURE, and DIFF_TROUBLE are integer constants
169representing diff's exit status when it finds
170no differences, some differences, or trouble respectively.
171The first two should be <stdlib.h>'s EXIT_SUCCESS and EXIT_FAILURE
172but this doesn't work on some broken hosts.
173
174DIFF3 is the name of the diff3 program.
175With GNU diffutils, this is simply its user-visible diff3 program.
176But with traditional diff3 it is the name of the undocumented diff3 auxiliary,
177whose name is /usr/lib/diff3 or /usr/5lib/rdiff3prog or something similar.
178
179DIFF3_BIN is 1 if DIFF3 is the user-visible GNU diff3 program (see DIFF3).
180Before setting this to 1, make sure your diff3 understands -a, -L, and and -m;
181e.g. the command `echo x | diff3 -m -L 0 -L 1 -L 2 /dev/null /dev/null -'
182should output `x'.
183
184ED is the name of the standard Unix line editor.
185It is used only if DIFF3_BIN is 0.
186
187INSTALL is the command that installs commands, e.g. `../install-sh'.
188INSTALL_DATA installs data, and
189INSTALL_PROGRAM installs programs.
190
191PIC is the name of your pic program, configured to avoid extensions
192so that a portable man page is generated.
193This is typically GNU pic with the `-n' option,
194or traditional pic with `-D'.
195It is used only if you edit the documentation or make `maintainer-clean'.
196
197prefix and exec_prefix establish the binary installation directory;
198they are affected by the --prefix and --exec-prefix option of `configure'.
199
200SENDMAIL is a comma-separated list of strings (using C syntax)
201that are a command to send mail.
202The name of the addressee will be appended as a separate argument,
203and the standard input will be the message
204(first line `Subject: xxxx', second line empty).
205If your host cannot send mail, leave SENDMAIL empty.
206
207
208__________
209
210src/Makefile notes
211
212Many of the src/Makefile variables are set by `configure' as described above.
213The notes below describe variables that may need to be edited by hand
214in unusual installations.
215
216ALL_CFLAGS are all the options passed to the C compiler.
217
218COMPAT2 is 1 if you still have version 2 RCS files around.
219(Version 2 became obsolete in 1982, so this isn't likely.)
220COMPAT2 assures that version 2 RCS files can still be read.
221When you have the new RCS installed, rename old version 2 RCS files as follows.
222Suppose the working file was `f.c';
223rename the RCS file `f.c.v' to `f.c,v', and the RCS file `f.v' to `f.c,v'.
224Thus suffixes are no longer dropped and RCS files end in `,v' rather than `.v'.
225After all version 2 RCS files have been updated with new versions of ci or rcs,
226you can remake RCS with COMPAT2 set to 0.
227
228DEFS are configuration options for the C preprocessor.
229It should include any extra -D and -I options needed on your system.
230
231LDFLAGS are the loader flags you need, e.g. -i, -n, -s, -x.
232
233LIBOBJS are any other object files you need to link.
234
235LIBS are the loader libraries you need, e.g. -lbsd, -lBSD, -ljobs, -lPW, -lx.
236
237LINK is the command used to link together an executable.
238
239LINT is the name and usual arguments of your lint program.
240
241RCSPREFIX is the prefix for subsidiary RCS commands like ci.
242If empty, RCS will search the PATH for these commands;
243this lets you move RCS commands after building them, and permits
244multiple instances of setuid RCS commands on the same host for different users.
245If nonempty, it should be a path followed by /;
246this makes RCS look in just one place, and makes execution faster.
247
248REMOVE is how to remove a file.
249
250o is the filename extension your host uses for object files.
251It includes the `.'.  It is typically `.o' on Unix hosts.
252
253x is the filename extension your host uses for executables.
254It includes any `.'.  It is empty on Unix hosts,
255which traditionally lack extensions on executables.
256
257
258__________
259
260src/conf.h notes
261
262See src/conf.sh for details about the definitions in src/conf.h.
263Comments below cover unusual situations requiring hand patches to src/conf.h.
264
265bad_NFS_rename - Some buggy NFS file servers (e.g. some NAC releases)
266can report that rename(A,B) succeeded even though it failed.
267Set bad_NFS_rename to nonzero to work around the problem.
268Warning: the workaround introduces a rare race condition
269that can falsely report I/O errors;
270this is why the workaround is disabled unless you specify otherwise.
271
272const - Some hosts support `const' but complain about it, perhaps because
273system headers are wrong.  If you can't stand the complaints,
274try `#define const /*empty*/'.
275
276has_mmap - For speed, RCS uses the `mmap' system call
277if it is available and the Mach `map_fd' system call is not.
278Unfortunately, many mmap implementations are broken.
279src/conf.sh guesses based on tests and on mmap bugs reported by RCS users;
280you may want to double-check its results.
281For instance, mmap does not work properly in HP-UX 8 or 9, or in Solaris 2.4,
282without kernel patches; see src/conf.sh for details.
283We don't know details about the bugs, so we can't test for them automatically.
284
285has_NFS - Set this if the target host might use NFS.
286NFS's ``stateless server'' protocol has well-known problems with
287the non-idempotent operations link(), rename(), and unlink().
288For example, unlink() can run twice on the NFS server,
289causing the client to think that the unlink failed with errno==ENOENT.
290has_NFS enables code that works around these problems.
291However, has_NFS does not work around NFS implementation bugs;
292if your NFS implementation is buggy, get another!
293For example, make sure that your NFS uses UDP checksums, if it uses UDP.
294Modern systems checksum by default; ask your vendor if you're not sure.
295
296has_rename - This should be 0 in SCO Unix V.3.2.  Its NFS rename() is broken,
297but if you run src/conf.sh in a non-NFS filesystem, it thinks rename() works.
298
299has_seteuid - You have to worry about this only if you plan to run RCS setuid.
300has_seteuid should be 1 only if your seteuid lets you switch back and
301forth between any pair of users as specified in Posix 1003.1a Draft 5.
302On some older systems (e.g. SunOS 3.5) seteuid doesn't allow this.
303One must be root to test this reliably, so src/conf.sh just guesses.
304If has_seteuid==0, perhaps you can use setreuid instead (see below).
305Otherwise, the next best thing is saved setuid semantics
306(a Posix 1003.1-1990 option), because this fails only if you run as root.
307You may need to compile with `cc -systype sysv' (some Mips OS variants)
308or `cc -YPOSIX' (some Ultrix variants) for best results here.
309Don't run RCS setuid under AIX 3.2 if you use NFS, since it's badly broken.
310To see the AIX 3.2 bug, run the following program setuid X where the NFS file
311"abc" already exists, owned by X, permission -rw-r--r--, and where
312the invoker is not X.  The program fails with "fclose: Permission denied".
313        #include <stdio.h>
314        int main() {
315                 FILE *f = fopen("abc", "w");
316                 setuid(getuid());
317                 fputc('\n', f);
318                 if (fclose(f) != 0)
319                         perror("fclose");
320        }
321
322has_setreuid - You have to worry about this only if you plan to run RCS setuid
323and if has_seteuid==0.  On some older BSDish systems, the setreuid system
324call lets you swap real and effective users even if one of them is root.
325One must be root to test this reliably, so src/conf.sh always guesses that
326it doesn't work.  Set it to 1 by hand if you know that it works.
327
328has_vfork - This should be 0 in some variants of HP/Apollo DomainOS.
329(The `uname -a' command reported `10.3.5 sys5.3' on one such variant.)
330Its vfork causes a system crash; you'll have to change src/conf.sh to output
331`#define has_vfork 0' without actually trying vfork.
332
333large_memory - This should be 1 if main memory is large enough to hold entire
334copies of RCS files, perhaps because virtual memory is available.
335
336_POSIX_SOURCE must be #defined in a strict Standard C environment,
337because otherwise <stdio.h> cannot define useful identifiers like fileno.
338Avoid defining _POSIX_SOURCE if possible,
339because it can disable useful non-Posix features in your host.
340Perhaps you can remove the need for _POSIX_SOURCE
341by supplying an option to your compiler to makes it less strict.
342You may also have to pay attention to other symbols, e.g. _XOPEN_SOURCE.
343
344TZ_must_be_set - set this to 1 on hosts where gmtime() yields bogus
345values unless the TZ environment variable is set.
346
347volatile - See `const'.  E.g. `volatile sig_atomic_t' is conforming, but some
348buggy hosts complain.  Also, Ultrix 4.0 Mips CC 2.0 has buggy volatile support.
349
350X_DEFAULT - This is normally ",v/" on Unix hosts, and "" on hosts that
351do not allow commas in file names (e.g. DOS).
Note: See TracBrowser for help on using the repository browser.