ncurses 6.2 - patch 20200308
[ncurses.git] / INSTALL
diff --git a/INSTALL b/INSTALL
index 38dce8834ff67c2077ed722439630f51d3460a54..8ce3878ce93467aa615d17745bb698a27ed47d2f 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -1,5 +1,6 @@
 -------------------------------------------------------------------------------
--- Copyright (c) 1998-2018,2019 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.212 2019/01/19 17:42:30 tom Exp $
+-- $Id: INSTALL,v 1.221 2020/03/08 14:27:08 tom Exp $
 ---------------------------------------------------------------------
              How to install Ncurses/Terminfo on your system
 ---------------------------------------------------------------------
@@ -438,6 +439,23 @@ 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 shared libraries during install.  Use this option to simply
@@ -492,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.
@@ -778,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)
 
@@ -860,6 +881,9 @@ SUMMARY OF CONFIGURE OPTIONS:
        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
@@ -903,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
@@ -954,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"
@@ -1033,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
@@ -1060,6 +1096,9 @@ 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.
@@ -1173,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
@@ -1329,6 +1372,43 @@ 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:
 
@@ -2120,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
 
@@ -2130,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
@@ -2138,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