ncurses 5.6 - patch 20070812

[ncurses.git] / INSTALL

diff --git a/INSTALL b/INSTALL
index bc3a4f849552f03267912e49102ad8f214fd7786..a8f5e90b73d813b8a3ffdffab284f85960649837 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -1,4 +1,31 @@
--- $Id: INSTALL,v 1.98 2005/10/09 14:09:37 tom Exp $
+-------------------------------------------------------------------------------
+-- Copyright (c) 1998-2005,2006 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             --
+-- "Software"), to deal in the Software without restriction, including       --
+-- without limitation the rights to use, copy, modify, merge, publish,       --
+-- distribute, distribute with modifications, sublicense, and/or sell copies --
+-- of the Software, and to permit persons to whom the Software is furnished  --
+-- to do so, subject to the following conditions:                            --
+--                                                                           --
+-- The above copyright notice and this permission notice shall be included   --
+-- in all copies or substantial portions of the Software.                    --
+--                                                                           --
+-- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS   --
+-- OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF                --
+-- MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN --
+-- NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,       --
+-- DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR     --
+-- OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE --
+-- USE OR OTHER DEALINGS IN THE SOFTWARE.                                    --
+--                                                                           --
+-- Except as contained in this notice, the name(s) of the above copyright    --
+-- holders shall not be used in advertising or otherwise to promote the      --
+-- sale, use or other dealings in this Software without prior written        --
+-- authorization.                                                            --
+-------------------------------------------------------------------------------
+-- $Id: INSTALL,v 1.119 2007/07/28 19:56:35 tom Exp $

 ---------------------------------------------------------------------
              How to install Ncurses/Terminfo on your system
 ---------------------------------------------------------------------
 ---------------------------------------------------------------------
              How to install Ncurses/Terminfo on your system
 ---------------------------------------------------------------------


@@ -277,6 +304,11 @@ SUMMARY OF CONFIGURE OPTIONS:
        return deceptive results, so you may have to override the configure
        script.  Or you may be building tic for a smaller machine.
 
        return deceptive results, so you may have to override the configure
        script.  Or you may be building tic for a smaller machine.
 

+    --disable-big-strings
+       Disable compile-time optimization of predefined tables which puts
+       all of their strings into a very long string, to reduce relocation
+       overhead.
+

     --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
     --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


@@ -307,6 +339,16 @@ SUMMARY OF CONFIGURE OPTIONS:
        For testing, compile-in code that frees memory that normally would not
        be freed, to simplify analysis of memory-leaks.
 
        For testing, compile-in code that frees memory that normally would not
        be freed, to simplify analysis of memory-leaks.
 

+       Any implementation of curses must not free the memory associated with
+       a screen, since (even after calling endwin()), it must be available
+       for use in the next call to refresh().  There are also chunks of
+       memory held for performance reasons.  That makes it hard to analyze
+       curses applications for memory leaks.  To work around this, build
+       a debugging version of the ncurses library which frees those chunks
+       which it can, and provides the _nc_free_and_exit() function to free
+       the remainder on exit.  The ncurses utility and test programs use this
+       feature, e.g., via the ExitProgram() macro.
+

     --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
     --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


@@ -318,8 +360,8 @@ SUMMARY OF CONFIGURE OPTIONS:
 
     --disable-macros
        For testing, use functions rather than macros.  The program will run
 
     --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.
+       more slowly, but it is simpler to debug.  This defines NCURSES_NOMACROS
+       at build time.  See also the --enable-expanded option.

 
     --disable-overwrite
        If you are installing ncurses on a system which contains another
 
     --disable-overwrite
        If you are installing ncurses on a system which contains another


@@ -331,6 +373,13 @@ SUMMARY OF CONFIGURE OPTIONS:
        rather than the include directory.  This makes it simpler to avoid
        compile-time conflicts with other versions of curses.h
 
        rather than the include directory.  This makes it simpler to avoid
        compile-time conflicts with other versions of curses.h
 

+    --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.
+
+       This option is ignored if --enable-rpath is not given.
+

     --disable-root-environ
        Compile with environment restriction, so certain environment variables
        are not available when running as root, or via a setuid/setgid
     --disable-root-environ
        Compile with environment restriction, so certain environment variables
        are not available when running as root, or via a setuid/setgid


@@ -341,6 +390,11 @@ SUMMARY OF CONFIGURE OPTIONS:
        Compile without scroll-hints code.  This option is ignored when
        hashmap scrolling is configured, which is the default.
 
        Compile without scroll-hints code.  This option is ignored when
        hashmap scrolling is configured, which is the default.
 

+    --disable-tparm-varargs
+       Portable programs should call tparm() using the fixed-length parameter
+       list documented in X/Open.  ncurses provides varargs support for this
+       function.  Use --disable-tparm-varargs to disable this support.
+

     --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-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.


