X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=INSTALL;h=bc3a4f849552f03267912e49102ad8f214fd7786;hp=8743d4941cff1b6a14b5d153d6c0aa2ce69b6668;hb=55ccd2b959766810cf7db8d1c4462f338ce0afc8;hpb=a8987e73ec254703634802b4f7ee30d3a485524d diff --git a/INSTALL b/INSTALL index 8743d494..bc3a4f84 100644 --- a/INSTALL +++ b/INSTALL @@ -1,4 +1,4 @@ --- $Id: INSTALL,v 1.71 2004/02/07 21:06:05 tom Exp $ +-- $Id: INSTALL,v 1.98 2005/10/09 14:09:37 tom Exp $ --------------------------------------------------------------------- How to install Ncurses/Terminfo on your system --------------------------------------------------------------------- @@ -19,12 +19,6 @@ 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. @@ -45,7 +39,7 @@ do anything else. REQUIREMENTS: ------------ -You will need the following in order to build and install ncurses under UNIX: +You will need the following to build and install ncurses under UNIX: * ANSI C compiler (gcc, for instance) * sh (bash will do) @@ -64,9 +58,10 @@ INSTALLATION PROCEDURE: 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. + 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: @@ -77,9 +72,20 @@ INSTALLATION PROCEDURE: 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. + 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. @@ -294,10 +300,22 @@ SUMMARY OF CONFIGURE OPTIONS: more likely writable than the system terminfo database. Use this option to disable the feature altogether. + --disable-largefile + Disable compiler flags needed to use large-file interfaces. + --disable-leaks For testing, compile-in code that frees memory that normally would not be freed, to simplify analysis of memory-leaks. + --disable-lp64 + The header files will ignore use of the _LP64 symbol to make chtype + and mmask_t types 32 bits (they may be long on 64-bit hosts, for + compatibility with older releases). + + NOTE: this is potentially an ABI change, depending on existing + packages. The default for this option is "disabled" for ncurses + ABI 5, and "enabled" for ABI 6. + --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 @@ -379,6 +397,24 @@ SUMMARY OF CONFIGURE OPTIONS: For testing, generate functions for certain macros to make them visible as such to the debugger. See also the --disable-macros option. + --enable-ext-colors + Extend the cchar_t structure to allow more than 16 colors to be + encoded. This applies only to the wide-character (--enable-widec) + configuration. + + NOTE: using this option will make libraries which are not binary- + compatible with libncursesw 5.4. None of the interfaces change, but + applications which have an array of cchar_t's must be recompiled. + + --enable-ext-mouse + Modify the encoding of mouse state to make room for a 5th mouse button. + That allows one to use ncurses with a wheel mouse with xterm or + similar X terminal emulators. + + NOTE: using this option will make libraries which are not binary- + compatible with libncursesw 5.4. None of the interfaces change, but + applications which have mouse mask mmask_t's must be recompiled. + --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 @@ -388,7 +424,7 @@ SUMMARY OF CONFIGURE OPTIONS: --enable-getcap-cache Cache translated termcaps under the directory $HOME/.terminfo - NOTE: this sounds good - it makes ncurses run faster the second time. + 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 @@ -444,9 +480,9 @@ SUMMARY OF CONFIGURE OPTIONS: Turn on GCC compiler warnings. There should be only a few. --enable-widec - Compile with experimental wide-character code. This makes a different - version of the libraries (e.g., libncursesw.so), which stores - characters as wide-characters, + 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 @@ -470,7 +506,7 @@ SUMMARY OF CONFIGURE OPTIONS: Specify the Ada95 compiler command (default "gnatmake") --with-ada-include=DIR - Tell where to install the Ada includes (default: + Tell where to install the Ada includes (default: PREFIX/lib/ada/adainclude) --with-ada-objects=DIR @@ -516,6 +552,13 @@ SUMMARY OF CONFIGURE OPTIONS: to use a terminfo database which is compatible with the native applications. + --with-chtype=TYPE + Override type of chtype, which stores the video attributes and (if + --enable-widec is not given) a character. Prior to ncurses 5.5, this + was always unsigned long, but with ncurses 5.5, it may be unsigned. + Use this option if you need to preserve compatibility with 64-bit + executables. + --with-database=XXX Specify the terminfo source file to install. Usually you will wish to install ncurses' default (misc/terminfo.src). Certain systems @@ -546,12 +589,19 @@ SUMMARY OF CONFIGURE OPTIONS: --with-gpm use Alessandro Rubini's GPM library to provide mouse support on the - Linux console. + Linux console. Prior to ncurses 5.5, this introduced a dependency + on the GPM library. Currently ncurses uses the dlsym() function to + bind to the at runtime, so it is only necessary that the library be + present when ncurses is built. --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. + 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. @@ -568,6 +618,12 @@ SUMMARY OF CONFIGURE OPTIONS: particular version of libtool, e.g., /usr/bin/libtool-1.2.3 + It is possible to rebuild the configure script to use the automake + macros for libtool, e.g., AC_PROG_LIBTOOL. See the comments in + aclocal.m4 for CF_PROG_LIBTOOL, and ensure that you build configure + using the appropriate patch for autoconf from + http://invisible-island.net/autoconf/ + --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 @@ -600,11 +656,17 @@ SUMMARY OF CONFIGURE OPTIONS: by running them through tbl to generate tables understandable by nroff. + --with-mmask-t=TYPE + Override type of mmask_t, which stores the mouse mask. Prior to + ncurses 5.5, this was always unsigned long, but with ncurses 5.5, it + may be unsigned. Use this option if you need to preserve compatibility + with 64-bit executables. + --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. + 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 @@ -633,11 +695,21 @@ SUMMARY OF CONFIGURE OPTIONS: 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. + NOTE: For some configurations, e.g., installing a new version of + ncurses shared libraries on a machine which already has ncurses + shared libraries, you may encounter problems with the linker. + For example, it may prevent you from running the build tree's + copy of tic (for installing the terminfo database) because it + loads the system's copy of the ncurses shared libraries. In that + case, using the misc/shlib script may be helpful, since it sets + $LD_LIBRARY_PATH to point to the build tree, e.g., + ./misc/shlib make install + --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 @@ -657,12 +729,19 @@ SUMMARY OF CONFIGURE OPTIONS: Specify a search-list of terminfo directories which will be compiled into the ncurses library (default: DATADIR/terminfo) - --with-termlib + --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) @@ -698,6 +777,11 @@ SUMMARY OF CONFIGURE OPTIONS: 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: -------------------------------------------- @@ -714,10 +798,82 @@ COMPATIBILITY WITH OLDER VERSIONS OF NCURSES: you may encounter when building a system with different versions of ncurses: + 5.5 (October 10, 2005) + Interface changes: + + + terminfo installs "xterm-new" as "xterm" entry rather than + "xterm-old" (aka xterm-r6). + + + terminfo data is installed using the tic -x option (few systems + still use ncurses 4.2). + + + modify C++ binding to work with newer C++ compilers by providing + initializers and using modern casts. Old-style header names are + still used in this release to allow compiling with not-so-old + compilers. + + + form and menu libraries now work with wide-character data. + Applications which bypassed the form library and manipulated the + FIELD.buf data directly will not work properly with libformw, since + that no longer points to an array of char. The set_field_buffer() + and field_buffer() functions translate to/from the actual field + data. + + + change SP->_current_attr to a pointer, adjust ifdef's to ensure that + libtinfo.so and libtinfow.so have the same ABI. The reason for this + is that the corresponding data which belongs to the upper-level + ncurses library has a different size in each model. + + + winnstr() now returns multibyte character strings for the + wide-character configuration. + + + assume_default_colors() no longer requires that use_default_colors() + be called first. + + + data_ahead() now works with wide-characters. + + + slk_set() and slk_wset() now accept and store multibyte or + multicolumn characters. + + + start_color() now returns OK if colors have already been started. + start_color() also returns ERR if it cannot allocate memory. + + + pair_content() now returns -1 for consistency with init_pair() if it + corresponds to the default-color. + + + unctrl() now returns null if its parameter does not correspond + to an unsigned char. + + Added extensions: + Experimental mouse version 2 supports wheel mice with buttons + 4 and 5. This requires ABI 6 because it modifies the encoding + of mouse events. + + Experimental extended colors allows encoding of 256 foreground + and background colors, e.g., with the xterm-256color or + xterm-88color terminfo entries. This requires ABI 6 because + it changes the size of cchar_t. + + Added internal functions: + _nc_check_termtype2 + _nc_resolve_uses2 + _nc_retrace_cptr + _nc_retrace_cvoid_ptr + _nc_retrace_void_ptr + _nc_setup_term + + Removed internal functions: + none + + Modified internal functions: + _nc_insert_ch + _nc_save_str + _nc_trans_string + 5.4 (February 8, 2004) Interface changes: - + add the remaining functions for X/Open curses wide-character support. + + 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() @@ -742,6 +898,7 @@ COMPATIBILITY WITH OLDER VERSIONS OF NCURSES: Added extensions: key_defined() + Added internal functions: _nc_get_locale() _nc_insert_ch() @@ -753,9 +910,11 @@ COMPATIBILITY WITH OLDER VERSIONS OF NCURSES: _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() @@ -778,6 +937,7 @@ COMPATIBILITY WITH OLDER VERSIONS OF NCURSES: Added extensions: is_term_resized() resize_term() + Added internal functions: _nc_altcharset_name() debug _nc_reset_colors() @@ -788,8 +948,10 @@ COMPATIBILITY WITH OLDER VERSIONS OF NCURSES: _nc_varargs() debug _nc_visbufn() debug _nc_wgetch() + Removed internal functions: _nc_background() + Modified internal functions: _nc_freeall() debug @@ -1063,17 +1225,10 @@ 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). + 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: @@ -1082,7 +1237,8 @@ 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. + pre-fetched fallback entries. This must be done on a machine which + has ncurses' infocmp and terminfo database installed. These entries are checked by setupterm() only when the conventional fetches from the terminfo tree and the termcap fallback (if configured) @@ -1090,23 +1246,23 @@ CONFIGURING FALLBACK ENTRIES: 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). + 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 + ncurses/tinfo/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 + tinfo/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 + tinfo/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 @@ -1186,45 +1342,37 @@ USING NCURSES WITH AFS: 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 + 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: + linking applications by combining all or part of libcurses.so into the + libgpm.so file, producing symbol conflicts with ncurses (specifically + the wgetch function). This was originally the BSD curses, but + generally whatever curses library exists on the system. + + 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: + See the FAQ, as well as the discussion under the --with-gpm option: - dickey.his.com:/ncurses/gpm-1.10-970125.tar.gz - - This patch is incorporated in gpm 1.12; however some integrators - are slow to update this library. Current distributions of gpm can - be configured properly using the --without-curses option. + 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. + that are compiled into the ncurses library. The essential thing to do + is set the BUILD_CC environment variable to your host's compiler, and + run the configure script configuring for the cross-compiler. + + The configure options --with-build-cc, etc., are provided to make this + simpler. Since make_hash and make_keys use only ANSI C features, it + is normally not necessary to provide the other options such as + --with-build-libs, but they are provided for completeness. Note that all of the generated source-files which are part of ncurses will be made if you use @@ -1235,6 +1383,12 @@ BUILDING NCURSES WITH A CROSS-COMPILER support for the tools used to generate the sources, e.g., sed, awk and Bourne-shell. + When ncurses has been successfully cross-compiled, you may want to use + "make install" (with a suitable target directory) to construct an + install tree. Note that in this case (as with the --with-fallbacks + option), ncurses uses the development platform's tic to do the + "make install.data" portion. + BUGS: Send any feedback to the ncurses mailing list at bug-ncurses@gnu.org. To subscribe send mail to