diff options
author | peter <peter@FreeBSD.org> | 1999-08-24 01:06:48 +0000 |
---|---|---|
committer | peter <peter@FreeBSD.org> | 1999-08-24 01:06:48 +0000 |
commit | bacd15cb1fff2dee94d390e0f84c147cd82ea148 (patch) | |
tree | ad214c5b2c8142ad6dc6d2ce3a9c83e6317d7f77 /contrib/ncurses/INSTALL | |
download | FreeBSD-src-bacd15cb1fff2dee94d390e0f84c147cd82ea148.zip FreeBSD-src-bacd15cb1fff2dee94d390e0f84c147cd82ea148.tar.gz |
Import unmodified (but trimmed) ncurses 5.0 prerelease 990821.
This contains the full eti (panel, form, menu) extensions.
bmake glue to follow.
Obtained from: ftp://ftp.clark.net/pub/dickey/ncurses
Diffstat (limited to 'contrib/ncurses/INSTALL')
-rw-r--r-- | contrib/ncurses/INSTALL | 481 |
1 files changed, 481 insertions, 0 deletions
diff --git a/contrib/ncurses/INSTALL b/contrib/ncurses/INSTALL new file mode 100644 index 0000000..2ad50f6 --- /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. |