ncurses 5.7 - patch 20090829
[ncurses.git] / INSTALL
diff --git a/INSTALL b/INSTALL
index c67aee65ef741a856f2db2f7af38a5e7bb0d72f7..cdc3513ac312ea8721b787d69f9b854e68022957 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -1,5 +1,5 @@
 -------------------------------------------------------------------------------
--- Copyright (c) 1998-2005,2006 Free Software Foundation, Inc.               --
+-- Copyright (c) 1998-2008,2009 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 +25,7 @@
 -- sale, use or other dealings in this Software without prior written        --
 -- authorization.                                                            --
 -------------------------------------------------------------------------------
--- $Id: INSTALL,v 1.118 2007/03/11 00:06:53 tom Exp $
+-- $Id: INSTALL,v 1.140 2009/08/01 19:32:04 tom Exp $
 ---------------------------------------------------------------------
              How to install Ncurses/Terminfo on your system
 ---------------------------------------------------------------------
@@ -149,6 +149,9 @@ INSTALLATION PROCEDURE:
     recent implementation of libiconv.  We have built this configuration on
     Linux using libiconv, sometimes requiring libutf8.
 
+    If you configure using the --with-pthread option, a "t" is appended to
+    the library names (e.g., libncursest.a, libncursestw.a).
+
     If you do not specify any models, the normal and debug libraries will be
     configured.  Typing `configure' with no arguments is equivalent to:
 
@@ -304,6 +307,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
@@ -385,6 +393,18 @@ SUMMARY OF CONFIGURE OPTIONS:
        Compile without scroll-hints code.  This option is ignored when
        hashmap scrolling is configured, which is the default.
 
+    --disable-tic-depends
+       When building shared libraries, normally the tic library is linked to
+       depend upon the ncurses library (and in turn, on the term-library if
+       the --with-termlib option was given).  The tic- and term-libraries
+       ABI does not depend on the --enable-widec option. Some packagers have
+       used this to reduce the number of library files which are packaged
+       by using only one copy of those libraries.  To make this work properly,
+       the tic library must be built without an explicit dependency on the
+       ncurses (or ncursesw) library.  Use this configure option to do that.
+       For example
+               configure --with-ticlib --with-shared --disable-tic-depends
+
     --disable-tparm-varargs
        Portable programs should call tparm() using the fixed-length parameter
        list documented in X/Open.  ncurses provides varargs support for this
@@ -493,15 +513,27 @@ 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-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
+       directory.
+
     --enable-reentrant
        Compile experimental configuration which improves reentrant use of the
-       library by reducing global and static variables.
+       library by reducing global and static variables.  This option is also
+       set if --with-pthread is used.
 
     --enable-rpath
        Use rpath option when generating shared libraries, and (with some
@@ -557,6 +589,13 @@ SUMMARY OF CONFIGURE OPTIONS:
     --enable-warnings
        Turn on GCC compiler warnings.  There should be only a few.
 
+    --enable-weak-symbols
+       If the --with-pthread option is set, check if the compiler supports
+       weak-symbols.  If it does, then name the thread-capable library without
+       the "t" (libncurses rather than libncursest), and provide for
+       dynamically loading the pthreads entrypoints at runtime.  This allows
+       one to reduce the number of library files for ncurses.
+
     --enable-wgetch-events
        Compile with experimental wgetch-events code.  See ncurses/README.IZ
 
@@ -583,6 +622,9 @@ SUMMARY OF CONFIGURE OPTIONS:
        Normally this is the same as the release version; some ports have
        special requirements for compatibility.
 
+       This option does not affect linking with libtool, which uses the
+       release major/minor numbers.
+
     --with-ada-compiler=CMD
        Specify the Ada95 compiler command (default "gnatmake")
 
@@ -610,20 +652,32 @@ SUMMARY OF CONFIGURE OPTIONS:
        to do this if the target compiler has unusual flags which confuse the
        host compiler.
 
+       You can also set the environment variable $BUILD_CFLAGS rather than
+       use this option.
+
     --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
        the host compiler.
 
+       You can also set the environment variable $BUILD_CPPFLAGS rather than
+       use this option.
+
     --with-build-ldflags=XXX
        If cross-compiling, specify the host linker-flags.  You might need to
        do this if the target linker has unusual flags which confuse the host
        compiler.
 
+       You can also set the environment variable $BUILD_LDFLAGS rather than
+       use this option.
+
     --with-build-libs=XXX
        If cross-compiling, the host libraries.  You might need to do this if
        the target environment requires unusual libraries.
 
+       You can also set the environment variable $BUILD_LIBS rather than
+       use this option.
+
     --with-caps=XXX
        Specify an alternate terminfo capabilities file, which makes the
        configure script look for "include/Caps.XXX".  A few systems, e.g.,
@@ -633,6 +687,10 @@ SUMMARY OF CONFIGURE OPTIONS:
        to use a terminfo database which is compatible with the native
        applications.
 
+    --with-ccharw-max=XXX
+       Override the size of the wide-character array in cchar_t structures.
+       Changing this will alter the binary interface.  This defaults to 5.
+
     --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
@@ -683,10 +741,16 @@ SUMMARY OF CONFIGURE OPTIONS:
 
        See also --without-dlsym
 
-    --with-hashed-db
+    --with-hashed-db[=XXX]
        Use a hashed database for storing terminfo data rather than storing
        each compiled entry in a separate binary file within a directory
        tree.
+       
+       In particular, this uses the Berkeley database 1.8.5 interface, as
+       provided by that and its successors db 2, 3, and 4.  The actual
+       interface is slightly different in the successor versions of the
+       Berkeley database.  The database should have been configured using
+       "--enable-compat185".
 
        If you use this option for configuring ncurses, tic will only be able
        to write entries in the hashed database.  infocmp can still read
@@ -698,6 +762,12 @@ SUMMARY OF CONFIGURE OPTIONS:
        You cannot have a directory containing both hashed-database and
        filesystem-based terminfo entries.
 
+       Use the parameter value to give the install-prefix used for the
+       datbase, e.g.,
+               --with-hashed-db=/usr/local/BigBase
+       to find the corresponding include- and lib-directories under the
+       given directory.
+
        See also the --enable-getcap option.
 
     --with-install-prefix=XXX
@@ -768,6 +838,14 @@ SUMMARY OF CONFIGURE OPTIONS:
        may be unsigned.  Use this option if you need to preserve compatibility
        with 64-bit executables.
 
+    --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-ospeed=TYPE
        Override type of ospeed variable, which is part of the termcap
        compatibility interface.  In termcap, this is a 'short', which works
@@ -781,18 +859,18 @@ SUMMARY OF CONFIGURE OPTIONS:
        those using termcap, do not use the higher speeds.  Your application
        (or system, in general) may or may not.
 
-    --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-pkg-config=[DIR]
+       Check for pkg-config, optionally specifying its path.
 
     --with-profile
        Generate profile-libraries These are named by adding "_p" to the root,
        e.g., libncurses_p.a
 
+    --with-pthread
+       Link with POSIX threads, set --enable-reentrant.  The use_window() and
+       use_screen() functions will use mutex's, allowing rudimentary support
+       for multithreaded applications.
+
     --with-rcs-ids
        Compile-in RCS identifiers.  Most of the C files have an identifier.
 
@@ -866,6 +944,12 @@ SUMMARY OF CONFIGURE OPTIONS:
        library.  As in termlib, there is no ABI difference between the
        "wide" libticw.so and libtic.so
 
+       NOTE: Overriding the name of the tic library may be useful if you are
+       also using the --with-termlib option to rename libtinfo.  If you are
+       not doing that, renaming the tic library can result in conflicting
+       library dependencies for tic and other programs built with the tic
+       library.
+
     --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.
@@ -874,6 +958,17 @@ SUMMARY OF CONFIGURE OPTIONS:
        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
+       "wrapping" function which fetches the data from the current SCREEN
+       structure.  Normally that function is named by prepending "_nc_" to the
+       variable's name.  The function is technically private (since portable
+       applications would not refer directly to it).  But according to one
+       line of reasoning, it is not the same type of "private" as functions
+       which applications should not call even via a macro.  This configure
+       option lets you choose the prefix for these wrapped variables.
+
     --without-ada
        Suppress the configure script's check for Ada95, do not build the
        Ada95 binding and related demo.
@@ -903,6 +998,9 @@ SUMMARY OF CONFIGURE OPTIONS:
     --without-dlsym
        Do not use dlsym() to load GPM dynamically.
 
+    --without-manpages
+       Tell the configure script to suppress the install of ncurses' manpages.
+
     --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
@@ -929,6 +1027,94 @@ COMPATIBILITY WITH OLDER VERSIONS OF NCURSES:
     you may encounter when building a system with different versions of
     ncurses:
 
+    5.7 (November 2, 2008)
+       Interface changes:
+
+       + generate linkable stubs for some macros:
+               getattrs
+
+       + Add new library configuration for tic-library (the non-curses portion
+         of the ncurses library used for the tic program as well as some
+         others such as tack.  There is no API change, but makefiles would be
+         changed to use the tic-library built separately.
+         
+         tack, distributed separately from ncurses, uses some of the internal
+         _nc_XXX functions, which are declared in the tic.h header file.
+
+         The reason for providing this separate library is that none of the
+         functions in it are suitable for threaded applications.
+
+       + Add new library configuration (ncursest, ncurseswt) which provides
+         rudimentary support for POSIX threads.  This introduces opaque
+         access functions to the WINDOW structure and adds a parameter to
+         several internal functions.
+
+       + move most internal variables (except tic-library) into data blocks
+         _nc_globals and _nc_prescreen to simplify analysis.  Those were
+         globally accessible, but since they were not part of the documented
+         API, there is no ABI change.
+
+       + changed static tables of strings to be indices into long strings, to
+         improve startup performance.  This changes parameter lists for some
+         of the internal functions.
+
+       Added extensions:
+
+       + add NCURSES_OPAQUE definition in curses.h to control whether internal
+         details of the WINDOW structure are visible to an application.  This
+         is always defined when the threaded library is built, and is optional
+         otherwise.  New functions for this:  is_cleared, is_idcok, is_idlok,
+         is_immedok, is_keypad, is_leaveok, is_nodelay, is_notimeout,
+         is_scrollok, is_syncok, wgetparent and wgetscrreg.
+
+       + the threaded library (ncursest) also disallows direct updating of
+         global curses-level variables, providing functions (via macros) for
+         obtaining their value.  A few of those variables can be modified by
+         the application, using new functions:  set_escdelay, set_tabsize
+
+       + added functions use_window() and use_screen() which wrap a mutex
+         (if threading is configured) around a call to a user-supplied
+         function.
+
+       Added internal functions:
+               _nc_get_alias_table
+               _nc_get_screensize
+               _nc_keyname
+               _nc_screen_of
+               _nc_set_no_padding
+               _nc_tracechar
+               _nc_tracemouse
+               _nc_unctrl
+               _nc_ungetch
+
+               These are used for leak-testing, and are stubs for
+               ABI compatibility when ncurses is not configured for that
+               using the --disable-leaks configure script option:
+
+               _nc_free_and_exit
+               _nc_leaks_tinfo
+
+       Removed internal functions:
+               none
+
+       Modified internal functions:
+               _nc_fifo_dump
+               _nc_find_entry
+               _nc_handle_sigwinch
+               _nc_init_keytry
+               _nc_keypad
+               _nc_locale_breaks_acs
+               _nc_timed_wait
+               _nc_update_screensize
+
+               Use new typedef TRIES to replace "struct tries":
+
+               _nc_add_to_try
+               _nc_expand_try
+               _nc_remove_key
+               _nc_remove_string
+               _nc_trace_tries
+
     5.6 (December 17, 2006)
        Interface changes:
 
@@ -1424,7 +1610,8 @@ CONFIGURING FALLBACK ENTRIES:
        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.  This must be done on a machine which
-       has ncurses' infocmp and terminfo database installed.
+       has ncurses' infocmp and terminfo database installed (as well as
+       ncurses' tic and infocmp programs).
 
        These entries are checked by setupterm() only when the conventional
        fetches from the terminfo tree and the termcap fallback (if configured)
@@ -1575,6 +1762,10 @@ BUILDING NCURSES WITH A CROSS-COMPILER
        option), ncurses uses the development platform's tic to do the
        "make install.data" portion.
 
+       The system's tic program is used to install the terminal database,
+       even for cross-compiles.  For best results, the tic program should
+       be from the most current version of ncurses.
+
 BUGS:
        Send any feedback to the ncurses mailing list at
        bug-ncurses@gnu.org. To subscribe send mail to