X-Git-Url: https://ncurses.scripts.mit.edu/?p=ncurses.git;a=blobdiff_plain;f=INSTALL;h=8ce3878ce93467aa615d17745bb698a27ed47d2f;hp=3459f6df43524d98e1f6f058825a8f71a7ea74d5;hb=3ef920d65fb2d4046096131d868ae8d4bba79d46;hpb=1b540608eae9a714c0c4195310f25c1a1897ae89 diff --git a/INSTALL b/INSTALL index 3459f6df..8ce3878c 100644 --- a/INSTALL +++ b/INSTALL @@ -1,5 +1,6 @@ ------------------------------------------------------------------------------- --- Copyright (c) 1998-2015,2016 Free Software Foundation, Inc. -- +-- Copyright 2018-2019,2020 Thomas E. Dickey -- +-- Copyright 1998-2017,2018 Free Software Foundation, Inc. -- -- -- -- Permission is hereby granted, free of charge, to any person obtaining a -- -- copy of this software and associated documentation files (the -- @@ -25,7 +26,7 @@ -- sale, use or other dealings in this Software without prior written -- -- authorization. -- ------------------------------------------------------------------------------- --- $Id: INSTALL,v 1.195 2016/12/11 00:41:03 tom Exp $ +-- $Id: INSTALL,v 1.221 2020/03/08 14:27:08 tom Exp $ --------------------------------------------------------------------- How to install Ncurses/Terminfo on your system --------------------------------------------------------------------- @@ -310,18 +311,27 @@ SUMMARY OF CONFIGURE OPTIONS: 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 + programs are useful in this configuration, e.g., tset and tput versus infocmp and tic. --disable-db-install Do not install the terminal database. This is used to omit features for packages, as done with --without-progs. + --disable-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). + --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-gnat-projects + Disable GNAT projects even if usable, for testing old makefile rules. + --disable-hashmap Compile without hashmap scrolling-optimization code. This algorithm is the default. @@ -335,25 +345,6 @@ SUMMARY OF CONFIGURE OPTIONS: --disable-largefile Disable compiler flags needed to use large-file interfaces. - --disable-lib-suffixes - Suppress the "w", "t" or "tw" suffixes which normally would be added - to the library names for the --enable-widec and --with-pthread options. - - --disable-libtool-version - when using --with-libtool, control how the major/minor version numbers - are used for constructing the library name. - - The default uses the -version-number feature of libtool, which makes - the library names compatible (though not identical) with the standard - build using --with-shared. - - Use --disable-libtool-version to use the libtool -version-info feature. - This corresponds to the setting used before patch 20100515. - - Starting with patch 20141115, using this option causes the configure - script to apply the top-level VERSION file to the ABI version used - for libtool. - --disable-leaks For testing, compile-in code that frees memory that normally would not be freed, to simplify analysis of memory-leaks. @@ -374,6 +365,25 @@ SUMMARY OF CONFIGURE OPTIONS: library resume and reallocate memory, then that would not use a "_nc_" prefix. + --disable-lib-suffixes + Suppress the "w", "t" or "tw" suffixes which normally would be added + to the library names for the --enable-widec and --with-pthread options. + + --disable-libtool-version + when using --with-libtool, control how the major/minor version numbers + are used for constructing the library name. + + The default uses the -version-number feature of libtool, which makes + the library names compatible (though not identical) with the standard + build using --with-shared. + + Use --disable-libtool-version to use the libtool -version-info feature. + This corresponds to the setting used before patch 20100515. + + Starting with patch 20141115, using this option causes the configure + script to apply the top-level VERSION file to the ABI version used + for libtool. + --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 @@ -429,12 +439,37 @@ SUMMARY OF CONFIGURE OPTIONS: Without some special effort, it will either fail to compile at all, or the compiler may find a different unctrl.h file. + In addition to the curses library, a system may provide its own + versions of the add-on libraries (form, menu, panel), which would + not be compatible with ncurses. These options allow you to rename + ncurses' add-on libraries to avoid conflicts when linking: + + --with-form-libname=XXX + --with-menu-libname=XXX + --with-panel-libname=XXX + + Rather than renaming them abitrarily, a prefix or suffix is + recommended. An "n" prefix provides consistency with ncurses versus + curses, i.e., + + --with-form-libname=nform + --with-menu-libname=nmenu + --with-panel-libname=npanel + --disable-relink If --enable-rpath is given, the generated makefiles normally will - rebuild the libraries during install. Use this option to simply - copy whatever the linked produced. + rebuild shared libraries during install. Use this option to simply + copy whatever the linker produced. - This option is ignored if --enable-rpath is not given. + Static libraries cannot simply be copied because tools use timestamps + to determine if the library's symbol table is up to date. If your + install program supports the "-p" (preserve timestamp) option, that + is used when --disable-relink is given, to avoid rebuilding the symbol + table. + + Finally, some tools ignore the subsecond timestamps supported by some + filesystems. This option adds a 1-second sleep to help those tools + avoid unnecessary relinking during the install process. --disable-root-environ Compile with environment restriction, so certain environment variables @@ -452,6 +487,9 @@ SUMMARY OF CONFIGURE OPTIONS: Compile without scroll-hints code. This option is ignored when hashmap scrolling is configured, which is the default. + --disable-stripping + Do not strip installed executables. + --disable-tic-depends When building shared libraries, normally the tic library is linked to depend upon the ncurses library (or equivalently, on the tinfo-library @@ -472,7 +510,7 @@ SUMMARY OF CONFIGURE OPTIONS: --disable-wattr-macros The 6.0 ABI adds support for extended colors and for extended mouse. - The former is a noticeable problem when developers inadvertantly + The former is a noticeable problem when developers inadvertently compile using the ncurses6 header files and link with an ncurses5 library, because the wattr* macros use a new field in the WINDOW structure. These macros are used in several applications. @@ -536,12 +574,6 @@ SUMMARY OF CONFIGURE OPTIONS: 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. @@ -617,6 +649,14 @@ SUMMARY OF CONFIGURE OPTIONS: terminfo entries. This is the default, unless you have disabled the extended functions. + --enable-opaque-curses + --enable-opaque-form + --enable-opaque-menu + --enable-opaque-panel + Define symbol in curses.h which controls whether some library + structures are treated as "opaque". The --enable-opaque-curses option + is overridden by the --enable-reentrant option. + --enable-pc-files If pkg-config is found (see --with-pkg-config), generate ".pc" files for each of the libraries, and install them in pkg-config's library @@ -627,9 +667,9 @@ SUMMARY OF CONFIGURE OPTIONS: call can be interrupted for SIGWINCH. --enable-reentrant - Compile experimental configuration which improves reentrant use of the - library by reducing global and static variables. This option is also - set if --with-pthread is used. + Compile configuration which improves reentrant use of the library by + reducing global and static variables. This option is also set if + --with-pthread is used. Enabling this option adds a "t" to the library names, except for the special case when --enable-weak-symbols is also used. @@ -653,14 +693,8 @@ SUMMARY OF CONFIGURE OPTIONS: --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. + vsnprintf() or vsprintf(). It is slow, however, and is used only on + very old systems which lack vsnprintf(). --enable-signed-char The term.h header declares a Booleans[] array typed "char". But it @@ -669,6 +703,13 @@ SUMMARY OF CONFIGURE OPTIONS: is not strictly compatible. This option allows one to implement this alteration without patching the source code. + --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-sp-funcs Compile-in support for extended functions which accept a SCREEN pointer, reducing the need for juggling the global SP value with set_term() and @@ -755,6 +796,9 @@ SUMMARY OF CONFIGURE OPTIONS: Tell where to install the Ada includes (default: PREFIX/lib/ada/adainclude) + --with-ada-libname=NAME + Override the name of the Ada binding (default: "AdaCurses") + --with-ada-objects=DIR Tell where to install the Ada objects (default: PREFIX/lib/ada/adalib) @@ -771,10 +815,6 @@ SUMMARY OF CONFIGURE OPTIONS: correspond with that in , or defaults to platform-specific sizes). - --with-build-cpp=XXX - This option is provided by the same macro used for $BUILD_CC, etc., - but is not directly used by ncurses. - --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. @@ -789,6 +829,10 @@ SUMMARY OF CONFIGURE OPTIONS: You can also set the environment variable $BUILD_CFLAGS rather than use this option. + --with-build-cpp=XXX + This option is provided by the same macro used for $BUILD_CC, etc., + but is not directly used by ncurses. + --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 @@ -833,6 +877,13 @@ SUMMARY OF CONFIGURE OPTIONS: executables, e.g., by setting "--with-chtype=long" (the configure script supplies "unsigned"). + --with-config-suffix=XXX + Specify a suffix for the ncursesw6-config file, etc., used to work + around conflicts with packages. + + --with-cxx-libname=NAME + Override the basename of the ncurses++ library (default: "ncurses++") + --with-cxx-shared When --with-shared is set, build libncurses++ as a shared library. This implicitly relies upon building with gcc/g++, since other @@ -876,6 +927,11 @@ SUMMARY OF CONFIGURE OPTIONS: Specify a list of fallback terminal descriptions which will be compiled into the ncurses library. See CONFIGURING FALLBACK ENTRIES. + See also "--with-tic-path" and "--with-infocmp-path". + + --with-form-libname=NAME + Override the basename of the form library (default: "form") + --with-gpm use Alessandro Rubini's GPM library to provide mouse support on the Linux console. Prior to ncurses 5.5, this introduced a dependency on @@ -927,6 +983,10 @@ SUMMARY OF CONFIGURE OPTIONS: See also the --enable-getcap option. + --with-infocmp-path[=XXX] + Use this option to override the automatic detection of tic in your + $PATH when building fallbacks (see "--with-fallbacks"). + --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" @@ -965,10 +1025,14 @@ SUMMARY OF CONFIGURE OPTIONS: 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/ + https://invisible-island.net/autoconf/ --with-libtool-opts=XXX - Specify additional libtool options. + Allow user to pass additional libtool options into the library creation + and link steps. The main use for this is to do something like + ./configure --with-libtool-opts=-static + to get the same behavior as automake-flavored + ./configure --enable-static --with-manpage-aliases Tell the configure script you wish to create entries in the @@ -1002,6 +1066,9 @@ SUMMARY OF CONFIGURE OPTIONS: by running them through tbl to generate tables understandable by nroff. + --with-menu-libname=NAME + Override the basename of the menu library (default: "menu") + --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 @@ -1029,11 +1096,23 @@ SUMMARY OF CONFIGURE OPTIONS: those using termcap, do not use the higher speeds. Your application (or system, in general) may or may not. + --with-panel-libname=NAME + Override the basename of the panel library (default: "panel") + --with-pc-suffix=SUFFIX If ".pc" files are installed, optionally add a suffix to the files and corresponding package names to separate unusual configurations. If no option value is given (or if it is "none"), no suffix is added. + --with-pcre2 + Add PCRE2 (Perl-compatible regular expressions v2) to the build if it + is available and the user requests it. Assume the application will + otherwise use the POSIX interface. + + This is useful for MinGW builds because the usual POSIX interface is + not supplied by the development environment, while ncurses' form + library uses a regular expression feature for one of the field types. + --with-pkg-config=[DIR] Check for pkg-config, optionally specifying its path. @@ -1133,6 +1212,10 @@ SUMMARY OF CONFIGURE OPTIONS: Specify a search-list of termcap files which will be compiled into the ncurses library (default: /etc/termcap:/usr/share/misc/termcap) + --with-tic-path[=XXX] + Use this option to override the automatic detection of tic in your + $PATH when building fallbacks (see "--with-fallbacks"). + --with-ticlib[=XXX] When building the ncurses library, build a separate library for the modules that are used only by the utility programs. Normally @@ -1161,6 +1244,10 @@ SUMMARY OF CONFIGURE OPTIONS: 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. + --with-valgrind + For testing, compile with debug option. + This also sets the --disable-leaks option. + --with-versioned-syms[=XXX] The Solaris, GNU and reportedly some other linkers (ld) accept a "--version-script" option which tells the linker to annotate the @@ -1185,25 +1272,13 @@ SUMMARY OF CONFIGURE OPTIONS: scripts which build several configurations for each release version, checking to see which of the "_nc_" symbols can be made local. In addition to the ncurses libraries and programs, the symbols used - by the "tack" program are made global. + by the "tack" program before version 1.08 are made global. These sample ".map" files will not cover all possible combinations. In some cases, e.g., when using the --with-weak-symbols option, you may prefer to use a different ".map" file by setting this option's value. - --with-xterm-kbs=XXX - Configure xterm's terminfo entries to use either BS (^H, i.e., ASCII - backspace) or DEL (^?, or 127). XXX can be BS (or bs, 8) or DEL - (or del, 127). - - During installation, the makefile and scripts modifies the "xterm+kbs" - terminfo entry to use this setting. - - --with-valgrind - For testing, compile with debug option. - This also sets the --disable-leaks option. - --with-wrap-prefix=XXX When using the --enable-reentrant option, ncurses redefines variables that would be global in curses, e.g., LINES, as a macro that calls a @@ -1215,6 +1290,19 @@ SUMMARY OF CONFIGURE OPTIONS: which applications should not call even via a macro. This configure option lets you choose the prefix for these wrapped variables. + --with-x11-rgb=FILE + Provide a pathname for the X11 rgb file, used by the picsmap program. + This overrides a configure check which usually works, but is needed + due to the lack of standardization for X11's files. + + --with-xterm-kbs=XXX + Configure xterm's terminfo entries to use either BS (^H, i.e., ASCII + backspace) or DEL (^?, or 127). XXX can be BS (or bs, 8) or DEL + (or del, 127). + + During installation, the makefile and scripts modifies the "xterm+kbs" + terminfo entry to use this setting. + --without-ada Suppress the configure script's check for Ada95, do not build the Ada95 binding and related demo. @@ -1254,6 +1342,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-tack + Suppress build/install with tack program, if it happens to be + in the same build-tree (tack was moved out of the ncurses source-tree + in 20070203). + --without-tests Tell the configure script to suppress the build of ncurses' test programs. @@ -1267,10 +1360,10 @@ SUMMARY OF CONFIGURE OPTIONS: COMPATIBILITY WITH OLDER VERSIONS OF NCURSES: -------------------------------------------- - Because ncurses implements X/Open Curses, its interface is fairly stable. + Because ncurses implements X/Open Curses, 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 largely correspond to X/Open (such as Solaris). + or implementations which largely correspond to X/Open (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. @@ -1279,6 +1372,128 @@ COMPATIBILITY WITH OLDER VERSIONS OF NCURSES: you may encounter when building a system with different versions of ncurses: + 6.2 (Feb 12, 2020) + Interface changes: + + + the terminal database must be compiled with ncurses 6.2 tic; + older versions of tic/infocmp will not work. Aside from that, + the compiled database will work with older applications. + + + "*.pc" and "ncurses*-config" files give the same information. + + + vwprintw and vwscanw are deprecated. + + Added extensions: + + + These make it simpler to substitute a debug-configuration of the + library for non-debug: + curses_trace + exit_curses + exit_terminfo + + Added internal functions (other than "_sp" variants): + + + These provide fast-lookup of common user-defined capabilities: + _nc_find_user_entry + _nc_get_userdefs_table + _nc_get_hash_user + + + This is added to work around compiler-warnings: + _nc_fmt_funcptr + + Removed internal functions: + + + _nc_import_termtype + + Modified internal functions: + + + _nc_reserve_pairs no longer returns a value + + 6.1 (Jan 27, 2018) + Interface changes: + + + X/Open Curses specifies a "reserved" void* parameter in several + functions, saying that it must be NULL. In this release, if the + parameter is non-NULL, it is interpreted as a point to an integer + containing a color pair. In previous releases, a non-NULL parameter + caused an error return. Portable applications are unaffected. Here + are the functions which have been extended: + attr_get + attr_off + attr_on + attr_set + chgat + color_set + mvchgat + mvwchgat + slk_attr_off + slk_attr_on + slk_attr_set + wattr_get + wattr_on + wattr_off + wattr_set + wchgat + wcolor_set + + + the TERMINAL structure declared in has been made opaque, + and its size increased to handle the increased size of color pair + and color value, as well as other numeric capabilities. + + A few applications required change, e.g., to use def_prog_mode; + only one application (tack) is known to have a valid reason for + accessing these internal details, and that was addressed by the + release of tack 1.08 in 2017. Internal functions marked as used + by tack will be deprecated in future releases. + + Added extensions: + + + Several new functions were added to manipulate extended color pairs + and color values. These include: + alloc_pair + extended_color_content + extended_pair_content + extended_slk_color + find_pair + free_pair + init_extended_color + init_extended_pair + reset_color_pairs + + as well as corresponding sp-functions. + + + A new terminfo capability "RGB" tells the ncurses library that the + color values are red/green/blue, to eliminate the need for palettes + in that special case for the color_content function. + + Added internal functions (other than "_sp" variants): + _nc_copy_termtype2 + _nc_export_termtype2 + _nc_fallback2 + _nc_find_prescr + _nc_forget_prescr + _nc_free_termtype2 + _nc_read_entry2 + _nc_write_object + + Removed internal functions: + _nc_check_termtype + _nc_resolve_uses + + Modified internal functions: + + + symbols are used by tic/infocmp/toe: + _nc_align_termtype - change parameters to TERMTYPE2* + _nc_check_termtype2 - change parameter to TERMTYPE2* + _nc_read_file_entry - change parameter to TERMTYPE2* + _nc_read_termtype - change parameter to TERMTYPE2* + _nc_trim_sgr0 - change parameter to TERMTYPE2* + _nc_write_entry - change parameter to TERMTYPE2* + + + symbols used only within the library: + _nc_fallback - change return type to TERMTYPE2* + _nc_init_termtype - change parameter to TERMTYPE2* + 6.0 (Aug 08, 2015) Interface changes: @@ -1985,9 +2200,10 @@ CONFIGURING FALLBACK ENTRIES: $TERMINFO \ ../misc/terminfo.src \ `which tic` \ + `which infocmp` \ linux vt100 xterm >fallback.c - The first three parameters of the script are normally supplied by + The first four parameters of the script are normally supplied by the configured makefiles via the "--with-fallbacks" option. They are @@ -1995,6 +2211,8 @@ CONFIGURING FALLBACK ENTRIES: 2) the source for the terminfo entries 3) the location of the tic program, used to create a terminfo database. + 4) the location of the infocmp program, used to print a terminfo + description. Then just rebuild and reinstall the library as you would normally. You can restore the default empty fallback list with @@ -2003,10 +2221,11 @@ CONFIGURING FALLBACK ENTRIES: $TERMINFO \ ../misc/terminfo.src \ `which tic` \ + `which infocmp` \ >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 + Any non-empty fallback list is const'd and therefore lives in shareable 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 @@ -2099,7 +2318,7 @@ USING NCURSES WITH GPM: but the linker may not cooperate, producing mysterious errors. See the FAQ, as well as the discussion under the --with-gpm option: - http://invisible-island.net/ncurses/ncurses.faq.html#using_gpm_lib + https://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