ncurses 5.6 - patch 20071117
[ncurses.git] / INSTALL
diff --git a/INSTALL b/INSTALL
index bc3a4f849552f03267912e49102ad8f214fd7786..9d972ef0275efbb83a0706967ee3018ab74de012 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.120 2007/11/17 22:05:11 tom Exp $
 ---------------------------------------------------------------------
              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.
 
+    --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
@@ -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.
 
+       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
@@ -318,8 +360,8 @@ SUMMARY OF CONFIGURE OPTIONS:
 
     --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
@@ -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
 
+    --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
@@ -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.
 
+    --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.
@@ -421,6 +475,13 @@ SUMMARY OF CONFIGURE OPTIONS:
        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
 
@@ -437,16 +498,37 @@ SUMMARY OF CONFIGURE OPTIONS:
        may not be accurate, or that your stty settings have disabled the use
        of tabs.
 
+    --enable-mixed-case
+       Controls whether the filesystem on which the terminfo database resides
+       supports mixed-case filenames (normal for UNIX, but not on other
+       systems).  If you do not specify this option, the configure script
+       checks the current filesystem.
+
     --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-reentrant
+       Compile experimental configuration which improves reentrant use of the
+       library by reducing global and static variables.
+
     --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
@@ -460,6 +542,13 @@ SUMMARY OF CONFIGURE OPTIONS:
        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
@@ -479,6 +568,9 @@ SUMMARY OF CONFIGURE OPTIONS:
     --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
@@ -567,6 +659,7 @@ SUMMARY OF CONFIGURE OPTIONS:
 
     --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"
@@ -576,12 +669,9 @@ SUMMARY OF CONFIGURE OPTIONS:
        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.
+       This also sets the --disable-leaks option.
 
     --with-fallbacks=XXX
        Specify a list of fallback terminal descriptions which will be
@@ -589,10 +679,37 @@ SUMMARY OF CONFIGURE OPTIONS:
 
     --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
@@ -678,6 +795,11 @@ SUMMARY OF CONFIGURE OPTIONS:
     --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
@@ -746,10 +868,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)
 
+    --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-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.
@@ -772,6 +907,13 @@ SUMMARY OF CONFIGURE OPTIONS:
        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
@@ -798,6 +940,61 @@ COMPATIBILITY WITH OLDER 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:
 
@@ -1397,3 +1594,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.
+
+-- vile:txtmode