ncurses 5.9 - patch 20140927
[ncurses.git] / INSTALL
diff --git a/INSTALL b/INSTALL
index 71baeb08fddb992576d7f0b0c3670687b3be7a8f..a4f4cf5f0be990c4cb11bbea305cbba6841768d4 100644 (file)
--- a/INSTALL
+++ b/INSTALL
@@ -25,7 +25,7 @@
 -- sale, use or other dealings in this Software without prior written        --
 -- authorization.                                                            --
 -------------------------------------------------------------------------------
--- $Id: INSTALL,v 1.171 2014/04/26 20:30:01 tom Exp $
+-- $Id: INSTALL,v 1.174 2014/09/20 00:51:37 tom Exp $
 ---------------------------------------------------------------------
              How to install Ncurses/Terminfo on your system
 ---------------------------------------------------------------------
@@ -390,6 +390,37 @@ SUMMARY OF CONFIGURE OPTIONS:
        rather than the include directory.  This makes it simpler to avoid
        compile-time conflicts with other versions of curses.h
 
+       Putting the header files into a subdirectory assumes that applications
+       will follow the (standard) practice of including the headers with
+       reference to the subdirectory name.  For instance, the normal ncurses
+       header would be included using
+
+               #include <ncurses/curses.h>
+               #include <ncurses/term.h>
+
+       while the ncursesw headers would be found this way:
+
+               #include <ncursesw/curses.h>
+               #include <ncursesw/term.h>
+
+       In either case (with or without the --disable-overwrite option),
+       almost all applications are designed to include a related set of
+       curses header files from the same directory.
+
+       Manipulating the --includedir configure option to put header files
+       directly in a subdirectory of the normal include-directory defeats
+       this, and breaks builds of portable applications.  Likewise, putting
+       some headers in /usr/include, and others in a subdirectory is a good
+       way to break builds.
+
+       When configured with --disable-overwrite, the installed header files'
+       embedded #include's are adjusted to use the same style of includes
+       noted above.  In particular, the unctrl.h header is included from
+       curses.h, which means that a makefile which tells the compiler to
+       include directly from the subdirectory will fail to compile correctly.
+       Without some special effort, it will either fail to compile at all,
+       or the compiler may find a different unctrl.h file.
+
     --disable-relink
        If --enable-rpath is given, the generated makefiles normally will
        rebuild the libraries during install.  Use this option to simply
@@ -841,7 +872,7 @@ SUMMARY OF CONFIGURE OPTIONS:
                --with-hashed-db=/usr/local/BigBase
        to find the corresponding include- and lib-directories under the
        given directory.  Alternatively, you can specify a directory leaf
-       name, e.g., 
+       name, e.g.,
                --with-hashed-db=db4
        to make the configure script look for files in a subdirectory such as
                /usr/include/db4/db.h
@@ -987,11 +1018,23 @@ SUMMARY OF CONFIGURE OPTIONS:
        shared libraries, you may encounter problems with the linker.
        For example, it may prevent you from running  the build tree's
        copy of tic (for installing the terminfo database) because it
-       loads the system's copy of the ncurses shared libraries.  In that
-       case, using the misc/shlib script may be helpful, since it sets
-       $LD_LIBRARY_PATH to point to the build tree, e.g.,
+       loads the system's copy of the ncurses shared libraries.
+
+       In that case, using the misc/shlib script may be helpful, since it
+       sets $LD_LIBRARY_PATH to point to the build tree, e.g.,
+
                ./misc/shlib make install
 
+       Alternatively, for most platforms, the linker accepts a list of
+       directories which will be searched for libraries at run-time.  The
+       configure script allows you to modify this list using the
+       RPATH_LIST environment variable.  It is a colon-separated list of
+       directories (default:  the "libdir" set via the configure script).
+       If you set that to put "../lib" first in the list, the linker will
+       look first at the build-directory, and avoid conflict with libraries
+       already installed.  One drawback to this approach is that libraries
+       can be accidentally searched in any "../lib" directory.
+
        NOTE: If you use the --with-ada-sharedlib option, you should also
        set this option, to ensure that C-language modules needed for the
        Ada binding use appropriate compiler options.