@@ -421,6 +475,13 @@ SUMMARY OF CONFIGURE OPTIONS:
        cross-references to) the terminfo tree, but it is faster than reading
        /etc/termcap.
 
        cross-references to) the terminfo tree, but it is faster than reading
        /etc/termcap.
 

+       If configured for one of the *BSD systems, this automatically uses
+       the hashed database system produced using cap_mkdb or similar tools.
+       In that case, there is no advantage in using the --enable-getcap-cache
+       option.
+
+       See also the --with-hashed-db option.
+

     --enable-getcap-cache
        Cache translated termcaps under the directory $HOME/.terminfo
 
     --enable-getcap-cache
        Cache translated termcaps under the directory $HOME/.terminfo
 


@@ -443,10 +504,25 @@ SUMMARY OF CONFIGURE OPTIONS:
        terminfo entries.  This is the default, unless you have disabled the
        extended functions.
 
        terminfo entries.  This is the default, unless you have disabled the
        extended functions.
 

+    --enable-reentrant
+       Compile experimental configuration which improves reentrant use of the
+       library by reducing global and static variables.
+

     --enable-rpath
     --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).
+       Use rpath option when generating shared libraries, and (with some
+       restrictions) when linking the corresponding programs.  This originally
+       (in 1997) applied mainly to systems using the GNU linker (read the
+       manpage).
+
+       More recently it is useful for systems that require special treatment
+       shared libraries in "unusual" locations.  The "system" libraries reside
+       in directories which are on the loader's default search-path.  While
+       you may be able to use workarounds such as the $LD_LIBRARY_PATH
+       environment variable, they do not work with setuid applications since
+       the LD_LIBRARY_PATH variable would be unset in that situation.
+
+       This option does not apply to --with-libtool, since libtool makes
+       extra assumptions about rpath.

 
     --enable-safe-sprintf
        Compile with experimental safe-sprintf code.  You may consider using
 
     --enable-safe-sprintf
        Compile with experimental safe-sprintf code.  You may consider using


@@ -460,6 +536,13 @@ SUMMARY OF CONFIGURE OPTIONS:
        changes.  This option is the default, unless you have disabled the
        extended functions.
 
        changes.  This option is the default, unless you have disabled the
        extended functions.
 

+    --enable-signed-char
+       The term.h header declares a Booleans[] array typed "char".  But it
+       stores signed values there and "char" is not necessarily signed.
+       Some packagers choose to alter the type of Booleans[] though this
+       is not strictly compatible.  This option allows one to implement this
+       alteration without patching the source code.
+

     --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
     --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


@@ -479,6 +562,9 @@ SUMMARY OF CONFIGURE OPTIONS:
     --enable-warnings
        Turn on GCC compiler warnings.  There should be only a few.
 
     --enable-warnings
        Turn on GCC compiler warnings.  There should be only a few.
 

+    --enable-wgetch-events
+       Compile with experimental wgetch-events code.  See ncurses/README.IZ
+

     --enable-widec
        Compile with wide-character code.  This makes a different version of
        the libraries (e.g., libncursesw.so), which stores characters as
     --enable-widec
        Compile with wide-character code.  This makes a different version of
        the libraries (e.g., libncursesw.so), which stores characters as


@@ -567,6 +653,7 @@ SUMMARY OF CONFIGURE OPTIONS:
 
     --with-dbmalloc
        For testing, compile and link with Conor Cahill's dbmalloc library.
 
     --with-dbmalloc
        For testing, compile and link with Conor Cahill's dbmalloc library.

+       This also sets the --disable-leaks option.

 
     --with-debug
        Generate debug-libraries (default).  These are named by adding "_g"
 
     --with-debug
        Generate debug-libraries (default).  These are named by adding "_g"


@@ -576,12 +663,9 @@ SUMMARY OF CONFIGURE OPTIONS:
        Specify the default terminfo database directory.  This is normally
        DATADIR/terminfo, e.g., /usr/share/terminfo.
 
        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-dmalloc
        For testing, compile and link with Gray Watson's dmalloc library.

+       This also sets the --disable-leaks option.

 
     --with-fallbacks=XXX
        Specify a list of fallback terminal descriptions which will be
 
     --with-fallbacks=XXX
        Specify a list of fallback terminal descriptions which will be


@@ -589,10 +673,37 @@ SUMMARY OF CONFIGURE OPTIONS:
 
     --with-gpm
        use Alessandro Rubini's GPM library to provide mouse support on the
 
     --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 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.
