487 lines
21 KiB
Plaintext
487 lines
21 KiB
Plaintext
-- $Id: INSTALL,v 1.33 1999/09/18 23:04:36 tom Exp $
|
|
---------------------------------------------------------------------
|
|
How to install Ncurses/Terminfo on your system
|
|
---------------------------------------------------------------------
|
|
************************************************************
|
|
* READ ALL OF THIS FILE BEFORE YOU TRY TO INSTALL NCURSES. *
|
|
************************************************************
|
|
|
|
You should be reading the file INSTALL in a directory called ncurses-d.d, where
|
|
d.d is the current version number. There should be several subdirectories,
|
|
including `c++', `form', `man', `menu', 'misc', `ncurses', `panel', `progs',
|
|
and `test'. See the README file for a roadmap to the package.
|
|
|
|
If you are a Linux or FreeBSD or NetBSD distribution integrator or packager,
|
|
please read and act on the section titled IF YOU ARE A SYSTEM INTEGRATOR
|
|
below.
|
|
|
|
If you are converting from BSD curses and do not have root access, be sure
|
|
to read the BSD CONVERSION NOTES section below.
|
|
|
|
If you are using a version of XFree86 xterm older than 3.1.2F, see the section
|
|
on RECENT XTERM VERSIONS below.
|
|
|
|
If you are trying to build GNU Emacs using ncurses for terminal support,
|
|
read the USING NCURSES WITH EMACS section below.
|
|
|
|
If you are trying to build applications using gpm with ncurses,
|
|
read the USING NCURSES WITH GPM section below.
|
|
|
|
If you are trying to build Elvis using ncurses for terminal support,
|
|
read the USING NCURSES WITH ELVIS section below.
|
|
|
|
If you are running over the Andrew File System see the note below on
|
|
USING NCURSES WITH AFS.
|
|
|
|
If you want to build the Ada95 binding, go to the Ada95 directory and
|
|
follow the instructions there. The Ada95 binding is not covered below.
|
|
|
|
If you are using anything but (a) Linux, or (b) one of the 4.4BSD-based
|
|
i386 Unixes, go read the Portability section in the TO-DO file before you
|
|
do anything else.
|
|
|
|
REQUIREMENTS:
|
|
|
|
You will need the following in order to build and install ncurses under UNIX:
|
|
|
|
* ANSI C compiler (gcc is recommended)
|
|
* sh (bash will do)
|
|
* awk (mawk or gawk will do)
|
|
* sed
|
|
* BSD or System V style install (a script is enclosed)
|
|
|
|
Ncurses has been also built in the OS/2 EMX environment.
|
|
|
|
INSTALLATION PROCEDURE:
|
|
|
|
1. First, decide whether you want ncurses to replace your existing library (in
|
|
which case you'll need super-user privileges) or be installed in parallel
|
|
with it.
|
|
|
|
The --prefix option to configure changes the root directory for installing
|
|
ncurses. The default is in subdirectories of /usr/local. Use
|
|
--prefix=/usr to replace your default curses distribution. This is the
|
|
default for Linux and BSD/OS users.
|
|
|
|
The package gets installed beneath the --prefix directory as follows:
|
|
|
|
In $(prefix)/bin: tic, infocmp, captoinfo, tset,
|
|
reset, clear, tput, toe
|
|
In $(prefix)/lib: libncurses*.* libcurses.a
|
|
In $(prefix)/share/terminfo: compiled terminal descriptions
|
|
In $(prefix)/include: C header files
|
|
Under $(prefix)/man: the manual pages
|
|
|
|
Note however that the configure script attempts to locate previous
|
|
installation of ncurses, and will set the default prefix according to where
|
|
it finds the ncurses headers.
|
|
|
|
2. Type `./configure' in the top-level directory of the distribution to
|
|
configure ncurses for your operating system and create the Makefiles.
|
|
Besides --prefix, various configuration options are available to customize
|
|
the installation; use `./configure --help' to list the available options.
|
|
|
|
If your operating system is not supported, read the PORTABILITY section in
|
|
the file ncurses/README for information on how to create a configuration
|
|
file for your system.
|
|
|
|
The `configure' script generates makefile rules for one or more object
|
|
models and their associated libraries:
|
|
|
|
libncurses.a (normal)
|
|
|
|
libcurses.a (normal, a link to libncurses.a)
|
|
This gets left out if you configure with --disable-overwrite.
|
|
|
|
libncurses.so (shared)
|
|
|
|
libncurses_g.a (debug)
|
|
|
|
libncurses_p.a (profile)
|
|
|
|
If you do not specify any models, the normal and debug libraries will be
|
|
configured. Typing `configure' with no arguments is equivalent to:
|
|
|
|
./configure --with-normal --with-debug --enable-overwrite
|
|
|
|
Typing
|
|
|
|
./configure --with-shared
|
|
|
|
makes the shared libraries the default, resulting in
|
|
|
|
./configure --with-shared --with-normal --with-debug --enable-overwrite
|
|
|
|
If you want only shared libraries, type
|
|
|
|
./configure --with-shared --without-normal --without-debug
|
|
|
|
Rules for generating shared libraries are highly dependent upon the choice
|
|
of host system and compiler. We've been testing shared libraries on Linux
|
|
and SunOS with gcc, but more work needs to be done to make shared libraries
|
|
work on other systems.
|
|
|
|
You can make curses and terminfo fall back to an existing file of termcap
|
|
definitions by configuring with --enable-termcap. If you do this, the
|
|
library will search /etc/termcap before the terminfo database, and will
|
|
also interpret the contents of the TERM environment variable. See the
|
|
section BSD CONVERSION NOTES below.
|
|
|
|
3. Type `make'. Ignore any warnings, no error messages should be produced.
|
|
This should compile the ncurses library, the terminfo compiler tic(1),
|
|
captoinfo(1), infocmp(1), toe(1), clear(1) tset(1), reset(1), and tput(1)
|
|
programs (see the man pages for explanation of what they do), some test
|
|
programs, and the panels, menus, and forms libraries.
|
|
|
|
4. Run ncurses and several other test programs in the test directory to
|
|
verify that ncurses functions correctly before doing an install that
|
|
may overwrite system files. Read the file test/README for details on
|
|
the test programs.
|
|
|
|
NOTE: You must have installed the terminfo database, or set the
|
|
environment variable $TERMINFO to point to a SVr4-compatible terminfo
|
|
database before running the test programs. Not all vendors' terminfo
|
|
databases are SVr4-compatible, but most seem to be. Exceptions include
|
|
DEC's Digital Unix (formerly known as OSF/1).
|
|
|
|
The ncurses program is designed specifically to test the ncurses library.
|
|
You can use it to verify that the screen highlights work correctly, that
|
|
cursor addressing and window scrolling works OK, etc.
|
|
|
|
5. Once you've tested, you can type `make install' to install libraries,
|
|
the programs, the terminfo database and the man pages. Alternately, you
|
|
can type `make install' in each directory you want to install. In the
|
|
top-level directory, you can do a partial install using these commands:
|
|
|
|
'make install.progs' installs tic, infocmp, etc...
|
|
'make install.includes' installs the headers.
|
|
'make install.libs' installs the libraries (and the headers).
|
|
'make install.data' installs the terminfo data. (Note: `tic' must
|
|
be installed before the terminfo data can be
|
|
compiled).
|
|
'make install.man' installs the man pages.
|
|
|
|
############################################################################
|
|
# CAVEAT EMPTOR: `install.data' run as root will NUKE any existing #
|
|
# terminfo database. If you have any custom or unusual entries SAVE them #
|
|
# before you install ncurses. I have a file called terminfo.custom for #
|
|
# this purpose. Don't forget to run tic on the file once you're done. #
|
|
############################################################################
|
|
|
|
The terminfo(5) manual page wants to be preprocessed with tbl(1) before
|
|
being formatted by nroff(1). Modern man(1) implementations tend to do
|
|
this by default, but you may want to look at your version's man page
|
|
to be sure.
|
|
|
|
If the system already has a curses library that you need to keep using
|
|
for some bizarre binary-compatibility reason, you'll need to distinguish
|
|
between it and ncurses. If ncurses is installed outside the standard
|
|
directories (/usr/include and /usr/lib) then all your users will need
|
|
to use the -I option to compile programs and -L to link them.
|
|
|
|
If you have BSD curses installed in your system and you accidentally
|
|
compile using its curses.h you'll end up with a large number of
|
|
undefined symbols at link time. _waddbytes is one of them.
|
|
|
|
IF YOU DO NOT HAVE ROOT: Change directory to the `progs' subdirectory
|
|
and run the `capconvert' script. This script will deduce various things
|
|
about your environment and use them to build you a private terminfo tree,
|
|
so you can use ncurses applications.
|
|
|
|
If more than one user at your site does this, the space for the duplicate
|
|
trees is wasted. Try to get your site administrators to install a system-
|
|
wide terminfo tree instead.
|
|
|
|
See the BSD CONVERSION NOTES section below for a few more details.
|
|
|
|
6. The c++ directory has C++ classes that are built on top of ncurses and
|
|
panels. You must have c++ (and its libraries) installed before you can
|
|
compile and run the demo.
|
|
|
|
Use --without-cxx-binding to tell configure to not build the C++ bindings
|
|
and demo.
|
|
|
|
If you do not have C++, you must use the --without-cxx option to tell
|
|
the configure script to not attempt to determine the type of 'bool'
|
|
which may be supported by C++. IF YOU USE THIS OPTION, BE ADVISED THAT
|
|
YOU MAY NOT BE ABLE TO COMPILE (OR RUN) NCURSES APPLICATIONS WITH C++.
|
|
|
|
7. If you're running an older Linux, you must either (a) tell Linux that the
|
|
console terminal type is `linux' or (b) make a link to or copy of the
|
|
linux entry in the appropriate place under your terminfo directory, named
|
|
`console'. All 1.3 and many 1.2 distributions (including Yggdrasil and
|
|
Red Hat) already have the console type set to `linux'.
|
|
|
|
The way to change the wired-in console type depends on the configuration
|
|
of your system. This may involve editing /etc/inittab, /etc/ttytype,
|
|
/etc/profile and other such files.
|
|
|
|
Warning: this is not for the fainthearted, if you mess up your console
|
|
getty entries you can make your system unusable! However, if you are
|
|
a distribution maker, this is the right thing to do (see the note for
|
|
integrators near the end of this file).
|
|
|
|
The easier way is to link or copy l/linux to c/console under your terminfo
|
|
directory. Note: this will go away next time you do `make install.data'
|
|
and you'll have to redo it. There is no need to have entries for all
|
|
possible screen sizes, ncurses will figure out the size automatically.
|
|
|
|
IF YOU ARE A SYSTEM INTEGRATOR:
|
|
|
|
Beginning with 1.9.9, the ncurses distribution includes both a tset
|
|
utility and /usr/share/tabset directory. If you are installing ncurses,
|
|
it is no longer either necessary or desirable to install tset-jv.
|
|
|
|
Configuration and Installation:
|
|
|
|
Configure with --prefix=/usr to make the install productions put
|
|
libraries and headers in the correct locations (overwriting any
|
|
previous curses libraries and headers). This will put the terminfo
|
|
hierarchy under /usr/share/terminfo; you may want to override this with
|
|
--datadir=/usr/share/misc; terminfo and tabset are installed under the
|
|
data directory.
|
|
|
|
Please configure the ncurses library in a pure-terminfo mode; that
|
|
is, with the --disable-termcap option. This will make the ncurses
|
|
library smaller and faster. The ncurses library includes a termcap
|
|
emulation that queries the terminfo database, so even applications
|
|
that use raw termcap to query terminal characteristics will win
|
|
(providing you recompile and relink them!).
|
|
|
|
If you must configure with termcap fallback enabled, you may also
|
|
wish to use the --enable-getcap option. This option speeds up
|
|
termcap-based startups, at the expense of not allowing personal
|
|
termcap entries to reference the terminfo tree. See the code in
|
|
ncurses/tinfo/read_termcap.c for details.
|
|
|
|
Note that if you have $TERMCAP set, ncurses will use that value
|
|
to locate termcap data. In particular, running from xterm will
|
|
set $TERMCAP to the contents of the xterm's termcap entry.
|
|
If ncurses sees that, it will not examine /etc/termcap.
|
|
|
|
Keyboard Mapping:
|
|
|
|
The terminfo file assumes that Shift-Tab generates \E[Z (the ECMA-48
|
|
reverse-tabulation sequence) rather than ^I. Here are the loadkeys -d
|
|
mappings that will set this up:
|
|
|
|
keycode 15 = Tab Tab
|
|
alt keycode 15 = Meta_Tab
|
|
shift keycode 15 = F26
|
|
string F26 ="\033[Z"
|
|
|
|
Naming the Console Terminal
|
|
|
|
In various Linuxes (and possibly elsewhere) there has been a practice
|
|
of designating the system console driver type as `console'. Please
|
|
do not do this any more! It complicates peoples' lives, because it
|
|
can mean that several different terminfo entries from different
|
|
operating systems all logically want to be called `console'.
|
|
|
|
Please pick a name unique to your console driver and set that up
|
|
in the /etc/inittab table or local equivalent. Send the entry to the
|
|
terminfo maintainer (listed in the misc/terminfo file) to be included
|
|
in the terminfo file, if it's not already there. See the
|
|
term(7) manual page included with this distribution for more on
|
|
conventions for choosing type names.
|
|
|
|
Here are some recommended primary console names:
|
|
|
|
linux -- Linux console driver
|
|
freebsd -- FreeBSD
|
|
netbsd -- NetBSD
|
|
bsdos -- BSD/OS
|
|
|
|
If you are responsible for integrating ncurses for one of these
|
|
distribution, please either use the recommended name or get back
|
|
to us explaining why you don't want to, so we can work out nomenclature
|
|
that will make users' lives easier rather than harder.
|
|
|
|
RECENT XTERM VERSIONS
|
|
The terminfo database file included with this distribution assumes you
|
|
are running an XFree86 xterm based on X11R6 (i.e., xterm-r6). The
|
|
earlier X11R5 entry (xterm-r5) is provided as well.
|
|
|
|
If you are running XFree86 version 3.2 (actually 3.1.2F and up), you
|
|
should consider using the xterm-xf86-v32 (or later, the most recent
|
|
version is always named "xterm-xfree86") entry, which adds ANSI color
|
|
and the VT220 capabilities which have been added in XFree86. If you
|
|
are running a mixed network, however, where this terminal description
|
|
may be used on an older xterm, you may have problems, since
|
|
applications that assume these capabilities will produce incorrect
|
|
output on the older xterm (e.g., highlighting is not cleared).
|
|
|
|
CONFIGURING FALLBACK ENTRIES
|
|
In order to support operation of ncurses programs before the terminfo
|
|
tree is accessible (that is, in single-user mode or at OS installation
|
|
time) the ncurses library can be compiled to include an array of
|
|
pre-fetched fallback entries.
|
|
|
|
These entries are checked by setupterm() only when the conventional
|
|
fetches from the terminfo tree and the termcap fallback (if configured)
|
|
have been tried and failed. Thus, the presence of a fallback will not
|
|
shadow modifications to the on-disk entry for the same type, when that
|
|
entry is accessible.
|
|
|
|
By default, there are no entries on the fallback list. After you
|
|
have built the ncurses suite for the first time, you can change
|
|
the list (the process needs infocmp(1)). To do so, use the script
|
|
MKfallback.sh. A configure script option --with-fallbacks does this
|
|
(it accepts a comma-separated list of the names you wish, and does
|
|
not require a rebuild).
|
|
|
|
If you wanted (say) to have linux, vt100, and xterm fallbacks, you
|
|
would use the commands
|
|
|
|
cd ncurses;
|
|
MKfallback.sh linux vt100 xterm >fallback.c
|
|
|
|
Then just rebuild and reinstall the library as you would normally.
|
|
You can restore the default empty fallback list with
|
|
|
|
MKfallback.sh >fallback.c
|
|
|
|
The overhead for an empty fallback list is one trivial stub function.
|
|
Any non-empty fallback list is const-ed and therefore lives in sharable
|
|
text space. You can look at the comment trailing each initializer in
|
|
the generated ncurses/fallback.c file to see the core cost of the
|
|
fallbacks. A good rule of thumb for modern vt100-like entries is that
|
|
each one will cost about 2.5K of text space.
|
|
|
|
BSD CONVERSION NOTES:
|
|
If you need to support really ancient BSD programs, you probably
|
|
want to configure with the --enable-bsdpad option. What this does
|
|
is enable code in tputs() that recognizes a numeric prefix on a
|
|
capability as a request for that much trailing padding in milliseconds.
|
|
There are old BSD programs that do things like tputs("50").
|
|
|
|
(If you are distributing ncurses as a support-library component of
|
|
an application you probably want to put the remainder of this section
|
|
in the package README file.)
|
|
|
|
The following note applies only if you have configured ncurses with
|
|
--enable-termcap.
|
|
|
|
------------------------------- CUT HERE --------------------------------
|
|
|
|
If you are installing this application privately (either because you
|
|
have no root access or want to experiment with it before doing a root
|
|
installation), there are a couple of details you need to be aware of.
|
|
They have to do with the ncurses library, which uses terminfo rather
|
|
than termcap for describing terminal characteristics.
|
|
|
|
Though the ncurses library is terminfo-based, it will interpret your
|
|
TERMCAP variable (if present), any local termcap files you reference
|
|
through it, and the system termcap file. However, in order to avoid
|
|
slowing down your application startup, it will only do this once per
|
|
terminal type!
|
|
|
|
The first time you load a given terminal type from your termcap
|
|
database, the library initialization code will automatically write it
|
|
in terminfo format to a subdirectory under $HOME/.terminfo. After
|
|
that, the initialization code will find it there and do a (much
|
|
faster) terminfo fetch.
|
|
|
|
Usually, all this means is that your home directory will silently grow
|
|
an invisible .terminfo subdirectory which will get filled in with
|
|
terminfo descriptions of terminal types as you invoke them. If anyone
|
|
ever installs a global terminfo tree on your system, this will quietly
|
|
stop happening and your $HOME/.terminfo will become redundant.
|
|
|
|
The objective of all this logic is to make converting from BSD termcap
|
|
as painless as possible without slowing down your application (termcap
|
|
compilation is expensive).
|
|
|
|
If you don't have a TERMCAP variable or custom personal termcap file,
|
|
you can skip the rest of this dissertation.
|
|
|
|
If you *do* have a TERMCAP variable and/or a custom personal termcap file
|
|
that defines a terminal type, that definition will stop being visible
|
|
to this application after the first time you run it, because it will
|
|
instead see the terminfo entry that it wrote to $HOME/terminfo the
|
|
first time around.
|
|
|
|
Subsequently, editing the TERMCAP variable or personal TERMCAP file
|
|
will have no effect unless you explicitly remove the terminfo entry
|
|
under $HOME/terminfo. If you do that, the entry will be recompiled
|
|
from your termcap resources the next time it is invoked.
|
|
|
|
To avoid these complications, use infocmp(1) and tic(1) to edit the
|
|
terminfo directory directly.
|
|
|
|
------------------------------- CUT HERE --------------------------------
|
|
|
|
USING NCURSES WITH AFS:
|
|
AFS treats each directory as a separate logical filesystem, you
|
|
can't hard-link across them. The --enable-symlinks option copes
|
|
with this by making tic use symbolic links.
|
|
|
|
USING NCURSES WITH EMACS:
|
|
GNU Emacs has its own termcap support. By default, it uses a mixture
|
|
of those functions and code linked from the host system's libraries.
|
|
You need to foil this and shut out the GNU termcap library entirely.
|
|
|
|
In order to do this, hack the Linux config file (s/linux.h) to contain
|
|
a #define TERMINFO and set the symbol LIBS_TERMCAP to "-lncurses".
|
|
|
|
We have submitted such a change for the 19.30 release, so it may
|
|
already be applied in your sources -- check for the #define TERMINFO.
|
|
|
|
USING NCURSES WITH GPM:
|
|
Ncurses 4.1 and up can be configured to use GPM (General Purpose Mouse)
|
|
which is used on Linux console. Be aware that GPM is commonly
|
|
installed as a shared library which contains a wrapper for the curses
|
|
wgetch() function (libcurses.o). Some integrators have simplified
|
|
linking applications by combining all of libcurses.so (the BSD curses)
|
|
into the libgpm.so file, producing symbol conflicts with ncurses. You
|
|
may be able to work around this problem by linking as follows:
|
|
|
|
cc -o foo foo.o -lncurses -lgpm -lncurses
|
|
|
|
but the linker may not cooperate, producing mysterious errors.
|
|
A patched version of gpm is available:
|
|
|
|
ftp.clark.net:/pub/dickey/ncurses/gpm-1.10-970125.tgz
|
|
|
|
This patch is incorporated in gpm 1.12; however some integrators
|
|
are slow to update this library.
|
|
|
|
USING NCURSES WITH ELVIS:
|
|
To use ncurses as the screen-painting library for Elvis, apply the
|
|
following patch to the Elvis curses
|
|
|
|
*** curses.c.orig Sun Jun 26 05:48:23 1994
|
|
--- curses.c Sun Feb 11 16:50:41 1996
|
|
***************
|
|
*** 986,992 ****
|
|
{
|
|
if (has_IM)
|
|
do_IM();
|
|
! do_IC();
|
|
qaddch(ch);
|
|
if (has_EI)
|
|
do_EI();
|
|
--- 986,995 ----
|
|
{
|
|
if (has_IM)
|
|
do_IM();
|
|
!#ifdef NCURSES_VERSION
|
|
! else /* ncurses does insertion in a slightly nonstandard way */
|
|
!#endif
|
|
! do_IC();
|
|
qaddch(ch);
|
|
if (has_EI)
|
|
do_EI();
|
|
|
|
This patch is for elvis-1.8pl4 but it can even be used for elvis-1.8pl3 with
|
|
an offset of -11 lines.
|
|
|
|
BUGS:
|
|
Send any feedback to the ncurses mailing list at
|
|
bug-ncurses@gnu.org. To subscribe send mail to
|
|
bug-ncurses-request@gnu.org with body that reads:
|
|
subscribe ncurses <your-email-address-here>
|
|
|
|
The Hacker's Guide in the misc directory includes some guidelines
|
|
on how to report bugs in ways that will get them fixed most quickly.
|