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.