ncurses 5.6 - patch 20080913

[ncurses.git] / INSTALL

diff --git a/INSTALL b/INSTALL
index e3dc161a9cb7b5c56da76f7624bbf82921ee3f28..e338dc73d1853a487808aaa37778e7877c91734b 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -1,5 +1,5 @@
 -------------------------------------------------------------------------------
 -------------------------------------------------------------------------------

--- Copyright (c) 1998-2005,2006 Free Software Foundation, Inc.               --
+-- Copyright (c) 1998-2006,2008 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             --
 --                                                                           --
 -- 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.                                                            --
 -------------------------------------------------------------------------------
 -- sale, use or other dealings in this Software without prior written        --
 -- authorization.                                                            --
 -------------------------------------------------------------------------------

--- $Id: INSTALL,v 1.115 2007/01/13 17:16:34 tom Exp $
+-- $Id: INSTALL,v 1.129 2008/08/23 20:02:46 tom Exp $

 ---------------------------------------------------------------------
              How to install Ncurses/Terminfo on your system
 ---------------------------------------------------------------------
 ---------------------------------------------------------------------
              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.
 
     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:
 
     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.
 
        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


@@ -334,6 +342,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


@@ -358,6 +376,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


@@ -476,12 +501,23 @@ SUMMARY OF CONFIGURE OPTIONS:
        may not be accurate, or that your stty settings have disabled the use
        of tabs.
 
        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-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.  This option is also
+       set if --with-pthread is used.
+

     --enable-rpath
        Use rpath option when generating shared libraries, and (with some
        restrictions) when linking the corresponding programs.  This originally
     --enable-rpath
        Use rpath option when generating shared libraries, and (with some
        restrictions) when linking the corresponding programs.  This originally


@@ -495,6 +531,9 @@ SUMMARY OF CONFIGURE OPTIONS:
        environment variable, they do not work with setuid applications since
        the LD_LIBRARY_PATH variable would be unset in that situation.
 
        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
        this if you are building ncurses for a system that has neither
     --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


@@ -533,6 +572,13 @@ 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-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
 
     --enable-wgetch-events
        Compile with experimental wgetch-events code.  See ncurses/README.IZ
 


@@ -586,20 +632,32 @@ SUMMARY OF CONFIGURE OPTIONS:
        to do this if the target compiler has unusual flags which confuse the
        host compiler.
 
        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.
 
     --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.
 
     --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.
 
     --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.,
     --with-caps=XXX
        Specify an alternate terminfo capabilities file, which makes the
        configure script look for "include/Caps.XXX".  A few systems, e.g.,


@@ -659,10 +717,16 @@ SUMMARY OF CONFIGURE OPTIONS:
 
        See also --without-dlsym
 
 
        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.
        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
 
        If you use this option for configuring ncurses, tic will only be able
        to write entries in the hashed database.  infocmp can still read


@@ -674,6 +738,12 @@ SUMMARY OF CONFIGURE OPTIONS:
        You cannot have a directory containing both hashed-database and
        filesystem-based terminfo entries.
 
        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
        See also the --enable-getcap option.
 
     --with-install-prefix=XXX


@@ -744,6 +814,14 @@ SUMMARY OF CONFIGURE OPTIONS:
        may be unsigned.  Use this option if you need to preserve compatibility
        with 64-bit executables.
 
        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
     --with-ospeed=TYPE
        Override type of ospeed variable, which is part of the termcap
        compatibility interface.  In termcap, this is a 'short', which works


@@ -757,18 +835,15 @@ SUMMARY OF CONFIGURE OPTIONS:
        those using termcap, do not use the higher speeds.  Your application
        (or system, in general) may or may not.
 
        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-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
 

+    --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.
 
     --with-rcs-ids
        Compile-in RCS identifiers.  Most of the C files have an identifier.
 


@@ -842,6 +917,12 @@ SUMMARY OF CONFIGURE OPTIONS:
        library.  As in termlib, there is no ABI difference between the
        "wide" libticw.so and libtic.so
 
        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.
     --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.