+       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 library at
+       runtime, so it is only necessary that the library be present when
+       ncurses is built, to obtain the filename (or soname) used in the
+       corresponding dlopen() call.  If you give a value for this option,
+       e.g.,
+
+               --with-gpm=$HOME/tmp/test-gpm.so
+
+       that overrides the configure check for the soname.
+
+       See also --without-dlsym
+
+    --with-hashed-db
+       Use a hashed database for storing terminfo data rather than storing
+       each compiled entry in a separate binary file within a directory
+       tree.
+
+       If you use this option for configuring ncurses, tic will only be able
+       to write entries in the hashed database.  infocmp can still read
+       entries from a directory tree as well as reading entries from the
+       hashed database.  To do this, infocmp determines whether the $TERMINFO
+       variable points to a directory or a file, and reads the directory-tree
+       or hashed database respectively.
+
+       You cannot have a directory containing both hashed-database and
+       filesystem-based terminfo entries.
+
+       See also the --enable-getcap option.

 
     --with-install-prefix=XXX
        Allows you to specify an alternate location for installing ncurses
 
     --with-install-prefix=XXX
        Allows you to specify an alternate location for installing ncurses


@@ -678,6 +789,11 @@ SUMMARY OF CONFIGURE OPTIONS:
     --with-normal
        Generate normal (i.e., static) libraries (default).
 
     --with-normal
        Generate normal (i.e., static) libraries (default).
 

+       Note:  on Linux, the configure script will attempt to use the GPM
+       library via the dlsym() function call.  Use --without-dlsym to disable
+       this feature, or --without-gpm, depending on whether you wish to use
+       GPM.
+

     --with-profile
        Generate profile-libraries These are named by adding "_p" to the root,
        e.g., libncurses_p.a
     --with-profile
        Generate profile-libraries These are named by adding "_p" to the root,
        e.g., libncurses_p.a


@@ -746,10 +862,23 @@ 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)
 
        Specify a search-list of termcap files which will be compiled into the
        ncurses library (default:  /etc/termcap:/usr/share/misc/termcap)
 

+    --with-ticlib[=XXX]
+       When building the ncurses library, build a separate library for
+       the modules that are used only by the utility programs.  Normally
+       those would be bundled with the termlib or ncurses libraries.
+
+       If an option value is given, that overrides the name of the tic
+       library.  As in termlib, there is no ABI difference between the
+       "wide" libticw.so and libtic.so
+

     --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.
 
     --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.
 

+    --with-valgrind
+       For testing, compile with debug option.
+       This also sets the --disable-leaks option.
+

     --without-ada
        Suppress the configure script's check for Ada95, do not build the
        Ada95 binding and related demo.
     --without-ada
        Suppress the configure script's check for Ada95, do not build the
        Ada95 binding and related demo.


@@ -772,6 +901,13 @@ SUMMARY OF CONFIGURE OPTIONS:
        Suppress the configure script's check for C++, do not build the
        C++ binding and related demo.
 
        Suppress the configure script's check for C++, do not build the
        C++ binding and related demo.
 

+    --without-develop
+       Disable development options.  This does not include those that change
+       the interface, such as --enable-widec.
+
+    --without-dlsym
+       Do not use dlsym() to load GPM dynamically.
+

     --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
     --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


@@ -798,6 +934,61 @@ COMPATIBILITY WITH OLDER VERSIONS OF NCURSES:
     you may encounter when building a system with different versions of
     ncurses:
 
     you may encounter when building a system with different versions of
     ncurses:
 

+    5.6 (December 17, 2006)
+       Interface changes:
+
+       + generate linkable stubs for some macros:
+
+         getbegx, getbegy, getcurx, getcury, getmaxx, getmaxy, getparx,
+         getpary, getpary,
+
+         and (for libncursesw)
+
+         wgetbkgrnd
+
+       Added extensions:
+               nofilter()
+               use_legacy_coding()
+
+       Added internal functions:
+               _nc_first_db
+               _nc_get_source
+               _nc_handle_sigwinch
+               _nc_is_abs_path
+               _nc_is_dir_path
+               _nc_is_file_path
+               _nc_keep_tic_dir
+               _nc_keep_tic_dir
+               _nc_last_db
+               _nc_next_db
+               _nc_read_termtype
+               _nc_tic_dir
+
+               Also (if using the hashed database configuration):
+
+               _nc_db_close
+               _nc_db_first
+               _nc_db_get
+               _nc_db_have_data
+               _nc_db_have_index
+               _nc_db_next
+               _nc_db_open
+               _nc_db_put
+
+               otherwise
+
+               _nc_hashed_db
+
+       Removed internal functions:
+               none
+
+       Modified internal functions:
+               _nc_add_to_try
+               _nc_do_color
+               _nc_expand_try
+               _nc_remove_key
+               _nc_setupscreen
+

     5.5 (October 10, 2005)
        Interface changes:
 
     5.5 (October 10, 2005)
        Interface changes:
 


@@ -1397,3 +1588,5 @@ BUGS:
 
        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.
 
        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.

+
+-- vile:txtmode