diff options
Diffstat (limited to 'Build/source/libs/ncurses/INSTALL')
-rw-r--r-- | Build/source/libs/ncurses/INSTALL | 1245 |
1 files changed, 1245 insertions, 0 deletions
diff --git a/Build/source/libs/ncurses/INSTALL b/Build/source/libs/ncurses/INSTALL new file mode 100644 index 00000000000..9a3a39210b3 --- /dev/null +++ b/Build/source/libs/ncurses/INSTALL @@ -0,0 +1,1245 @@ +-- $Id: INSTALL,v 1.79 2004/10/09 16:56:33 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 trying to build applications using gpm with ncurses, +read the USING NCURSES WITH GPM section below. + +If you are running over the Andrew File System see the note below on +USING NCURSES WITH AFS. + +If you are cross-compiling, see the note below on BUILDING NCURSES WITH A +CROSS-COMPILER. + +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 to build and install ncurses under UNIX: + + * ANSI C compiler (gcc, for instance) + * 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 normally in subdirectories of /usr/local, except + for systems where ncurses is normally installed as a system library, e.g., + Linux, the various BSD systems and Cygwin. Use --prefix=/usr to replace + your default curses distribution. + + 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 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. + + Do not use commands such as + + make install prefix=XXX + + to change the prefix after configuration, since the prefix value is used + for some absolute pathnames such as TERMINFO. Instead do this + + make install DESTDIR=XXX + + See also the discussion of --with-install-prefix. + +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) + + libncurses.la (libtool) + + If you configure using the --enable-widec option, a "w" is appended to the + library names (e.g., libncursesw.a), and the resulting libraries support + wide-characters, e.g., via a UTF-8 locale. The corresponding header files + are compatible with the non-wide-character configuration; wide-character + features are provided by ifdef's in the header files. The wide-character + library interfaces are not binary-compatible with the non-wide-character + version. Building and running the wide-character code relies on a fairly + recent implementation of libiconv. We have built this configuration on + Linux using libiconv, sometimes requiring libutf8. + + 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. + + If you have libtool installed, you can type + + ./configure --with-libtool + + to generate the appropriate static and/or shared libraries for your + platform using libtool. + + 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 manual 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). + + If you run the test programs WITHOUT installing terminfo, ncurses may + read the termcap file and cache that in $HOME/.terminfo, which will + thereafter be used instead of the terminfo database. See the comments + on "--enable-getcap-cache", to see why this is a Bad Thing. + + It is possible to configure ncurses to use other terminfo database formats. + A few are provided as examples in the include-directory (see --with-caps). + + 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 manual 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 manual 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 must 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 manual page + to be sure. You may also install the manual pages after preprocessing + with tbl(1) by specifying the configure option --with-manpage-tbl. + + If the system already has a curses library that you need to keep using + you'll need to distinguish between it and ncurses. See the discussion of + --disable-overwrite. 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 another 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. + + 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++. + + +SUMMARY OF CONFIGURE OPTIONS: +---------------------------- + + The configure script provides a short list of its options when you type + + ./configure --help + + The --help and several options are common to all configure scripts that are + generated with autoconf. Those are all listed before the line + + --enable and --with options recognized: + + The other options are specific to this package. We list them in alphabetic + order. + + --disable-assumed-color + With ncurses 5.1, we introduced a new function, assume_default_colors() + which allows applications to specify what the default foreground and + background color are assumed to be. Most color applications use + full-screen color; but a few do not color the background. While the + assumed values can be overridden by invoking assume_default_colors(), + you may find it useful to set the assumed values to the pre-5.1 + convention, using this configure option. + + --disable-big-core + Assume machine has little memory. The configure script attempts to + determine if your machine has enough memory (about 6Mb) to compile the + terminfo database without writing portions to disk. Some allocators + return deceptive results, so you may have to override the configure + script. Or you may be building tic for a smaller machine. + + --disable-database + Use only built-in data. The ncurses libraries normally read terminfo + and termcap data from disk. You can configure ncurses to have a + built-in database, aka "fallback" entries. Embedded applications may + have no need for an external database. Some, but not all of the + programs are useful in this configuration, e.g., reset and tput versus + infocmp and tic. + + --disable-ext-funcs + Disable function-extensions. Configure ncurses without the functions + that are not specified by XSI. See ncurses/modules for the exact + list of library modules that would be suppressed. + + --disable-hashmap + Compile without hashmap scrolling-optimization code. This algorithm is + the default. + + --disable-home-terminfo + The $HOME/.terminfo directory is normally added to ncurses' search + list for reading/writing terminfo entries, since that directory is + more likely writable than the system terminfo database. Use this + option to disable the feature altogether. + + --disable-leaks + For testing, compile-in code that frees memory that normally would not + be freed, to simplify analysis of memory-leaks. + + --disable-macros + For testing, use functions rather than macros. The program will run + more slowly, but it is simpler to debug. This makes a header file + "nomacros.h". See also the --enable-expanded option. + + --disable-overwrite + If you are installing ncurses on a system which contains another + development version of curses, or which could be confused by the loader + for another version, we recommend that you leave out the link to + -lcurses. The ncurses library is always available as -lncurses. + Disabling overwrite also causes the ncurses header files to be + installed into a subdirectory, e.g., /usr/local/include/ncurses, + rather than the include directory. This makes it simpler to avoid + compile-time conflicts with other versions of curses.h + + --disable-root-environ + Compile with environment restriction, so certain environment variables + are not available when running as root, or via a setuid/setgid + application. These are (for example $TERMINFO) those that allow the + search path for the terminfo or termcap entry to be customized. + + --disable-scroll-hints + Compile without scroll-hints code. This option is ignored when + hashmap scrolling is configured, which is the default. + + --enable-assertions + For testing, compile-in assertion code. This is used only for a few + places where ncurses cannot easily recover by returning an error code. + + --enable-broken_linker + A few platforms have what we consider a broken linker: it cannot link + objects from an archive solely by referring to data objects in those + files, but requires a function reference. This configure option + changes several data references to functions to work around this + problem. + + NOTE: With ncurses 5.1, this may not be necessary, since we are + told that some linkers interpret uninitialized global data as a + different type of reference which behaves as described above. We have + explicitly initialized all of the global data to work around the + problem. + + --enable-bsdpad + Recognize BSD-style prefix padding. Some ancient BSD programs (such as + nethack) call tputs("50") to implement delays. + + --enable-colorfgbg + Compile with experimental $COLORFGBG code. That environment variable + is set by some terminal emulators as a hint to applications, by + advertising the default foreground and background colors. During + initialization, ncurses sets color pair 0 to match this. + + --enable-const + The curses interface as documented in XSI is rather old, in fact + including features that precede ANSI C. The prototypes generally do + not make effective use of "const". When using stricter compilers (or + gcc with appropriate warnings), you may see warnings about the mismatch + between const and non-const data. We provide a configure option which + changes the interfaces to use const - quieting these warnings and + reflecting the actual use of the parameters more closely. The ncurses + library uses the symbol NCURSES_CONST for these instances of const, + and if you have asked for compiler warnings, will add gcc's const-qual + warning. There will still be warnings due to subtle inconsistencies + in the interface, but at a lower level. + + NOTE: configuring ncurses with this option may detract from the + portability of your applications by encouraging you to use const in + places where the XSI curses interface would not allow them. Similar + issues arise when porting to SVr4 curses, which uses const in even + fewer places. + + --enable-echo + Use the option --disable-echo to make the build-log less verbose by + suppressing the display of the compile and link commands. This makes + it easier to see the compiler warnings. (You can always use "make -n" + to see the options that are used). + + --enable-expanded + For testing, generate functions for certain macros to make them visible + as such to the debugger. See also the --disable-macros option. + + --enable-getcap + Use the 4.4BSD getcap code if available, or a bundled version of it to + fetch termcap entries. Entries read in this way cannot use (make + cross-references to) the terminfo tree, but it is faster than reading + /etc/termcap. + + --enable-getcap-cache + Cache translated termcaps under the directory $HOME/.terminfo + + NOTE: this sounds good - it makes ncurses run faster the second time. + But look where the data comes from - an /etc/termcap containing lots of + entries that are not up to date. If you configure with this option and + forget to install the terminfo database before running an ncurses + application, you will end up with a hidden terminfo database that + generally does not support color and will miss some function keys. + + --enable-hard-tabs + Compile-in cursor-optimization code that uses hard-tabs. We would make + this a standard feature except for the concern that the terminfo entry + may not be accurate, or that your stty settings have disabled the use + of tabs. + + --enable-no-padding + Compile-in support for the $NCURSES_NO_PADDING environment variable, + which allows you to suppress the effect of non-mandatory padding in + terminfo entries. This is the default, unless you have disabled the + extended functions. + + --enable-rpath + Use rpath option when generating shared libraries, and with some + restrictions when linking the corresponding programs. This applies + mainly to systems using the GNU linker (read the manpage). + + --enable-safe-sprintf + Compile with experimental safe-sprintf code. You may consider using + this if you are building ncurses for a system that has neither + vsnprintf() or vsprintf(). It is slow, however. + + --enable-sigwinch + Compile support for ncurses' SIGWINCH handler. If your application has + its own SIGWINCH handler, ncurses will not use its own. The ncurses + handler causes wgetch() to return KEY_RESIZE when the screen-size + changes. This option is the default, unless you have disabled the + extended functions. + + --enable-symlinks + If your system supports symbolic links, make tic use symbolic links + rather than hard links to save diskspace when writing aliases in the + terminfo database. + + --enable-tcap-names + Compile-in support for user-definable terminal capabilities. Use the + -x option of tic and infocmp to treat unrecognized terminal + capabilities as user-defined strings. This option is the default, + unless you have disabled the extended functions. + + --enable-termcap + Compile in support for reading terminal descriptions from termcap if no + match is found in the terminfo database. See also the --enable-getcap + and --enable-getcap-cache options. + + --enable-warnings + Turn on GCC compiler warnings. There should be only a few. + + --enable-widec + Compile with wide-character code. This makes a different version of + the libraries (e.g., libncursesw.so), which stores characters as + wide-characters, + + NOTE: applications compiled with this configuration are not compatible + with those built for 8-bit characters. You cannot simply make a + symbolic link to equate libncurses.so with libncursesw.so + + NOTE: the Ada95 binding may be built against either version of the the + ncurses library, but you must decide which: the binding installs the + same set of files for either version. Currently (2002/6/22) it does + not use the extended features from the wide-character code, so it is + probably better to not install the binding for that configuration. + + --enable-xmc-glitch + Compile-in support experimental xmc (magic cookie) code. + + --with-abi-version=NUM + Override the ABI version, which is used in shared library filenames. + Normally this is the same as the release version; some ports have + special requirements for compatibility. + + --with-ada-compiler=CMD + Specify the Ada95 compiler command (default "gnatmake") + + --with-ada-include=DIR + Tell where to install the Ada includes (default: + PREFIX/lib/ada/adainclude) + + --with-ada-objects=DIR + Tell where to install the Ada objects (default: PREFIX/lib/ada/adalib) + + --with-bool=TYPE + If --without-cxx is specified, override the type used for the "bool" + declared in curses.h (normally the type is automatically chosen to + correspond with that in <stdbool.h>, or defaults to platform-specific + sizes). + + --with-build-cc=XXX + If cross-compiling, specify a host C compiler, which is needed to + compile a few utilities which generate source modules for ncurses. + If you do not give this option, the configure script checks if the + $BUILD_CC variable is set, and otherwise defaults to gcc or cc. + + --with-build-cflags=XXX + If cross-compiling, specify the host C compiler-flags. You might need + to do this if the target compiler has unusual flags which confuse the + host compiler. + + --with-build-cppflags=XXX + If cross-compiling, specify the host C preprocessor-flags. You might + need to do this if the target compiler has unusual flags which confuse + the host compiler. + + --with-build-ldflags=XXX + If cross-compiling, specify the host linker-flags. You might need to + do this if the target linker has unusual flags which confuse the host + compiler. + + --with-build-libs=XXX + If cross-compiling, the host libraries. You might need to do this if + the target environment requires unusual libraries. + + --with-caps=XXX + Specify an alternate terminfo capabilities file, which makes the + configure script look for "include/Caps.XXX". A few systems, e.g., + AIX 4.x use the same overall file-format as ncurses for terminfo + data, but use different alignments within the tables to support + legacy applications. For those systems, you can configure ncurses + to use a terminfo database which is compatible with the native + applications. + + --with-database=XXX + Specify the terminfo source file to install. Usually you will wish + to install ncurses' default (misc/terminfo.src). Certain systems + have special requirements, e.g, OS/2 EMX has a customized terminfo + source file. + + --with-dbmalloc + For testing, compile and link with Conor Cahill's dbmalloc library. + + --with-debug + Generate debug-libraries (default). These are named by adding "_g" + to the root, e.g., libncurses_g.a + + --with-default-terminfo-dir=XXX + Specify the default terminfo database directory. This is normally + DATADIR/terminfo, e.g., /usr/share/terminfo. + + --with-develop + Enable experimental/development options. This does not count those + that change the interface, such as --enable-widec. + + --with-dmalloc + For testing, compile and link with Gray Watson's dmalloc library. + + --with-fallbacks=XXX + Specify a list of fallback terminal descriptions which will be + compiled into the ncurses library. See CONFIGURING FALLBACK ENTRIES. + + --with-gpm + use Alessandro Rubini's GPM library to provide mouse support on the + Linux console. + + --with-install-prefix=XXX + Allows you to specify an alternate location for installing ncurses + after building it. The value you specify is prepended to the "real" + install location. This simplifies making binary packages. The + makefile variable DESTDIR is set by this option. It is also possible + to use + make install DESTDIR=XXX + since the makefiles pass that variable to subordinate makes. + + NOTE: a few systems build shared libraries with fixed pathnames; this + option probably will not work for those configurations. + + --with-libtool[=XXX] + Generate libraries with libtool. If this option is selected, then it + overrides all other library model specifications. Note that libtool + must already be installed, uses makefile rules dependent on GNU make, + and does not promise to follow the version numbering convention of + other shared libraries on your system. However, if the --with-shared + option does not succeed, you may get better results with this option. + + If a parameter value is given, it must be the full pathname of the + particular version of libtool, e.g., + /usr/bin/libtool-1.2.3 + + --with-manpage-aliases + Tell the configure script you wish to create entries in the + man-directory for aliases to manpages which list them, e.g., the + functions in the panel manpage. This is the default. You can disable + it if your man program does this. You can also disable + --with-manpage-symlinks to install files containing a ".so" command + rather than symbolic links. + + --with-manpage-format=XXX + Tell the configure script how you would like to install man-pages. The + option value must be one of these: gzip, compress, BSDI, normal, + formatted. If you do not give this option, the configure script + attempts to determine which is the case. + + --with-manpage-renames=XXX + Tell the configure script that you wish to rename the manpages while + installing. Currently the only distribution which does this is + the Linux Debian. The option value specifies the name of a file + that lists the renamed files, e.g., $srcdir/man/man_db.renames + + --with-manpage-symlinks + Tell the configure script that you wish to make symbolic links in the + man-directory for aliases to the man-pages. This is the default, but + can be disabled for systems that provide this automatically. Doing + this on systems that do not support symbolic links will result in + copying the man-page for each alias. + + --with-manpage-tbl + Tell the configure script that you with to preprocess the manpages + by running them through tbl to generate tables understandable by + nroff. + + --with-ospeed=TYPE + Override type of ospeed variable, which is part of the termcap + compatibility interface. In termcap, this is a 'short', which works + for a wide range of baudrates because ospeed is not the actual speed + but the encoded value, e.g., B9600 would be a small number such as 13. + However the encoding scheme originally allowed for values "only" up to + 38400bd. A newer set of definitions past 38400bd is not encoded as + compactly, and is not guaranteed to fit into a short (see the function + cfgetospeed(), which returns a speed_t for this reason). In practice, + applications that required knowledge of the ospeed variable, i.e., + those using termcap, do not use the higher speeds. Your application + (or system, in general) may or may not. + + --with-normal + Generate normal (i.e., static) libraries (default). + + --with-profile + Generate profile-libraries These are named by adding "_p" to the root, + e.g., libncurses_p.a + + --with-rcs-ids + Compile-in RCS identifiers. Most of the C files have an identifier. + + --with-rel-version=NUM + Override the release version, which may be used in shared library + filenames. This consists of a major and minor version number separated + by ".". Normally the major version number is the same as the ABI + version; some ports have special requirements for compatibility. + + --with-shared + Generate shared-libraries. The names given depend on the system for + which you are building, typically using a ".so" suffix, along with + symbolic links that refer to the release version. + + NOTE: Unless you override the configure script by setting the $CFLAGS + environment variable, these will not be built with the -g debugging + option. + + --with-shlib-version=XXX + Specify whether to use the release or ABI version for shared libraries. + This is normally chosen automatically based on the type of system + which you are building on. We use it for testing the configure script. + + --with-sysmouse + use FreeBSD sysmouse interface provide mouse support on the console. + + --with-system-type=XXX + For testing, override the derived host system-type which is used to + decide things such as the linker commands used to build shared + libraries. This is normally chosen automatically based on the type of + system which you are building on. We use it for testing the configure + script. + + --with-terminfo-dirs=XXX + Specify a search-list of terminfo directories which will be compiled + into the ncurses library (default: DATADIR/terminfo) + + --with-termlib[=XXX] + When building the ncurses library, organize this as two parts: the + curses library (libncurses) and the low-level terminfo library + (libtinfo). This is done to accommodate applications that use only + the latter. The terminfo library is about half the size of the total. + + If an option value is given, that overrides the name of the terminfo + library. For instance, if the wide-character version is built, the + terminfo library would be named libtinfow. But the libtinfow interface + is upward compatible from libtinfo, so it would be possible to overlay + libtinfo.so with a "wide" version of libtinfow.so by renaming it with + this option. + + --with-termpath=XXX + Specify a search-list of termcap files which will be compiled into the + ncurses library (default: /etc/termcap:/usr/share/misc/termcap) + + --with-trace + Configure the trace() function as part of the all models of the ncurses + library. Normally it is part of the debug (libncurses_g) library only. + + --without-ada + Suppress the configure script's check for Ada95, do not build the + Ada95 binding and related demo. + + --without-curses-h + Don't install the ncurses header with the name "curses.h". Rather, + install as "ncurses.h" and modify the installed headers and manpages + accordingly. + + --without-cxx + XSI curses declares "bool" as part of the interface. C++ also declares + "bool". Neither specifies the size and type of booleans, but both + insist on the same name. We chose to accommodate this by making the + configure script check for the size and type (e.g., unsigned or signed) + that your C++ compiler uses for booleans. If you do not wish to use + ncurses with C++, use this option to tell the configure script to not + adjust ncurses bool to match C++. + + --without-cxx-binding + Suppress the configure script's check for C++, do not build the + C++ binding and related demo. + + --without-progs + Tell the configure script to suppress the build of ncurses' application + programs (e.g., tic). The test applications will still be built if you + type "make", though not if you simply do "make install". + + --without-xterm-new + Tell the configure script to use "xterm-old" for the entry used in + the terminfo database. This will work with variations such as + X11R5 and X11R6 xterm. + + +COMPATIBILITY WITH OLDER VERSIONS OF NCURSES: +-------------------------------------------- + + Because ncurses implements the X/Open Curses Specification, its interface + is fairly stable. That does not mean the interface does not change. + Changes are made to the documented interfaces when we find differences + between ncurses and X/Open or implementations which they certify (such as + Solaris). We add extensions to those interfaces to solve problems not + addressed by the original curses design, but those must not conflict with + the X/Open documentation. + + Here are some of the major interface changes, and related problems which + you may encounter when building a system with different versions of + ncurses: + + 5.4 (February 8, 2004) + Interface changes: + + + add the remaining functions for X/Open curses wide-character support. + These are only available if the library is configured using the + --enable-widec option. + pecho_wchar() + slk_wset() + + + write getyx() and related 2-return macros in terms of getcury(), + getcurx(), etc. + + + simplify ifdef for bool declaration in curses.h + + + modify ifdef's in curses.h that disabled use of __attribute__() for + g++, since recent versions implement the cases which ncurses uses. + + + change some interfaces to use const: + define_key() + mvprintw() + mvwprintw() + printw() + vw_printw() + winsnstr() + wprintw() + + Added extensions: + key_defined() + Added internal functions: + _nc_get_locale() + _nc_insert_ch() + _nc_is_charable() wide + _nc_locale_breaks_acs() + _nc_pathlast() + _nc_to_char() wide + _nc_to_widechar() wide + _nc_tparm_analyze() + _nc_trace_bufcat() debug + _nc_unicode_locale() + Removed internal functions: + _nc_outstr() + _nc_sigaction() + Modified internal functions: + _nc_remove_string() + _nc_retrace_chtype() + + 5.3 (October 12, 2002) + Interface changes: + + + change type for bool used in headers to NCURSES_BOOL, which usually + is the same as the compiler's definition for 'bool'. + + + add all but two functions for X/Open curses wide-character support. + These are only available if the library is configured using the + --enable-widec option. Missing functions are + pecho_wchar() + slk_wset() + + + add environment variable $NCURSES_ASSUMED_COLORS to modify the + assume_default_colors() extension. + + Added extensions: + is_term_resized() + resize_term() + Added internal functions: + _nc_altcharset_name() debug + _nc_reset_colors() + _nc_retrace_bool() debug + _nc_retrace_unsigned() debug + _nc_rootname() + _nc_trace_ttymode() debug + _nc_varargs() debug + _nc_visbufn() debug + _nc_wgetch() + Removed internal functions: + _nc_background() + Modified internal functions: + _nc_freeall() debug + + 5.2 (October 21, 2000) + Interface changes: + + + revert termcap ospeed variable to 'short' (see discussion of the + --with-ospeed configure option). + + 5.1 (July 8, 2000) + Interface changes: + + + made the extended terminal capabilities + (configure --enable-tcap-names) a standard feature. This should + be transparent to applications that do not require it. + + + removed the trace() function and related trace support from the + production library. + + + modified curses.h.in, undef'ing some symbols to avoid conflict + with C++ STL. + + Added extensions: assume_default_colors(). + + 5.0 (October 23, 1999) + Interface changes: + + + implemented the wcolor_set() and slk_color() functions. + + + move macro winch to a function, to hide details of struct ldat + + + corrected prototypes for slk_* functions, using chtype rather than + attr_t. + + + the slk_attr_{set,off,on} functions need an additional void* + parameter according to XSI. + + + modified several prototypes to correspond with 1997 version of X/Open + Curses: [w]attr_get(), [w]attr_set(), border_set() have different + parameters. Some functions were renamed or misspelled: + erase_wchar(), in_wchntr(), mvin_wchntr(). Some developers have used + attr_get(). + + Added extensions: keybound(), curses_version(). + + Terminfo database changes: + + + change translation for termcap 'rs' to terminfo 'rs2', which is + the documented equivalent, rather than 'rs1'. + + The problems are subtler in recent releases. + + a) This release provides users with the ability to define their own + terminal capability extensions, like termcap. To accomplish this, + we redesigned the TERMTYPE struct (in term.h). Very few + applications use this struct. They must be recompiled to work with + the 5.0 library. + + a) If you use the extended terminfo names (i.e., you used configure + --enable-tcap-names), the resulting terminfo database can have some + entries which are not readable by older versions of ncurses. This + is a bug in the older versions: + + + the terminfo database stores booleans, numbers and strings in + arrays. The capabilities that are listed in the arrays are + specified by X/Open. ncurses recognizes a number of obsolete and + extended names which are stored past the end of the specified + entries. + + + a change to read_entry.c in 951001 made the library do an lseek() + call incorrectly skipping data which is already read from the + string array. This happens when the number of strings in the + terminfo data file is greater than STRCOUNT, the number of + specified and obsolete or extended strings. + + + as part of alignment with the X/Open final specification, in the + 990109 patch we added two new terminfo capabilities: + set_a_attributes and set_pglen_inch). This makes the indices for + the obsolete and extended capabilities shift up by 2. + + + the last two capabilities in the obsolete/extended list are memu + and meml, which are found in most terminfo descriptions for xterm. + + When trying to read this terminfo entry, the spurious lseek() + causes the library to attempt to read the final portion of the + terminfo data (the text of the string capabilities) 4 characters + past its starting point, and reads 4 characters too few. The + library rejects the data, and applications are unable to + initialize that terminal type. + + FIX: remove memu and meml from the xterm description. They are + obsolete, not used by ncurses. (It appears that the feature was + added to xterm to make it more like hpterm). + + This is not a problem if you do not use the -x option of tic to + create a terminfo database with extended names. Note that the + user-defined terminal capabilities are not affected by this bug, + since they are stored in a table after the older terminfo data ends, + and are invisible to the older libraries. + + c) Some developers did not wish to use the C++ binding, and used the + configure --without-cxx option. This causes problems if someone + uses the ncurses library from C++ because that configure test + determines the type for C++'s bool and makes ncurses match it, since + both C++ and curses are specified to declare bool. Calling ncurses + functions with the incorrect type for bool will cause execution + errors. In 5.0 we added a configure option "--without-cxx-binding" + which controls whether the binding itself is built and installed. + + 4.2 (March 2, 1998) + Interface changes: + + + correct prototype for termattrs() as per XPG4 version 2. + + + add placeholder prototypes for color_set(), erasewchar(), + term_attrs(), wcolor_set() as per XPG4 version 2. + + + add macros getcur[xy] getbeg[xy] getpar[xy], which are defined in + SVr4 headers. + + New extensions: keyok() and define_key(). + + Terminfo database changes: + + + corrected definition in curses.h for ACS_LANTERN, which was 'I' + rather than 'i'. + + 4.1 (May 15, 1997) + + We added these extensions: use_default_colors(). Also added + configure option --enable-const, to support the use of const where + X/Open should have, but did not, specify. + + The terminfo database content changed the representation of color for + most entries that use ANSI colors. SVr4 curses treats the setaf/setab + and setf/setb capabilities differently, interchanging the red/blue + colors in the latter. + + 4.0 (December 24, 1996) + + We bumped to version 4.0 because the newly released dynamic loader + (ld.so.1.8.5) on Linux did not load shared libraries whose ABI and REL + versions were inconsistent. At that point, ncurses ABI was 3.4 and the + REL was 1.9.9g, so we made them consistent. + + 1.9.9g (December 1, 1996) + + This fixed most of the problems with 1.9.9e, and made these interface + changes: + + + remove tparam(), which had been provided for compatibility with + some termcap. tparm() is standard, and does not conflict with + application's fallback for missing tparam(). + + + turn off hardware echo in initscr(). This changes the sense of the + echo() function, which was initialized to echoing rather than + nonechoing (the latter is specified). There were several other + corrections to the terminal I/O settings which cause applications to + behave differently. + + + implemented several functions (such as attr_on()) which were + available only as macros. + + + corrected several typos in curses.h.in (i.e., the mvXXXX macros). + + + corrected prototypes for delay_output(), + has_color, immedok() and idcok(). + + + corrected misspelled getbkgd(). Some applications used the + misspelled name. + + + added _yoffset to WINDOW. The size of WINDOW does not impact + applications, since they use only pointers to WINDOW structs. + + These changes were made to the terminfo database: + + + removed boolean 'getm' which was available as an extended name. + + We added these extensions: wresize(), resizeterm(), has_key() and + mcprint(). + + 1.9.9e (March 24, 1996) + + not recommended (a last-minute/untested change left the forms and + menus libraries unusable since they do not repaint the screen). + Foreground/background colors are combined incorrectly, working properly + only on a black background. When this was released, the X/Open + specification was available only in draft form. + + Some applications (such as lxdialog) were "fixed" to work with the + incorrect color scheme. + + +IF YOU ARE A SYSTEM INTEGRATOR: +------------------------------ + + Configuration and Installation: + + On platforms where ncurses is assumed to be installed in /usr/lib, + the configure script uses "/usr" as a default: + + Linux, FreeBSD, NetBSD, OpenBSD, Cygwin + + For other platforms, the default is "/usr/local". See the discussion + of the "--disable-overwrite" option. + + The location of the terminfo is set indirectly by the "--datadir" + configure option, e.g., /usr/share/terminfo, given a datadir of + /usr/share. You may want to override this if you are installing + ncurses libraries in nonstandard locations, but wish to share the + terminfo database. + + Normally the ncurses library is configured in a pure-terminfo mode; + that is, with the --disable-termcap option. This makes 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 speeds up termcap-based + startups, at the expense of not allowing personal termcap entries to + reference the terminfo tree. See comments in + ncurses/tinfo/read_termcap.c for further 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 systems there has been a practice of designating the system + console driver type as `console'. Please do not do this! 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 a modern xterm based on XFree86 (i.e., xterm-new). The + earlier X11R6 entry (xterm-r6) and X11R5 entry (xterm-r5) is provided + as well. See the --without-xterm-new configure script option if you + are unable to update your system. + + +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 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 or part of libcurses.so (the BSD + curses) into the libgpm.so file, producing symbol conflicts with + ncurses (specifically the wgetch function). 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. + See the FAQ: + + http://invisible-island.net/ncurses/ncurses.faq.html#using_gpm_lib + +BUILDING NCURSES WITH A CROSS-COMPILER + Ncurses can be built with a cross-compiler. Some parts must be built + with the host's compiler since they are used for building programs + (e.g., ncurses/make_hash and ncurses/make_keys) that generate tables + that are compiled into the ncurses library. You should set the + BUILD_CC environment variable to your host's compiler, and run the + configure script configuring for the cross-compiler. + + Note that all of the generated source-files which are part of ncurses + will be made if you use + + make sources + + This would be useful in porting to an environment which has little + support for the tools used to generate the sources, e.g., sed, awk and + Bourne-shell. + +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 doc directory includes some guidelines + on how to report bugs in ways that will get them fixed most quickly. |