Sync with FreeBSD. This adds read-only support for zip and ISO9660.
[dragonfly.git] / contrib / nvi / build / README
1 #       @(#)README      8.26 (Berkeley) 10/19/96
2
3 Nvi uses the GNU autoconf program for configuration and compilation.  You
4 should enter:
5
6         configure
7         make
8
9 and nvi will configure the system and build one or two binaries:  nvi and
10 tknvi.  You can use any path to the configure script, e.g., to build for
11 an x86 architecture, I suggest that you do:
12
13         mkdir build.x86
14         cd build.x86
15         ../build/configure
16         make
17
18 There are options that you can specify to the configure command.  See
19 the next section for a description of these options.
20
21 If you want to rebuild or reconfigure nvi, for example, because you change
22 your mind as to the curses library that you want to use, create a new
23 directory and reconfigure it using "configure" and whatever options you
24 choose, don't try to selectively edit the files.
25
26 By default, nvi is installed as "vi", with hard links to "ex" and "view".
27 To install them using different names, use the configure program options.
28 For example, to install them as "nvi", "nex" and "nview", use:
29
30         configure --program-prefix=n
31
32 See the section below on installation for details.
33
34 Note, if you're building nvi on a LynxOS system, you should read the
35 README.LynxOS file in this directory for additional build instructions
36 that are specific to that operating system.
37
38 If you have trouble with this procedure, send email to the addresses
39 listed in ../README.  In that email, please provide a complete script
40 of the output for all of the above commands that you entered.
41
42 =-=-=-=-=-=-=
43 NVI'S OPTIONS TO THE CONFIGURE PROGRAM
44 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
45
46 There are many options that you can enter to the configuration program.
47 To see a complete list of the options, enter "configure --help".  Only
48 a few of them are nvi specific.  These options are as follows:
49
50   --disable-curses        DON'T use the nvi-provided curses routines.
51   --disable-db            DON'T use the nvi-provided DB routines.
52   --disable-re            DON'T use the nvi-provided RE routines.
53   --enable-debug          Build a debugging version.
54   --enable-perlinterp     Include a Perl interpreter in vi.
55   --enable-tclinterp      Include a Tk/Tcl interpreter in vi.
56   --enable-tknvi          Build a Tk/Tcl front-end for vi.
57
58 disable-curses:
59         By default, nvi loads its own implementation of the curses
60         routines (which are a stripped-down version of the 4.4BSD curses
61         library).  If you have your own curses library implementation and
62         you want to use it instead, enter:
63
64         --disable-curses
65
66         as an argument to configure, and the curses routines will be taken
67         from whatever libraries you load.  Note: System V based curses
68         implementations are usually broken.  See the last section of this
69         README for further information about nvi and the curses library.
70
71 disable-db:
72         By default, nvi loads its own versions of the Berkeley DB routines
73         (which are a stripped-down version of DB 1.85).  If you have your
74         own version of the Berkeley DB routines and you want to use them
75         instead, enter:
76
77         --disable-db
78
79         as an argument to configure, and the DB routines will be taken
80         from whatever libraries you load.  Make sure that the DB routines
81         you use are at least version 1.85 or later.
82
83 disable-re:
84         By default, nvi loads its own versions of the POSIX 1003.2 Regular
85         Expression routines (which are Henry Spencer's implementation).
86         If your C library contains an implementation of the POSIX 1003.2
87         RE routines (note, this is NOT the same as the historic UNIX RE
88         routines), and you want to use them instead, enter:
89
90         --disable-re
91
92         as an argument to configure, and the RE routines will be taken
93         from whatever libraries you load.  Please ensure that your RE
94         routines implement Henry Spencer's extensions for doing vi-style
95         "word" searches.
96
97 enable-debug:
98         If you want to build nvi with no optimization (i.e. without -O
99         as a compiler flag), with -g as a compiler flag, and with DEBUG
100         defined during compilation, enter:
101
102         --enable-debug
103
104         as an argument to configure.
105
106 enable-perlinterp:
107         If you have the Perl 5 libraries and you want to compile in the
108         Perl interpreter, enter:
109
110         --enable-perlinterp
111
112         as an argument to configure.  (Note: this is NOT possible with
113         Perl 4, or even with Perl 5 versions earlier than 5.002.)
114
115 enable-tclinterp:
116         If you have the Tk/Tcl libraries and you want to compile in the
117         Tcl/Tk interpreter, enter:
118
119         --enable-tclinterp
120
121         as an argument to configure.  If your Tk/Tcl include files and
122         libraries aren't in the standard library and include locations,
123         see the next section of this README file for more information.
124
125 enable-tknvi:
126         If you have the Tk/Tcl libraries and you want to build the Tcl/Tk
127         nvi front-end, enter:
128
129         --enable-tknvi
130
131         as an argument to configure.  If your Tk/Tcl include files and
132         libraries aren't in the standard library and include locations,
133         see the next section of this README file for more information.
134
135 =-=-=-=-=-=-=
136 ADDING OR CHANGING COMPILERS, OR COMPILE OR LOAD LINE FLAGS
137 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
138
139 If you want to use a specific compiler, specify the CC environment
140 variable before running configure.  For example:
141
142         env CC=gcc configure
143
144 Using anything other than the native compiler will almost certainly
145 mean that you'll want to check the compile and load line flags, too.
146
147 If you want to specify additional load line flags, specify the ADDLDFLAGS
148 environment variable before running configure.  For example:
149
150         env ADDLDFLAGS="-Q" configure
151
152 would specify the -Q flag in the load line when the nvi programs are
153 loaded.
154
155 If you don't want configure to use the default load line flags for the
156 system, specify the LDFLAGS environment variable before running configure.
157 For example:
158
159         env LDFLAGS="-32" configure
160
161 will cause configure to set the load line flags to "-32", and not set
162 them based on the current system.
163
164 If you want to specify additional compile line flags, specify the
165 ADDCPPFLAGS environment variable before running configure.  For example:
166
167         env ADDCPPFLAGS="-I../foo" configure
168
169 would cause the compiler to be passed the -I../foo flag when compiling
170 test programs during configuration as well as when building nvi object
171 files.
172
173 If you don't want configure to use the default compile line flags for the
174 system, specify the CPPFLAGS environment variable before running configure.
175 For example:
176
177         env CPPFLAGS="-I.." configure
178
179 will cause configure to use "-I.." as the compile line flags instead of
180 the default values.
181
182 =-=-=-=-=-=-=
183 ADDING LIBRARIES AND INCLUDE FILES
184 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
185
186 If the Tk/Tcl or any other include files or libraries are in non-standard
187 places on your system, you will need to specify the directory path where
188 they can be found.
189
190 If you want to specify additional library paths, set the ADDLIBS environment
191 variable before running configure.  For example:
192
193         env ADDLIBS="-L/a/b -L/e/f -ldb" configure
194
195 would specify two additional directories to search for libraries, /a/b
196 and /e/f, and one additional library to load, "db".
197
198 If you want to specify additional include paths, specify the ADDCPPFLAGS
199 environment variable before running configure.  For example:
200
201         env ADDCPPFLAGS="-I/usr/local/include" LIBS="-ldb" configure
202
203 would search /usr/local/include for include files, as well as load the db
204 library as described above.
205
206 As a final example, let's say that you've downloaded ncurses from the net
207 and you've built it in a directory named ncurses which is at the same
208 level in the filesystem hierarchy as nvi.  You would enter something like:
209
210         env ADDCPPFLAGS="-I../../ncurses/include" \
211             ADDLIBS="-L../../ncurses/libraries" configure
212
213 to cause nvi to look for the curses include files and the curses library
214 in the ncurses environment.
215
216 Notes:
217         Make sure that you prepend -L to any library directory names, and
218         that you prepend -I to any include file directory names!  Also,
219         make sure that you quote the paths as shown above, i.e. with
220         single or double quotes around the values you're specifying for
221         ADDCPPFLAGS and ADDLIBS.
222
223         =-=-=-=-=-=
224         You should NOT need to add any libraries or include files to load
225         the Perl5 interpreter.  The configure script will obtain that
226         information directly from the Perl5 program.  This means that the
227         configure script must be able to find perl in its path.  It looks
228         for "perl5" first, and then "perl".  If you're building a Perl
229         interpreter and neither is found, it's a fatal error.
230
231         =-=-=-=-=-=
232         You do not need to specify additional libraries to load Tk/Tcl,
233         Perl or curses, as the nvi configuration script adds the
234         appropriate libraries to the load line whenever you specify
235         --enable-tknvi or other Perl or Tk/Tcl related option, or build
236         the Tk/Tcl or curses version of nvi.  The library names that are
237         automatically loaded are as follows:
238
239         for Perl:       -lperl
240         for Tk/Tcl:     -ltk -ltcl -lm
241         for curses:     -lcurses
242
243         In addition, the configure script loads:
244
245                 ... the X libraries when loading the Tk/Tcl libraries,
246                     if they exist.
247
248                 ... the -ltermcap or -ltermlib libraries when loading
249                     any curses library, if they exist.
250
251         =-=-=-=-=-=
252         The env command is available on most systems, and simply sets one
253         or more environment variables before running a command.  If the
254         env command is not available to you, you can set the environment
255         variables in your shell before running configure.  For example,
256         in sh or ksh, you could do:
257
258                 ADDLIBS="-L/a/b -L/e/f -ldb" configure
259
260         and in csh or tcsh, you could do:
261
262                 setenv ADDLIBS "-L/a/b -L/e/f -ldb"
263                 configure
264
265         See your shell manual page for further information.
266
267 =-=-=-=-=-=-=
268 INSTALLING NVI
269 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
270
271 Nvi installs the following files into the following locations, with
272 the following default values:
273
274 Variables:              Default value:
275 prefix                  /usr/local
276 exec_prefix             $(prefix)
277 bindir                  $(prefix)/bin
278 datadir                 $(prefix)/share
279 mandir                  $(prefix)/man
280
281 File(s):                Default location
282 ----------------------------------------
283 vi                      $(bindir)/vi
284 vi.1                    $(mandir)/man1/vi.1
285 vi.0                    $(mandir)/cat1/vi.0
286 Perl scripts            $(datadir)/vi/perl/
287 Tcl scripts             $(datadir)/vi/tcl/
288 Message Catalogs        $(datadir)/vi/catalog/
289
290 Notes:
291         There are two hard links to the vi program, named ex and view.
292         Similarly, there are two hard links to the unformatted vi manual
293         page, named ex.1 and view.1, and two hard links to the formatted
294         manual page, named ex.0 and view.0.  These links are created when
295         the program and man pages are installed.
296
297         If you want to install vi, ex, view and the man pages as nvi, nex,
298         nview, use the configure option --program-prefix=n.  Other, more
299         complex transformations are possible -- use configure --help to
300         see more options.
301
302         To move the entire installation tree somewhere besides /usr/local,
303         change the value of both "exec_prefix" and "prefix".  To move the
304         binaries to a different place, change the value of "bindir".
305         Similarly, to put the datafiles (the message catalogs, Perl and
306         Tcl scripts) or the man pages in a different place, change the
307         value of "datadir" or "mandir".  These values can be changed as
308         part of configuration:
309
310                 configure --exec_prefix=/usr/contrib --prefix=/usr/share
311
312         or when doing the install itself:
313
314                 make exec_prefix=/usr/contrib prefix=/usr/contrib install
315
316         The datafile directory (e.g., /usr/local/share/vi by default) is
317         completely removed and then recreated as part of the installation
318         process.
319
320 =-=-=-=-=-=-=
321 NVI AND THE CURSES LIBRARY
322 =-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=-=
323
324 The major portability problem for nvi is selecting a curses library.
325 Unfortunately, it is common to find broken versions of curses -- the
326 original System V curses was broken, resulting in all vendors whose
327 implementations are derived from System V having broken implementations
328 in turn.
329
330 For this reason, BY DEFAULT, nvi uses the stripped-down curses library
331 that's included in its distribution.  Of course, it would be preferable
332 to use the vendor's curses library, or one of the newer implementations
333 of curses, e.g., ncurses.
334
335 To use the vendor's curses library, specify the:
336
337         --disable-curses
338
339 argument to the configure command.  If you use the vendor's or other
340 curses library, and you see any of the following symptoms:
341
342         + Core dumps in curses routines.
343         + Missing routines when compiling.
344         + Repainting the wrong characters on the screen.
345         + Displaying inverse video in the wrong places.
346         + Failure to reset your terminal to the correct modes on exit.
347
348 you have a broken curses implementation, and you should reconfigure nvi
349 to use another curses library or the curses library provided with nvi.
350
351 There are two alternative sources for curses libraries:
352
353 #1: Compile the 4BSD curses library from any of the recent BSD
354     releases: FreeBSD, NetBSD or 4.4BSD-Lite release 2.  These
355     libraries should be able to support nvi.
356
357 #2: Retrieve and build the ncurses library.  This library is not
358     recommended unreservedly, at least for now, for two reasons.
359     First, it can't be built on any system where the compiler
360     doesn't support function prototypes.  Second, it currently has
361     a few bugs in its support for nvi.  It mostly works, but it's
362     still not quite right.
363
364 One final note.  If you see the following symptoms:
365
366         + Line-by-line screen repainting instead of scrolling.
367
368 it usually means that your termcap or terminfo information is insufficient
369 for the terminal.