aboutsummaryrefslogtreecommitdiff
path: root/contrib/ncurses/INSTALL
diff options
context:
space:
mode:
Diffstat (limited to 'contrib/ncurses/INSTALL')
-rw-r--r--contrib/ncurses/INSTALL481
1 files changed, 481 insertions, 0 deletions
diff --git a/contrib/ncurses/INSTALL b/contrib/ncurses/INSTALL
new file mode 100644
index 000000000000..2ad50f6d9d73
--- /dev/null
+++ b/contrib/ncurses/INSTALL
@@ -0,0 +1,481 @@
+-- $Id: INSTALL,v 1.32 1999/07/24 21:06:24 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 need to have c++ (and its libraries) installed before you can
+ compile and run the demo.
+
+ If you do not have C++, you must use the --without-cxx option to tell
+ the configure script to not attempt to build the C++ bindings.
+
+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.