ncurses 6.2 - patch 20200314
[ncurses.git] / INSTALL
1 -------------------------------------------------------------------------------
2 -- Copyright 2018-2019,2020 Thomas E. Dickey                                 --
3 -- Copyright 1998-2017,2018 Free Software Foundation, Inc.                   --
4 --                                                                           --
5 -- Permission is hereby granted, free of charge, to any person obtaining a   --
6 -- copy of this software and associated documentation files (the             --
7 -- "Software"), to deal in the Software without restriction, including       --
8 -- without limitation the rights to use, copy, modify, merge, publish,       --
9 -- distribute, distribute with modifications, sublicense, and/or sell copies --
10 -- of the Software, and to permit persons to whom the Software is furnished  --
11 -- to do so, subject to the following conditions:                            --
12 --                                                                           --
13 -- The above copyright notice and this permission notice shall be included   --
14 -- in all copies or substantial portions of the Software.                    --
15 --                                                                           --
16 -- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS   --
17 -- OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF                --
18 -- MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN --
19 -- NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,       --
20 -- DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR     --
21 -- OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE --
22 -- USE OR OTHER DEALINGS IN THE SOFTWARE.                                    --
23 --                                                                           --
24 -- Except as contained in this notice, the name(s) of the above copyright    --
25 -- holders shall not be used in advertising or otherwise to promote the      --
26 -- sale, use or other dealings in this Software without prior written        --
27 -- authorization.                                                            --
28 -------------------------------------------------------------------------------
29 -- $Id: INSTALL,v 1.221 2020/03/08 14:27:08 tom Exp $
30 ---------------------------------------------------------------------
31              How to install Ncurses/Terminfo on your system
32 ---------------------------------------------------------------------
33
34     ************************************************************
35     * READ ALL OF THIS FILE BEFORE YOU TRY TO INSTALL NCURSES. *
36     ************************************************************
37
38 You should be reading the file INSTALL in a directory called ncurses-d.d, where
39 d.d is the current version number.  There should be several subdirectories,
40 including `c++', `form', `man', `menu', 'misc', `ncurses', `panel', `progs',
41 and `test'.  See the README file for a roadmap to the package.
42
43 If you are a distribution integrator or packager, please read and act on the
44 section titled IF YOU ARE A SYSTEM INTEGRATOR below.
45
46 If you are converting from BSD curses and do not have root access, be sure
47 to read the BSD CONVERSION NOTES section below.
48
49 If you are trying to build applications using gpm with ncurses,
50 read the USING NCURSES WITH GPM section below.
51
52 If you are running over the Andrew File System see the note below on
53 USING NCURSES WITH AFS.
54
55 If you are cross-compiling, see the note below on BUILDING NCURSES WITH A
56 CROSS-COMPILER.
57
58 If you want to build the Ada95 binding, go to the Ada95 directory and
59 follow the instructions there.  The Ada95 binding is not covered below.
60
61
62 REQUIREMENTS:
63 ------------
64
65 You will need the following to build and install ncurses under UNIX:
66
67         * ANSI C compiler  (gcc, for instance)
68         * sh               (bash will do)
69         * awk              (mawk or gawk will do)
70         * sed
71         * BSD or System V style install (a script is enclosed)
72
73 Ncurses has been also built in the OS/2 EMX environment.
74
75
76 INSTALLATION PROCEDURE:
77 ----------------------
78
79 1.  First, decide whether you want ncurses to replace your existing library (in
80     which case you'll need super-user privileges) or be installed in parallel
81     with it.
82
83     The --prefix option to configure changes the root directory for installing
84     ncurses.  The default is normally in subdirectories of /usr/local, except
85     for systems where ncurses is normally installed as a system library (see
86     "IF YOU ARE A SYSTEM INTEGRATOR").  Use --prefix=/usr to replace your
87     default curses distribution.
88
89     The package gets installed beneath the --prefix directory as follows:
90
91     In $(prefix)/bin:          tic, infocmp, captoinfo, tset,
92                                 reset, clear, tput, toe, tabs
93     In $(prefix)/lib:          libncurses*.* libcurses.a
94     In $(prefix)/share/terminfo: compiled terminal descriptions
95     In $(prefix)/include:      C header files
96     Under $(prefix)/man:       the manual pages
97
98     Note that the configure script attempts to locate previous installation of
99     ncurses, and will set the default prefix according to where it finds the
100     ncurses headers.
101
102     Do not use commands such as
103
104         make install prefix=XXX
105
106     to change the prefix after configuration, since the prefix value is used
107     for some absolute pathnames such as TERMINFO.  Instead do this
108
109         make install DESTDIR=XXX
110
111     See also the discussion of --with-install-prefix.
112
113 2.  Type `./configure' in the top-level directory of the distribution to
114     configure ncurses for your operating system and create the Makefiles.
115     Besides --prefix, various configuration options are available to customize
116     the installation; use `./configure --help' to list the available options.
117
118     If your operating system is not supported, read the PORTABILITY section in
119     the file ncurses/README for information on how to create a configuration
120     file for your system.
121
122     The `configure' script generates makefile rules for one or more object
123     models and their associated libraries:
124
125         libncurses.a (normal)
126
127         libcurses.a (normal, a link to libncurses.a)
128                 This gets left out if you configure with --disable-overwrite.
129
130         libncurses.so (shared)
131
132         libncurses_g.a (debug)
133
134         libncurses_p.a (profile)
135
136         libncurses.la (libtool)
137
138     If you configure using the --enable-widec option, a "w" is appended to the
139     library names (e.g., libncursesw.a), and the resulting libraries support
140     wide-characters, e.g., via a UTF-8 locale.  The corresponding header files
141     are compatible with the non-wide-character configuration; wide-character
142     features are provided by ifdef's in the header files.  The wide-character
143     library interfaces are not binary-compatible with the non-wide-character
144     version.  Building and running the wide-character code relies on a fairly
145     recent implementation of libiconv.  We have built this configuration on
146     various systems using libiconv, sometimes requiring libutf8.
147
148     If you configure using the --with-pthread option, a "t" is appended to
149     the library names (e.g., libncursest.a, libncursestw.a).
150
151     If you do not specify any models, the normal and debug libraries will be
152     configured.  Typing `configure' with no arguments is equivalent to:
153
154         ./configure --with-normal --with-debug --enable-overwrite
155
156     Typing
157
158         ./configure --with-shared
159
160     makes the shared libraries the default, resulting in
161
162         ./configure --with-shared --with-normal --with-debug --enable-overwrite
163
164     If you want only shared libraries, type
165
166         ./configure --with-shared --without-normal --without-debug
167
168     Rules for generating shared libraries are highly dependent upon the choice
169     of host system and compiler.  We've been testing shared libraries on
170     several systems, but more work needs to be done to make shared libraries
171     work on other systems.
172
173     If you have libtool installed, you can type
174
175         ./configure --with-libtool
176
177     to generate the appropriate static and/or shared libraries for your
178     platform using libtool.
179
180     You can make curses and terminfo fall back to an existing file of termcap
181     definitions by configuring with --enable-termcap.  If you do this, the
182     library will search /etc/termcap before the terminfo database, and will
183     also interpret the contents of the TERM environment variable.  See the
184     section BSD CONVERSION NOTES below.
185
186 3.  Type `make'.  Ignore any warnings, no error messages should be produced.
187     This should compile the ncurses library, the terminfo compiler tic(1),
188     captoinfo(1), infocmp(1), toe(1), clear(1) tset(1), reset(1), and tput(1)
189     programs (see the manual pages for explanation of what they do), some test
190     programs, and the panels, menus, and forms libraries.
191
192 4.  Run ncurses and several other test programs in the test directory to
193     verify that ncurses functions correctly before doing an install that
194     may overwrite system files.  Read the file test/README for details on
195     the test programs.
196
197     NOTE: You must have installed the terminfo database, or set the
198     environment variable $TERMINFO to point to a SVr4-compatible terminfo
199     database before running the test programs.  Not all vendors' terminfo
200     databases are SVr4-compatible, but most seem to be.
201
202     It is possible to configure ncurses to use other terminfo database formats.
203     A few are provided as examples in the include-directory (see --with-caps).
204
205     If you run the test programs WITHOUT installing terminfo, ncurses may
206     read the termcap file and cache that in $HOME/.terminfo, which will
207     thereafter be used instead of the terminfo database.  See the comments
208     on "--enable-getcap-cache", to see why this is a Bad Thing.
209
210     The ncurses program is designed specifically to test the ncurses library.
211     You can use it to verify that the screen highlights work correctly, that
212     cursor addressing and window scrolling works OK, etc.
213
214 5.  Once you've tested, you can type `make install' to install libraries,
215     the programs, the terminfo database and the manual pages.  Alternately, you
216     can type `make install' in each directory you want to install.  In the
217     top-level directory, you can do a partial install using these commands:
218
219         'make install.progs'    installs tic, infocmp, etc...
220         'make install.includes' installs the headers.
221         'make install.libs'     installs the libraries (and the headers).
222         'make install.data'     installs the terminfo data. (Note: `tic' must
223                                 be installed before the terminfo data can be
224                                 compiled).
225         'make install.man'      installs the manual pages.
226
227   ############################################################################
228   #     CAVEAT EMPTOR: `install.data' run as root will NUKE any existing     #
229   #  terminfo database. If you have any custom or unusual entries SAVE them  #
230   #  before you install ncurses.                                             #
231   ############################################################################
232
233     The terminfo(5) manual page must be preprocessed with tbl(1) before
234     being formatted by nroff(1).  Modern man(1) implementations tend to do
235     this by default, but you may want to look at your version's manual page
236     to be sure.  You may also install the manual pages after preprocessing
237     with tbl(1) by specifying the configure option --with-manpage-tbl.
238
239     If the system already has a curses library that you need to keep using
240     you'll need to distinguish between it and ncurses.  See the discussion of
241     --disable-overwrite.  If ncurses is installed outside the standard
242     directories (/usr/include and /usr/lib) then all your users will need to
243     use the -I option to compile programs and -L to link them.
244
245     If you have another curses installed in your system and you accidentally
246     compile using its curses.h you'll end up with a large number of
247     undefined symbols at link time.
248
249     IF YOU DO NOT HAVE ROOT: Change directory to the `progs' subdirectory
250     and run the `capconvert' script.  This script will deduce various things
251     about your environment and use them to build you a private terminfo tree,
252     so you can use ncurses applications.
253
254     If more than one user at your site does this, the space for the duplicate
255     trees is wasted.  Try to get your site administrators to install a system-
256     wide terminfo tree instead.
257
258     See the BSD CONVERSION NOTES section below for a few more details.
259
260 6.  The c++ directory has C++ classes that are built on top of ncurses and
261     panels.  You must have c++ (and its libraries) installed before you can
262     compile and run the demo.
263
264     Use --without-cxx-binding to tell configure to not build the C++ bindings
265     and demo.
266
267     If you do not have C++, you must use the --without-cxx option to tell
268     the configure script to not attempt to determine the type of 'bool'
269     which may be supported by C++.  IF YOU USE THIS OPTION, BE ADVISED THAT
270     YOU MAY NOT BE ABLE TO COMPILE (OR RUN) NCURSES APPLICATIONS WITH C++.
271
272
273 SUMMARY OF CONFIGURE OPTIONS:
274 ----------------------------
275
276     The configure script provides a short list of its options when you type
277
278         ./configure --help
279
280     The --help and several options are common to all configure scripts that are
281     generated with autoconf.  Those are all listed before the line
282
283         --enable and --with options recognized:
284
285     The other options are specific to this package.  We list them in alphabetic
286     order.
287
288     --disable-assumed-color
289         With ncurses 5.1, we introduced a new function, assume_default_colors()
290         which allows applications to specify what the default foreground and
291         background color are assumed to be.  Most color applications use
292         full-screen color; but a few do not color the background.  While the
293         assumed values can be overridden by invoking assume_default_colors(),
294         you may find it useful to set the assumed values to the pre-5.1
295         convention, using this configure option.
296
297     --disable-big-core
298         Assume machine has little memory.  The configure script attempts to
299         determine if your machine has enough memory (about 6Mb) to compile the
300         terminfo database without writing portions to disk.  Some allocators
301         return deceptive results, so you may have to override the configure
302         script.  Or you may be building tic for a smaller machine.
303
304     --disable-big-strings
305         Disable compile-time optimization of predefined tables which puts
306         all of their strings into a very long string, to reduce relocation
307         overhead.
308
309     --disable-database
310         Use only built-in data.  The ncurses libraries normally read terminfo
311         and termcap data from disk.  You can configure ncurses to have a
312         built-in database, aka "fallback" entries.  Embedded applications may
313         have no need for an external database.  Some, but not all of the
314         programs are useful in this configuration, e.g., tset and tput versus
315         infocmp and tic.
316
317     --disable-db-install
318         Do not install the terminal database.  This is used to omit features
319         for packages, as done with --without-progs.
320
321     --disable-echo
322         Use the option --disable-echo to make the build-log less verbose by
323         suppressing the display of the compile and link commands.  This makes
324         it easier to see the compiler warnings.  (You can always use "make -n"
325         to see the options that are used).
326
327     --disable-ext-funcs
328         Disable function-extensions.  Configure ncurses without the functions
329         that are not specified by XSI.  See ncurses/modules for the exact
330         list of library modules that would be suppressed.
331
332     --disable-gnat-projects
333         Disable GNAT projects even if usable, for testing old makefile rules.
334
335     --disable-hashmap
336         Compile without hashmap scrolling-optimization code.  This algorithm is
337         the default.
338
339     --disable-home-terminfo
340         The $HOME/.terminfo directory is normally added to ncurses' search
341         list for reading/writing terminfo entries, since that directory is
342         more likely writable than the system terminfo database.  Use this
343         option to disable the feature altogether.
344
345     --disable-largefile
346         Disable compiler flags needed to use large-file interfaces.
347
348     --disable-leaks
349         For testing, compile-in code that frees memory that normally would not
350         be freed, to simplify analysis of memory-leaks.
351
352         Any implementation of curses must not free the memory associated with
353         a screen, since (even after calling endwin()), it must be available
354         for use in the next call to refresh().  There are also chunks of
355         memory held for performance reasons.  That makes it hard to analyze
356         curses applications for memory leaks.  To work around this, build a
357         debugging version of the ncurses library which frees those chunks
358         which it can, and provides the _nc_free_and_exit() function to free
359         the remainder and then exit.  The ncurses utility and test programs
360         use this feature, e.g., via the ExitProgram() macro.
361
362         Because this lies outside of the library's intended usage, it is not
363         normally considered part of the ABI.  If there were some (as yet
364         unplanned) extension which frees memory in a manner that would let the
365         library resume and reallocate memory, then that would not use a "_nc_"
366         prefix.
367
368     --disable-lib-suffixes
369         Suppress the "w", "t" or "tw" suffixes which normally would be added
370         to the library names for the --enable-widec and --with-pthread options.
371
372     --disable-libtool-version
373         when using --with-libtool, control how the major/minor version numbers
374         are used for constructing the library name.
375
376         The default uses the -version-number feature of libtool, which makes
377         the library names compatible (though not identical) with the standard
378         build using --with-shared.
379
380         Use --disable-libtool-version to use the libtool -version-info feature.
381         This corresponds to the setting used before patch 20100515.
382
383         Starting with patch 20141115, using this option causes the configure
384         script to apply the top-level VERSION file to the ABI version used
385         for libtool.
386
387     --disable-lp64
388         The header files will ignore use of the _LP64 symbol to make chtype
389         and mmask_t types 32 bits (they may be long on 64-bit hosts, for
390         compatibility with older releases).
391
392         NOTE: this is potentially an ABI change, depending on existing
393         packages.  The default for this option is "disabled" for ncurses
394         ABI 5, and "enabled" for ABI 6.
395
396     --disable-macros
397         For testing, use functions rather than macros.  The program will run
398         more slowly, but it is simpler to debug.  This defines NCURSES_NOMACROS
399         at build time.  See also the --enable-expanded option.
400
401     --disable-overwrite
402         If you are installing ncurses on a system which contains another
403         development version of curses, or which could be confused by the loader
404         for another version, we recommend that you leave out the link to
405         -lcurses.  The ncurses library is always available as -lncurses.
406         Disabling overwrite also causes the ncurses header files to be
407         installed into a subdirectory, e.g., /usr/local/include/ncurses,
408         rather than the include directory.  This makes it simpler to avoid
409         compile-time conflicts with other versions of curses.h
410
411         Putting the header files into a subdirectory assumes that applications
412         will follow the (standard) practice of including the headers with
413         reference to the subdirectory name.  For instance, the normal ncurses
414         header would be included using
415
416                 #include <ncurses/curses.h>
417                 #include <ncurses/term.h>
418
419         while the ncursesw headers would be found this way:
420
421                 #include <ncursesw/curses.h>
422                 #include <ncursesw/term.h>
423
424         In either case (with or without the --disable-overwrite option),
425         almost all applications are designed to include a related set of
426         curses header files from the same directory.
427
428         Manipulating the --includedir configure option to put header files
429         directly in a subdirectory of the normal include-directory defeats
430         this, and breaks builds of portable applications.  Likewise, putting
431         some headers in /usr/include, and others in a subdirectory is a good
432         way to break builds.
433
434         When configured with --disable-overwrite, the installed header files'
435         embedded #include's are adjusted to use the same style of includes
436         noted above.  In particular, the unctrl.h header is included from
437         curses.h, which means that a makefile which tells the compiler to
438         include directly from the subdirectory will fail to compile correctly.
439         Without some special effort, it will either fail to compile at all,
440         or the compiler may find a different unctrl.h file.
441
442         In addition to the curses library, a system may provide its own
443         versions of the add-on libraries (form, menu, panel), which would
444         not be compatible with ncurses.  These options allow you to rename
445         ncurses' add-on libraries to avoid conflicts when linking:
446
447                 --with-form-libname=XXX
448                 --with-menu-libname=XXX
449                 --with-panel-libname=XXX
450
451         Rather than renaming them abitrarily, a prefix or suffix is
452         recommended.  An "n" prefix provides consistency with ncurses versus
453         curses, i.e.,
454
455                 --with-form-libname=nform
456                 --with-menu-libname=nmenu
457                 --with-panel-libname=npanel
458
459     --disable-relink
460         If --enable-rpath is given, the generated makefiles normally will
461         rebuild shared libraries during install.  Use this option to simply
462         copy whatever the linker produced.
463
464         Static libraries cannot simply be copied because tools use timestamps
465         to determine if the library's symbol table is up to date.  If your
466         install program supports the "-p" (preserve timestamp) option, that
467         is used when --disable-relink is given, to avoid rebuilding the symbol
468         table.
469
470         Finally, some tools ignore the subsecond timestamps supported by some
471         filesystems.  This option adds a 1-second sleep to help those tools
472         avoid unnecessary relinking during the install process.
473
474     --disable-root-environ
475         Compile with environment restriction, so certain environment variables
476         are not available when running as root, or via a setuid/setgid
477         application.  These are (for example $TERMINFO) those that allow the
478         search path for the terminfo or termcap entry to be customized.
479
480     --disable-rpath-hack
481         Normally the configure script helps link libraries found in unusual
482         places by adding an rpath option to the link command.  If you are
483         building packages, this feature may be redundant.  Use this option
484         to suppress the feature.
485
486     --disable-scroll-hints
487         Compile without scroll-hints code.  This option is ignored when
488         hashmap scrolling is configured, which is the default.
489
490     --disable-stripping
491         Do not strip installed executables.
492
493     --disable-tic-depends
494         When building shared libraries, normally the tic library is linked to
495         depend upon the ncurses library (or equivalently, on the tinfo-library
496         if the --with-termlib option was given).  The tic- and tinfo-library
497         ABIs do not depend on the --enable-widec option.  Some packagers have
498         used this to reduce the number of library files which are packaged by
499         using only one copy of those libraries.  To make this work properly,
500         the tic library must be built without an explicit dependency on the
501         underlying library (ncurses vs ncursesw, tinfo vs tinfow).  Use this
502         configure option to do that.
503         For example
504                 configure --with-ticlib --with-shared --disable-tic-depends
505
506     --disable-tparm-varargs
507         Portable programs should call tparm() using the fixed-length parameter
508         list documented in X/Open.  ncurses provides varargs support for this
509         function.  Use --disable-tparm-varargs to disable this support.
510
511     --disable-wattr-macros
512         The 6.0 ABI adds support for extended colors and for extended mouse.
513         The former is a noticeable problem when developers inadvertently
514         compile using the ncurses6 header files and link with an ncurses5
515         library, because the wattr* macros use a new field in the WINDOW
516         structure.  These macros are used in several applications.
517
518         Since ncurses provides an actual function for each of these macros,
519         suppressing them from the curses.h header allows the ncurses5 libraries
520         to be used in most applications.
521
522         NOTE: The extended colors also are used in the cchar_t structure, but
523         fewer applications use that.
524
525         NOTE: This workaround does not help with mismatches in the ncurses
526         mouse version.  The extended mouse feature uses one less fewer bit for
527         each button, so that only the first button will work as expected with
528         a mismatch between header and library.  Again, most applications will
529         work, since most use only the first button.
530
531     --enable-assertions
532         For testing, compile-in assertion code.  This is used only for a few
533         places where ncurses cannot easily recover by returning an error code.
534
535     --enable-broken_linker
536         A few platforms have what we consider a broken linker:  it cannot link
537         objects from an archive solely by referring to data objects in those
538         files, but requires a function reference.  This configure option
539         changes several data references to functions to work around this
540         problem.
541
542         NOTE: With ncurses 5.1, this may not be necessary, since we are
543         told that some linkers interpret uninitialized global data as a
544         different type of reference which behaves as described above.  We have
545         explicitly initialized all of the global data to work around the
546         problem.
547
548     --enable-bsdpad
549         Recognize BSD-style prefix padding.  Some ancient BSD programs (such as
550         nethack) call tputs("50") to implement delays.
551
552     --enable-colorfgbg
553         Compile with experimental $COLORFGBG code.  That environment variable
554         is set by some terminal emulators as a hint to applications, by
555         advertising the default foreground and background colors.  During
556         initialization, ncurses sets color pair 0 to match this.
557
558     --enable-const
559         The curses interface as documented in XSI is rather old, in fact
560         including features that precede ANSI C.  The prototypes generally do
561         not make effective use of "const".  When using stricter compilers (or
562         gcc with appropriate warnings), you may see warnings about the mismatch
563         between const and non-const data.  We provide a configure option which
564         changes the interfaces to use const - quieting these warnings and
565         reflecting the actual use of the parameters more closely.  The ncurses
566         library uses the symbol NCURSES_CONST for these instances of const,
567         and if you have asked for compiler warnings, will add gcc's const-qual
568         warning.  There will still be warnings due to subtle inconsistencies
569         in the interface, but at a lower level.
570
571         NOTE: configuring ncurses with this option may detract from the
572         portability of your applications by encouraging you to use const in
573         places where the XSI curses interface would not allow them.  Similar
574         issues arise when porting to SVr4 curses, which uses const in even
575         fewer places.
576
577     --enable-expanded
578         For testing, generate functions for certain macros to make them visible
579         as such to the debugger.  See also the --disable-macros option.
580
581     --enable-ext-colors
582         Extend the cchar_t structure to allow more than 16 colors to be
583         encoded.  This applies only to the wide-character (--enable-widec)
584         configuration.
585
586         NOTE: using this option will make libraries which are not binary-
587         compatible with libncursesw 5.4.  None of the interfaces change, but
588         applications which have an array of cchar_t's must be recompiled.
589
590     --enable-ext-mouse
591         Modify the encoding of mouse state to make room for a 5th mouse button.
592         That allows one to use ncurses with a wheel mouse with xterm or
593         similar X terminal emulators.
594
595         NOTE: using this option will make libraries which are not binary-
596         compatible with libncursesw 5.4.  None of the interfaces change, but
597         applications which have mouse mask mmask_t's must be recompiled.
598
599     --enable-ext-putwin
600         Modify the file-format written by putwin() to use printable text rather
601         than binary files, allowing getwin() to read screen dumps written by
602         differently-configured ncurses libraries.  The extended getwin() can
603         still read binary screen dumps from the "same" configuration of
604         ncurses.  This does not change the ABI (the binary interface seen by
605         calling applications).
606
607     --enable-getcap
608         Use the 4.4BSD getcap code if available, or a bundled version of it to
609         fetch termcap entries.  Entries read in this way cannot use (make
610         cross-references to) the terminfo tree, but it is faster than reading
611         /etc/termcap.
612
613         If configured for one of the *BSD systems, this automatically uses
614         the hashed database system produced using cap_mkdb or similar tools.
615         In that case, there is no advantage in using the --enable-getcap-cache
616         option.
617
618         See also the --with-hashed-db option.
619
620     --enable-getcap-cache
621         Cache translated termcaps under the directory $HOME/.terminfo
622
623         NOTE: this sounds good - it makes ncurses run faster the second time.
624         But look where the data comes from - an /etc/termcap containing lots of
625         entries that are not up to date.  If you configure with this option and
626         forget to install the terminfo database before running an ncurses
627         application, you will end up with a hidden terminfo database that
628         generally does not support color and will miss some function keys.
629
630     --enable-hard-tabs
631         Compile-in cursor-optimization code that uses hard-tabs.  We would make
632         this a standard feature except for the concern that the terminfo entry
633         may not be accurate, or that your stty settings have disabled the use
634         of tabs.
635
636     --enable-interop
637         Compile-in experimental interop bindings.  These provide generic types
638         for the form-library.
639
640     --enable-mixed-case
641         Controls whether the filesystem on which the terminfo database resides
642         supports mixed-case filenames (normal for UNIX, but not on other
643         systems).  If you do not specify this option, the configure script
644         checks the current filesystem.
645
646     --enable-no-padding
647         Compile-in support for the $NCURSES_NO_PADDING environment variable,
648         which allows you to suppress the effect of non-mandatory padding in
649         terminfo entries.  This is the default, unless you have disabled the
650         extended functions.
651
652     --enable-opaque-curses
653     --enable-opaque-form
654     --enable-opaque-menu
655     --enable-opaque-panel
656         Define symbol in curses.h which controls whether some library
657         structures are treated as "opaque".  The --enable-opaque-curses option
658         is overridden by the --enable-reentrant option.
659
660     --enable-pc-files
661         If pkg-config is found (see --with-pkg-config), generate ".pc" files
662         for each of the libraries, and install them in pkg-config's library
663         directory.
664
665     --enable-pthreads-eintr
666         add logic in threaded configuration to ensure that a read(2) system
667         call can be interrupted for SIGWINCH.
668
669     --enable-reentrant
670         Compile configuration which improves reentrant use of the library by
671         reducing global and static variables.  This option is also set if
672         --with-pthread is used.
673
674         Enabling this option adds a "t" to the library names, except for the
675         special case when --enable-weak-symbols is also used.
676
677     --enable-rpath
678         Use rpath option when generating shared libraries, and (with some
679         restrictions) when linking the corresponding programs.  This originally
680         (in 1997) applied mainly to systems using the GNU linker (read the
681         manpage).
682
683         More recently it is useful for systems that require special treatment
684         shared libraries in "unusual" locations.  The "system" libraries reside
685         in directories which are on the loader's default search-path.  While
686         you may be able to use workarounds such as the $LD_LIBRARY_PATH
687         environment variable, they do not work with setuid applications since
688         the LD_LIBRARY_PATH variable would be unset in that situation.
689
690         This option does not apply to --with-libtool, since libtool makes
691         extra assumptions about rpath.
692
693     --enable-safe-sprintf
694         Compile with experimental safe-sprintf code.  You may consider using
695         this if you are building ncurses for a system that has neither
696         vsnprintf() or vsprintf().  It is slow, however, and is used only on
697         very old systems which lack vsnprintf().
698
699     --enable-signed-char
700         The term.h header declares a Booleans[] array typed "char".  But it
701         stores signed values there and "char" is not necessarily signed.
702         Some packagers choose to alter the type of Booleans[] though this
703         is not strictly compatible.  This option allows one to implement this
704         alteration without patching the source code.
705
706     --enable-sigwinch
707         Compile support for ncurses' SIGWINCH handler.  If your application has
708         its own SIGWINCH handler, ncurses will not use its own.  The ncurses
709         handler causes wgetch() to return KEY_RESIZE when the screen-size
710         changes.  This option is the default, unless you have disabled the
711         extended functions.
712
713     --enable-sp-funcs
714         Compile-in support for extended functions which accept a SCREEN pointer,
715         reducing the need for juggling the global SP value with set_term() and
716         delscreen().
717
718     --enable-string-hacks
719         Controls whether strlcat and strlcpy may be used.  The same issue
720         applies to OpenBSD's warnings about snprintf, noting that this function
721         is weakly standardized.
722
723         Aside from stifling these warnings, there is no functional improvement
724         in ncurses.
725
726     --enable-symlinks
727         If your system supports symbolic links, make tic use symbolic links
728         rather than hard links to save diskspace when writing aliases in the
729         terminfo database.
730
731     --enable-tcap-names
732         Compile-in support for user-definable terminal capabilities.  Use the
733         -x option of tic and infocmp to treat unrecognized terminal
734         capabilities as user-defined strings.  This option is the default,
735         unless you have disabled the extended functions.
736
737     --enable-term-driver
738         Enable experimental terminal-driver.  This is currently used for the
739         MinGW port, by providing a way to substitute the low-level terminfo
740         library with different terminal drivers.
741
742     --enable-termcap
743         Compile in support for reading terminal descriptions from termcap if no
744         match is found in the terminfo database.  See also the --enable-getcap
745         and --enable-getcap-cache options.
746
747         Termcap support requires run-time parsing rather than loading
748         predigested data.  If you have specified --with-ticlib, then you
749         cannot have termcap support since run-time parsing is done in the
750         tic library, which is intentionally not part of normal linkage
751         dependencies.
752
753     --enable-warnings
754         Turn on GCC compiler warnings.  There should be only a few.
755
756     --enable-weak-symbols
757         If the --with-pthread option is set, check if the compiler supports
758         weak-symbols.  If it does, then name the thread-capable library without
759         the "t" (libncurses rather than libncursest), and provide for
760         dynamically loading the pthreads entrypoints at runtime.  This allows
761         one to reduce the number of library files for ncurses.
762
763     --enable-wgetch-events
764         Compile with experimental wgetch-events code.  See ncurses/README.IZ
765
766     --enable-widec
767         Compile with wide-character code.  This makes a different version of
768         the libraries (e.g., libncursesw.so), which stores characters as
769         wide-characters,
770
771         NOTE: applications compiled with this configuration are not compatible
772         with those built for 8-bit characters.  You cannot simply make a
773         symbolic link to equate libncurses.so with libncursesw.so
774
775         NOTE: the Ada95 binding may be built against either version of the the
776         ncurses library, but you must decide which:  the binding installs the
777         same set of files for either version.  Currently (2002/6/22) it does
778         not use the extended features from the wide-character code, so it is
779         probably better to not install the binding for that configuration.
780
781     --enable-xmc-glitch
782         Compile-in support experimental xmc (magic cookie) code.
783
784     --with-abi-version=NUM
785         Override the ABI version, which is used in shared library filenames.
786         Normally this is the same as the release version; some ports have
787         special requirements for compatibility.
788
789         This option does not affect linking with libtool, which uses the
790         release major/minor numbers.
791
792     --with-ada-compiler=CMD
793         Specify the Ada95 compiler command (default "gnatmake")
794
795     --with-ada-include=DIR
796         Tell where to install the Ada includes (default:
797         PREFIX/lib/ada/adainclude)
798
799     --with-ada-libname=NAME
800         Override the name of the Ada binding (default: "AdaCurses")
801
802     --with-ada-objects=DIR
803         Tell where to install the Ada objects (default:  PREFIX/lib/ada/adalib)
804
805     --with-ada-sharedlib
806         Build a shared library for Ada95 binding, if the compiler permits.
807
808         NOTE: You must also set the --with-shared option on some platforms
809         for a successful build.  You need not use this option when you set
810         --with-shared, unless you want to use the Ada shared library.
811
812     --with-bool=TYPE
813         If --without-cxx is specified, override the type used for the "bool"
814         declared in curses.h (normally the type is automatically chosen to
815         correspond with that in <stdbool.h>, or defaults to platform-specific
816         sizes).
817
818     --with-build-cc=XXX
819         If cross-compiling, specify a host C compiler, which is needed to
820         compile a few utilities which generate source modules for ncurses.
821         If you do not give this option, the configure script checks if the
822         $BUILD_CC variable is set, and otherwise defaults to gcc or cc.
823
824     --with-build-cflags=XXX
825         If cross-compiling, specify the host C compiler-flags.  You might need
826         to do this if the target compiler has unusual flags which confuse the
827         host compiler.
828
829         You can also set the environment variable $BUILD_CFLAGS rather than
830         use this option.
831
832     --with-build-cpp=XXX
833         This option is provided by the same macro used for $BUILD_CC, etc.,
834         but is not directly used by ncurses.
835
836     --with-build-cppflags=XXX
837         If cross-compiling, specify the host C preprocessor-flags.  You might
838         need to do this if the target compiler has unusual flags which confuse
839         the host compiler.
840
841         You can also set the environment variable $BUILD_CPPFLAGS rather than
842         use this option.
843
844     --with-build-ldflags=XXX
845         If cross-compiling, specify the host linker-flags.  You might need to
846         do this if the target linker has unusual flags which confuse the host
847         compiler.
848
849         You can also set the environment variable $BUILD_LDFLAGS rather than
850         use this option.
851
852     --with-build-libs=XXX
853         If cross-compiling, the host libraries.  You might need to do this if
854         the target environment requires unusual libraries.
855
856         You can also set the environment variable $BUILD_LIBS rather than
857         use this option.
858
859     --with-caps=XXX
860         Specify an alternate terminfo capabilities file, which makes the
861         configure script look for "include/Caps.XXX".  A few systems, e.g.,
862         AIX 4.x use the same overall file-format as ncurses for terminfo
863         data, but use different alignments within the tables to support
864         legacy applications.  For those systems, you can configure ncurses
865         to use a terminfo database which is compatible with the native
866         applications.
867
868     --with-ccharw-max=XXX
869         Override the size of the wide-character array in cchar_t structures.
870         Changing this will alter the binary interface.  This defaults to 5.
871
872     --with-chtype=TYPE
873         Override type of chtype, which stores the video attributes and (if
874         --enable-widec is not given) a character.  Prior to ncurses 5.5, this
875         was always unsigned long, but with ncurses 5.5, it may be unsigned.
876         Use this option if you need to preserve compatibility with 64-bit
877         executables, e.g., by setting "--with-chtype=long" (the configure
878         script supplies "unsigned").
879
880     --with-config-suffix=XXX
881         Specify a suffix for the ncursesw6-config file, etc., used to work
882         around conflicts with packages.
883
884     --with-cxx-libname=NAME
885         Override the basename of the ncurses++ library (default: "ncurses++")
886
887     --with-cxx-shared
888         When --with-shared is set, build libncurses++ as a shared library.
889         This implicitly relies upon building with gcc/g++, since other
890         compiler suites may have differences in the way shared libraries are
891         built.  libtool by the way has similar limitations.
892
893     --with-database=XXX
894         Specify the terminfo source file to install.  Usually you will wish
895         to install ncurses' default (misc/terminfo.src).  Certain systems
896         have special requirements, e.g, OS/2 EMX has a customized terminfo
897         source file.
898
899     --with-dbmalloc
900         For testing, compile and link with Conor Cahill's dbmalloc library.
901         This also sets the --disable-leaks option.
902
903     --with-debug
904         Generate debug-libraries (default).  These are named by adding "_g"
905         to the root, e.g., libncurses_g.a
906
907     --with-default-terminfo-dir=XXX
908         Specify the default terminfo database directory.  This is normally
909         DATADIR/terminfo, e.g., /usr/share/terminfo.
910
911     --with-dmalloc
912         For testing, compile and link with Gray Watson's dmalloc library.
913         This also sets the --disable-leaks option.
914
915     --with-export-syms[=XXX]
916         Limit exported symbols using libtool.  The configure script
917         automatically chooses an appropriate ".sym" file, which lists the
918         symbols which are part of the ABI.
919
920     --with-extra-suffix[=XXX]
921         Add the given suffix to header- and library-names to simplify
922         installing incompatible ncurses libraries, e.g., those using a
923         different ABI.  The renaming affects the name of the
924         include-subdirectory if --disable-overwrite is given.
925
926     --with-fallbacks=XXX
927         Specify a list of fallback terminal descriptions which will be
928         compiled into the ncurses library.  See CONFIGURING FALLBACK ENTRIES.
929
930         See also "--with-tic-path" and "--with-infocmp-path".
931
932     --with-form-libname=NAME
933         Override the basename of the form library (default: "form")
934
935     --with-gpm
936         use Alessandro Rubini's GPM library to provide mouse support on the
937         Linux console.  Prior to ncurses 5.5, this introduced a dependency on
938         the GPM library.
939
940         Currently ncurses uses the dlsym() function to bind to the library at
941         runtime, so it is only necessary that the library be present when
942         ncurses is built, to obtain the filename (or soname) used in the
943         corresponding dlopen() call.  If you give a value for this option,
944         e.g.,
945
946                 --with-gpm=$HOME/tmp/test-gpm.so
947
948         that overrides the configure check for the soname.
949
950         See also --without-dlsym
951
952     --with-hashed-db[=XXX]
953         Use a hashed database for storing terminfo data rather than storing
954         each compiled entry in a separate binary file within a directory
955         tree.
956
957         In particular, this uses the Berkeley database 1.8.5 interface, as
958         provided by that and its successors db 2, 3, and 4.  The actual
959         interface is slightly different in the successor versions of the
960         Berkeley database.  The database should have been configured using
961         "--enable-compat185".
962
963         If you use this option for configuring ncurses, tic will only be able
964         to write entries in the hashed database.  infocmp can still read
965         entries from a directory tree as well as reading entries from the
966         hashed database.  To do this, infocmp determines whether the $TERMINFO
967         variable points to a directory or a file, and reads the directory-tree
968         or hashed database respectively.
969
970         You cannot have a directory containing both hashed-database and
971         filesystem-based terminfo entries.
972
973         Use the parameter value to give the install-prefix used for the
974         database, e.g.,
975                 --with-hashed-db=/usr/local/BigBase
976         to find the corresponding include- and lib-directories under the
977         given directory.  Alternatively, you can specify a directory leaf
978         name, e.g.,
979                 --with-hashed-db=db4
980         to make the configure script look for files in a subdirectory such as
981                 /usr/include/db4/db.h
982                 /usr/lib/db4/libdb.so
983
984         See also the --enable-getcap option.
985
986     --with-infocmp-path[=XXX]
987         Use this option to override the automatic detection of tic in your
988         $PATH when building fallbacks (see "--with-fallbacks").
989
990     --with-install-prefix=XXX
991         Allows you to specify an alternate location for installing ncurses
992         after building it.  The value you specify is prepended to the "real"
993         install location.  This simplifies making binary packages.  The
994         makefile variable DESTDIR is set by this option.  It is also possible
995         to use
996                 make install DESTDIR=XXX
997         since the makefiles pass that variable to subordinate makes.
998
999         NOTE: a few systems build shared libraries with fixed pathnames; this
1000         option probably will not work for those configurations.
1001
1002     --with-lib-prefix=XXX
1003         OS/2 EMX used a different naming convention from most Unix-like
1004         platforms.  It required that the "lib" part of a library name was
1005         omitted.  Newer EMX as part of eComStation does not follow that
1006         convention.  Use this option to override the configure script's
1007         assumptions about the library-prefix.  If this option is omitted, it
1008         uses the original OS/2 EMX convention for that platform.  Use
1009         "--with-lib-prefix=lib" for the newer EMX in eComStation.  Use
1010         "--without-lib-prefix" to suppress it for other odd platforms.
1011
1012     --with-libtool[=XXX]
1013         Generate libraries with libtool.  If this option is selected, then it
1014         overrides all other library model specifications.  Note that libtool
1015         must already be installed, uses makefile rules dependent on GNU make,
1016         and does not promise to follow the version numbering convention of
1017         other shared libraries on your system.  However, if the --with-shared
1018         option does not succeed, you may get better results with this option.
1019
1020         If a parameter value is given, it must be the full pathname of the
1021         particular version of libtool, e.g.,
1022                 /usr/bin/libtool-1.2.3
1023
1024         It is possible to rebuild the configure script to use the automake
1025         macros for libtool, e.g., AC_PROG_LIBTOOL.  See the comments in
1026         aclocal.m4 for CF_PROG_LIBTOOL, and ensure that you build configure
1027         using the appropriate patch for autoconf from
1028                 https://invisible-island.net/autoconf/
1029
1030     --with-libtool-opts=XXX
1031         Allow user to pass additional libtool options into the library creation
1032         and link steps.  The main use for this is to do something like
1033                 ./configure --with-libtool-opts=-static
1034         to get the same behavior as automake-flavored
1035                 ./configure --enable-static
1036
1037     --with-manpage-aliases
1038         Tell the configure script you wish to create entries in the
1039         man-directory for aliases to manpages which list them, e.g., the
1040         functions in the panel manpage.  This is the default.  You can disable
1041         it if your man program does this.  You can also disable
1042         --with-manpage-symlinks to install files containing a ".so" command
1043         rather than symbolic links.
1044
1045     --with-manpage-format=XXX
1046         Tell the configure script how you would like to install man-pages.  The
1047         option value must be one of these:  gzip, compress, BSDI, normal,
1048         formatted.  If you do not give this option, the configure script
1049         attempts to determine which is the case.
1050
1051     --with-manpage-renames=XXX
1052         Tell the configure script that you wish to rename the manpages while
1053         installing.  Currently the only distribution which does this is Debian.
1054         The option value specifies the name of a file that lists the renamed
1055         files, e.g., $srcdir/man/man_db.renames
1056
1057     --with-manpage-symlinks
1058         Tell the configure script that you wish to make symbolic links in the
1059         man-directory for aliases to the man-pages.  This is the default, but
1060         can be disabled for systems that provide this automatically.  Doing
1061         this on systems that do not support symbolic links will result in
1062         copying the man-page for each alias.
1063
1064     --with-manpage-tbl
1065         Tell the configure script that you wish to preprocess the manpages
1066         by running them through tbl to generate tables understandable by
1067         nroff.
1068
1069     --with-menu-libname=NAME
1070         Override the basename of the menu library (default: "menu")
1071
1072     --with-mmask-t=TYPE
1073         Override type of mmask_t, which stores the mouse mask.  Prior to
1074         ncurses 5.5, this was always unsigned long, but with ncurses 5.5, it
1075         may be unsigned.  Use this option if you need to preserve compatibility
1076         with 64-bit executables.
1077
1078     --with-normal
1079         Generate normal (i.e., static) libraries (default).
1080
1081         Note:  on Linux, the configure script will attempt to use the GPM
1082         library via the dlsym() function call.  Use --without-dlsym to disable
1083         this feature, or --without-gpm, depending on whether you wish to use
1084         GPM.
1085
1086     --with-ospeed=TYPE
1087         Override type of ospeed variable, which is part of the termcap
1088         compatibility interface.  In termcap, this is a 'short', which works
1089         for a wide range of baudrates because ospeed is not the actual speed
1090         but the encoded value, e.g., B9600 would be a small number such as 13.
1091         However the encoding scheme originally allowed for values "only" up to
1092         38400bd.  A newer set of definitions past 38400bd is not encoded as
1093         compactly, and is not guaranteed to fit into a short (see the function
1094         cfgetospeed(), which returns a speed_t for this reason).  In practice,
1095         applications that required knowledge of the ospeed variable, i.e.,
1096         those using termcap, do not use the higher speeds.  Your application
1097         (or system, in general) may or may not.
1098
1099     --with-panel-libname=NAME
1100         Override the basename of the panel library (default: "panel")
1101
1102     --with-pc-suffix=SUFFIX
1103         If ".pc" files are installed, optionally add a suffix to the files
1104         and corresponding package names to separate unusual configurations.
1105         If no option value is given (or if it is "none"), no suffix is added.
1106
1107     --with-pcre2
1108         Add PCRE2 (Perl-compatible regular expressions v2) to the build if it
1109         is available and the user requests it.  Assume the application will
1110         otherwise use the POSIX interface.
1111
1112         This is useful for MinGW builds because the usual POSIX interface is
1113         not supplied by the development environment, while ncurses' form
1114         library uses a regular expression feature for one of the field types.
1115
1116     --with-pkg-config=[DIR]
1117         Check for pkg-config, optionally specifying its path.
1118
1119     --with-pkg-config-libdir=[DIR]
1120         If pkg-config was found, override the automatic check for its library
1121         path.
1122
1123     --with-profile
1124         Generate profile-libraries These are named by adding "_p" to the root,
1125         e.g., libncurses_p.a
1126
1127     --with-pthread
1128         Link with POSIX threads, set --enable-reentrant.  The use_window() and
1129         use_screen() functions will use mutex's, allowing rudimentary support
1130         for multithreaded applications.
1131
1132     --with-rcs-ids
1133         Compile-in RCS identifiers.  Most of the C files have an identifier.
1134
1135     --with-rel-version=NUM
1136         Override the release version, which may be used in shared library
1137         filenames.  This consists of a major and minor version number separated
1138         by ".".  Normally the major version number is the same as the ABI
1139         version; some ports have special requirements for compatibility.
1140
1141     --with-shared
1142         Generate shared-libraries.  The names given depend on the system for
1143         which you are building, typically using a ".so" suffix, along with
1144         symbolic links that refer to the release version.
1145
1146         NOTE: Unless you override the configure script by setting the $CFLAGS
1147         environment variable, these will not be built with the -g debugging
1148         option.
1149
1150         NOTE: For some configurations, e.g., installing a new version of
1151         ncurses shared libraries on a machine which already has ncurses
1152         shared libraries, you may encounter problems with the linker.
1153         For example, it may prevent you from running  the build tree's
1154         copy of tic (for installing the terminfo database) because it
1155         loads the system's copy of the ncurses shared libraries.
1156
1157         In that case, using the misc/shlib script may be helpful, since it
1158         sets $LD_LIBRARY_PATH to point to the build tree, e.g.,
1159
1160                 ./misc/shlib make install
1161
1162         Alternatively, for most platforms, the linker accepts a list of
1163         directories which will be searched for libraries at run-time.  The
1164         configure script allows you to modify this list using the
1165         RPATH_LIST environment variable.  It is a colon-separated list of
1166         directories (default:  the "libdir" set via the configure script).
1167         If you set that to put "../lib" first in the list, the linker will
1168         look first at the build-directory, and avoid conflict with libraries
1169         already installed.  One drawback to this approach is that libraries
1170         can be accidentally searched in any "../lib" directory.
1171
1172         NOTE: If you use the --with-ada-sharedlib option, you should also
1173         set this option, to ensure that C-language modules needed for the
1174         Ada binding use appropriate compiler options.
1175
1176     --with-shlib-version=XXX
1177         Specify whether to use the release or ABI version for shared libraries.
1178         This is normally chosen automatically based on the type of system
1179         which you are building on.  We use it for testing the configure script.
1180
1181     --with-sysmouse
1182         use FreeBSD sysmouse interface provide mouse support on the console.
1183
1184     --with-system-type=XXX
1185         For testing, override the derived host system-type which is used to
1186         decide things such as the linker commands used to build shared
1187         libraries.  This is normally chosen automatically based on the type of
1188         system which you are building on.  We use it for testing the configure
1189         script.
1190
1191     --with-terminfo-dirs=XXX
1192         Specify a search-list of terminfo directories which will be compiled
1193         into the ncurses library (default: DATADIR/terminfo)
1194
1195         This is a colon-separated list, like the TERMINFO_DIRS environment
1196         variable.
1197
1198     --with-termlib[=XXX]
1199         When building the ncurses library, organize this as two parts:  the
1200         curses library (libncurses) and the low-level terminfo library
1201         (libtinfo).  This is done to accommodate applications that use only
1202         the latter.  The terminfo library is about half the size of the total.
1203
1204         If an option value is given, that overrides the name of the terminfo
1205         library.  For instance, if the wide-character version is built, the
1206         terminfo library would be named libtinfow.  But the libtinfow interface
1207         is upward compatible from libtinfo, so it would be possible to overlay
1208         libtinfo.so with a "wide" version of libtinfow.so by renaming it with
1209         this option.
1210
1211     --with-termpath=XXX
1212         Specify a search-list of termcap files which will be compiled into the
1213         ncurses library (default:  /etc/termcap:/usr/share/misc/termcap)
1214
1215     --with-tic-path[=XXX]
1216         Use this option to override the automatic detection of tic in your
1217         $PATH when building fallbacks (see "--with-fallbacks").
1218
1219     --with-ticlib[=XXX]
1220         When building the ncurses library, build a separate library for
1221         the modules that are used only by the utility programs.  Normally
1222         those would be bundled with the termlib or ncurses libraries.
1223
1224         If an option value is given, that overrides the name of the tic
1225         library.  As in termlib, there is no ABI difference between the
1226         "wide" libticw.so and libtic.so
1227
1228         NOTE: Overriding the name of the tic library may be useful if you are
1229         also using the --with-termlib option to rename libtinfo.  If you are
1230         not doing that, renaming the tic library can result in conflicting
1231         library dependencies for tic and other programs built with the tic
1232         library.
1233
1234     --with-tparm-arg[=XXX]
1235         Override the type used for tparm() arguments, which normally is a
1236         "long".  However the function must assume that its arguments can hold a
1237         pointer to char's which is not always workable for 64-bit platforms.  A
1238         better choice would be intptr_t, which was not available at the time
1239         tparm's interface was defined.
1240
1241         If the option is not given, this defaults to "long".
1242
1243     --with-trace
1244         Configure the trace() function as part of the all models of the ncurses
1245         library.  Normally it is part of the debug (libncurses_g) library only.
1246
1247     --with-valgrind
1248         For testing, compile with debug option.
1249         This also sets the --disable-leaks option.
1250
1251     --with-versioned-syms[=XXX]
1252         The Solaris, GNU and reportedly some other linkers (ld) accept a
1253         "--version-script" option which tells the linker to annotate the
1254         resulting objects with version identifiers.
1255
1256         Use "objdump -T" on a library to see the annotations.
1257
1258         The configure script attempts to automatically apply a suitable ".map"
1259         file to provide this information for Linux.  Solaris mapfiles differ:
1260
1261         a) comments are not accepted
1262         b) wildcards are not accepted, except for a special case of "_*".
1263         c) each symbol listed in the map file must exist in the library
1264
1265         The Solaris limitations conflict with the development goal of providing
1266         a small set of ".map" files as examples, which cover the most common
1267         configurations.  Because that coverage is done by merging together
1268         several builds, some symbols will be listed in the the ".map" files
1269         that do not happen to be present in one configuration or another.
1270
1271         The sample ".map" (and ".sym") files are generated using a set of
1272         scripts which build several configurations for each release version,
1273         checking to see which of the "_nc_" symbols can be made local.  In
1274         addition to the ncurses libraries and programs, the symbols used
1275         by the "tack" program before version 1.08 are made global.
1276
1277         These sample ".map" files will not cover all possible combinations.
1278         In some cases, e.g., when using the --with-weak-symbols option, you
1279         may prefer to use a different ".map" file by setting this option's
1280         value.
1281
1282     --with-wrap-prefix=XXX
1283         When using the --enable-reentrant option, ncurses redefines variables
1284         that would be global in curses, e.g., LINES, as a macro that calls a
1285         "wrapping" function which fetches the data from the current SCREEN
1286         structure.  Normally that function is named by prepending "_nc_" to the
1287         variable's name.  The function is technically private (since portable
1288         applications would not refer directly to it).  But according to one
1289         line of reasoning, it is not the same type of "private" as functions
1290         which applications should not call even via a macro.  This configure
1291         option lets you choose the prefix for these wrapped variables.
1292
1293     --with-x11-rgb=FILE
1294         Provide a pathname for the X11 rgb file, used by the picsmap program.
1295         This overrides a configure check which usually works, but is needed
1296         due to the lack of standardization for X11's files.
1297
1298     --with-xterm-kbs=XXX
1299         Configure xterm's terminfo entries to use either BS (^H, i.e., ASCII
1300         backspace) or DEL (^?, or 127).  XXX can be BS (or bs, 8) or DEL
1301         (or del, 127).
1302
1303         During installation, the makefile and scripts modifies the "xterm+kbs"
1304         terminfo entry to use this setting.
1305
1306     --without-ada
1307         Suppress the configure script's check for Ada95, do not build the
1308         Ada95 binding and related demo.
1309
1310     --without-curses-h
1311         Don't install the ncurses header with the name "curses.h".  Rather,
1312         install as "ncurses.h" and modify the installed headers and manpages
1313         accordingly.
1314
1315         Likewise, do not install an alias "curses" for the ncurses manpage.
1316
1317     --without-cxx
1318         XSI curses declares "bool" as part of the interface.  C++ also declares
1319         "bool".  Neither specifies the size and type of booleans, but both
1320         insist on the same name.  We chose to accommodate this by making the
1321         configure script check for the size and type (e.g., unsigned or signed)
1322         that your C++ compiler uses for booleans.  If you do not wish to use
1323         ncurses with C++, use this option to tell the configure script to not
1324         adjust ncurses bool to match C++.
1325
1326     --without-cxx-binding
1327         Suppress the configure script's check for C++, do not build the
1328         C++ binding and related demo.
1329
1330     --without-develop
1331         Disable development options.  This does not include those that change
1332         the interface, such as --enable-widec.
1333
1334     --without-dlsym
1335         Do not use dlsym() to load GPM dynamically.
1336
1337     --without-manpages
1338         Tell the configure script to suppress the install of ncurses' manpages.
1339
1340     --without-progs
1341         Tell the configure script to suppress the build of ncurses' application
1342         programs (e.g., tic).  The test applications will still be built if you
1343         type "make", though not if you simply do "make install".
1344
1345     --without-tack
1346         Suppress build/install with tack program, if it happens to be
1347         in the same build-tree (tack was moved out of the ncurses source-tree
1348         in 20070203).
1349
1350     --without-tests
1351         Tell the configure script to suppress the build of ncurses' test
1352         programs.
1353
1354     --without-xterm-new
1355         Tell the configure script to use "xterm-old" for the entry used in
1356         the terminfo database.  This will work with variations such as
1357         X11R5 and X11R6 xterm.
1358
1359
1360 COMPATIBILITY WITH OLDER VERSIONS OF NCURSES:
1361 --------------------------------------------
1362
1363     Because ncurses implements X/Open Curses, its interface is fairly stable.
1364     That does not mean the interface does not change.  Changes are made to the
1365     documented interfaces when we find differences between ncurses and X/Open
1366     or implementations which largely correspond to X/Open (such as Solaris).
1367     We add extensions to those interfaces to solve problems not addressed by
1368     the original curses design, but those must not conflict with the X/Open
1369     documentation.
1370
1371     Here are some of the major interface changes, and related problems which
1372     you may encounter when building a system with different versions of
1373     ncurses:
1374
1375     6.2 (Feb 12, 2020)
1376         Interface changes:
1377
1378         + the terminal database must be compiled with ncurses 6.2 tic;
1379           older versions of tic/infocmp will not work.  Aside from that,
1380           the compiled database will work with older applications.
1381
1382         + "*.pc" and "ncurses*-config" files give the same information.
1383
1384         + vwprintw and vwscanw are deprecated.
1385
1386         Added extensions:
1387
1388         + These make it simpler to substitute a debug-configuration of the
1389           library for non-debug:
1390                 curses_trace
1391                 exit_curses
1392                 exit_terminfo
1393
1394         Added internal functions (other than "_sp" variants):
1395
1396         + These provide fast-lookup of common user-defined capabilities:
1397                 _nc_find_user_entry
1398                 _nc_get_userdefs_table
1399                 _nc_get_hash_user
1400
1401         + This is added to work around compiler-warnings:
1402                 _nc_fmt_funcptr
1403
1404         Removed internal functions:
1405
1406         + _nc_import_termtype
1407
1408         Modified internal functions:
1409
1410         + _nc_reserve_pairs no longer returns a value
1411
1412     6.1 (Jan 27, 2018)
1413         Interface changes:
1414
1415         + X/Open Curses specifies a "reserved" void* parameter in several
1416           functions, saying that it must be NULL.  In this release, if the
1417           parameter is non-NULL, it is interpreted as a point to an integer
1418           containing a color pair.  In previous releases, a non-NULL parameter
1419           caused an error return.  Portable applications are unaffected.  Here
1420           are the functions which have been extended:
1421                 attr_get
1422                 attr_off
1423                 attr_on
1424                 attr_set
1425                 chgat
1426                 color_set
1427                 mvchgat
1428                 mvwchgat
1429                 slk_attr_off
1430                 slk_attr_on
1431                 slk_attr_set
1432                 wattr_get
1433                 wattr_on
1434                 wattr_off
1435                 wattr_set
1436                 wchgat
1437                 wcolor_set
1438
1439         + the TERMINAL structure declared in <term.h> has been made opaque,
1440           and its size increased to handle the increased size of color pair
1441           and color value, as well as other numeric capabilities.
1442
1443           A few applications required change, e.g., to use def_prog_mode;
1444           only one application (tack) is known to have a valid reason for
1445           accessing these internal details, and that was addressed by the
1446           release of tack 1.08 in 2017.  Internal functions marked as used
1447           by tack will be deprecated in future releases.
1448
1449         Added extensions:
1450
1451         + Several new functions were added to manipulate extended color pairs
1452           and color values.  These include:
1453                 alloc_pair
1454                 extended_color_content
1455                 extended_pair_content
1456                 extended_slk_color
1457                 find_pair
1458                 free_pair
1459                 init_extended_color
1460                 init_extended_pair
1461                 reset_color_pairs
1462
1463           as well as corresponding sp-functions.
1464
1465         + A new terminfo capability "RGB" tells the ncurses library that the
1466           color values are red/green/blue, to eliminate the need for palettes
1467           in that special case for the color_content function.
1468
1469         Added internal functions (other than "_sp" variants):
1470                 _nc_copy_termtype2
1471                 _nc_export_termtype2
1472                 _nc_fallback2
1473                 _nc_find_prescr
1474                 _nc_forget_prescr
1475                 _nc_free_termtype2
1476                 _nc_read_entry2
1477                 _nc_write_object
1478
1479         Removed internal functions:
1480                 _nc_check_termtype
1481                 _nc_resolve_uses
1482
1483         Modified internal functions:
1484
1485         + symbols are used by tic/infocmp/toe:
1486                 _nc_align_termtype - change parameters to TERMTYPE2*
1487                 _nc_check_termtype2 - change parameter to TERMTYPE2*
1488                 _nc_read_file_entry - change parameter to TERMTYPE2*
1489                 _nc_read_termtype - change parameter to TERMTYPE2*
1490                 _nc_trim_sgr0 - change parameter to TERMTYPE2*
1491                 _nc_write_entry - change parameter to TERMTYPE2*
1492
1493         + symbols used only within the library:
1494                 _nc_fallback - change return type to TERMTYPE2*
1495                 _nc_init_termtype - change parameter to TERMTYPE2*
1496
1497     6.0 (Aug 08, 2015)
1498         Interface changes:
1499
1500         + The 6.0 ABI modifies the defaults for these configure options:
1501            --enable-const
1502            --enable-ext-colors
1503            --enable-ext-mouse
1504            --enable-ext-putwin
1505            --enable-interop
1506            --enable-lp64
1507            --enable-sp-funcs
1508            --with-chtype=uint32_t
1509            --with-mmask_t=uint32_t
1510            --with-tparm-arg=intptr_t
1511
1512         + ncurses supports symbol versioning.  If you use this feature, about
1513           half of the "_nc_" private symbols are changed to local symbols.
1514
1515         + a few applications may need to explicitly flush the standard output
1516           when switching between printf's and (curses) printw.
1517
1518         Added extensions:
1519
1520         + use_tioctl is an improvement over use_env
1521
1522         + added wgetdelay to support the NCURSES_OPAQUE feature.
1523
1524         Added internal functions (other than "_sp" variants):
1525                 _nc_init_termtype
1526                 _nc_mvcur
1527                 _nc_putchar
1528                 _nc_setenv_num
1529                 _nc_trace_mmask_t
1530
1531         Removed internal functions:
1532                 none
1533
1534         Modified internal functions:
1535                 _nc_do_color - change parameters from short/bool to int
1536                 _nc_keypad - change parameter from bool to int
1537                 _nc_setupscreen - change parameter from bool to int
1538                 _nc_signal_handler - change parameter from bool to int
1539
1540     5.9 (Apr 04, 2011)
1541     5.8 (Feb 26, 2011)
1542         Interface changes:
1543
1544         + add an alternate library configuration, i.e., "terminal driver" to
1545           support port to Windows, built with MinGW.  There are two drivers
1546           (terminfo and Windows console).  The terminfo driver works on other
1547           platforms.
1548
1549         + add a new set of functions which accept a SCREEN* parameter, in
1550           contrast with the original set which use the global value "sp".
1551           By default, these names end with "_sp", and are otherwise
1552           functionally identical with the originals.
1553
1554           In addition to the "_sp" functions, there are a few new functions
1555           associated with this feature:  ceiling_panel, ground_panel,
1556           new_prescr.
1557
1558           If the library is not built with the sp-funcs extension, there
1559           are no related interface changes.
1560
1561         + add tiparm function based on review of X/Open Curses Issue 7.
1562
1563         + change internal _nc_has_mouse function to public has_mouse function
1564
1565         Added extensions:
1566
1567         + add a few more functions to support the NCURSES_OPAQUE feature:
1568           get_escdelay, is_pad, is_subwin
1569
1570         Added internal functions (other than "_sp" variants):
1571                 _nc_curscr_of
1572                 _nc_format_slks
1573                 _nc_get_alias_table
1574                 _nc_get_hash_info
1575                 _nc_insert_wch
1576                 _nc_newscr_of
1577                 _nc_outc_wrapper
1578                 _nc_retrace_char
1579                 _nc_retrace_int_attr_t
1580                 _nc_retrace_mmask_t
1581                 _nc_setup_tinfo
1582                 _nc_stdscr_of
1583                 _nc_tinfo_cmdch
1584
1585         Removed internal functions:
1586                 _nc_makenew (some configurations replace by _nc_makenew_sp)
1587
1588         Modified internal functions:
1589                 _nc_UpdateAttrs
1590                 _nc_get_hash_table
1591                 _nc_has_mouse
1592                 _nc_insert_ch
1593                 _nc_wgetch
1594
1595     5.7 (November 2, 2008)
1596         Interface changes:
1597
1598         + generate linkable stubs for some macros:
1599                 getattrs
1600
1601         + Add new library configuration for tic-library (the non-curses portion
1602           of the ncurses library used for the tic program as well as some
1603           others such as tack.  There is no API change, but makefiles would be
1604           changed to use the tic-library built separately.
1605
1606           tack, distributed separately from ncurses, uses some of the internal
1607           _nc_XXX functions, which are declared in the tic.h header file.
1608
1609           The reason for providing this separate library is that none of the
1610           functions in it are suitable for threaded applications.
1611
1612         + Add new library configuration (ncursest, ncurseswt) which provides
1613           rudimentary support for POSIX threads.  This introduces opaque
1614           access functions to the WINDOW structure and adds a parameter to
1615           several internal functions.
1616
1617         + move most internal variables (except tic-library) into data blocks
1618           _nc_globals and _nc_prescreen to simplify analysis.  Those were
1619           globally accessible, but since they were not part of the documented
1620           API, there is no ABI change.
1621
1622         + changed static tables of strings to be indices into long strings, to
1623           improve startup performance.  This changes parameter lists for some
1624           of the internal functions.
1625
1626         Added extensions:
1627
1628         + add NCURSES_OPAQUE definition in curses.h to control whether internal
1629           details of the WINDOW structure are visible to an application.  This
1630           is always defined when the threaded library is built, and is optional
1631           otherwise.  New functions for this:  is_cleared, is_idcok, is_idlok,
1632           is_immedok, is_keypad, is_leaveok, is_nodelay, is_notimeout,
1633           is_scrollok, is_syncok, wgetparent and wgetscrreg.
1634
1635         + the threaded library (ncursest) also disallows direct updating of
1636           global curses-level variables, providing functions (via macros) for
1637           obtaining their value.  A few of those variables can be modified by
1638           the application, using new functions:  set_escdelay, set_tabsize
1639
1640         + added functions use_window() and use_screen() which wrap a mutex
1641           (if threading is configured) around a call to a user-supplied
1642           function.
1643
1644         Added internal functions:
1645                 _nc_get_alias_table
1646                 _nc_get_screensize
1647                 _nc_keyname
1648                 _nc_screen_of
1649                 _nc_set_no_padding
1650                 _nc_tracechar
1651                 _nc_tracemouse
1652                 _nc_unctrl
1653                 _nc_ungetch
1654
1655                 These are used for leak-testing, and are stubs for
1656                 ABI compatibility when ncurses is not configured for that
1657                 using the --disable-leaks configure script option:
1658
1659                 _nc_free_and_exit
1660                 _nc_leaks_tinfo
1661
1662         Removed internal functions:
1663                 none
1664
1665         Modified internal functions:
1666                 _nc_fifo_dump
1667                 _nc_find_entry
1668                 _nc_handle_sigwinch
1669                 _nc_init_keytry
1670                 _nc_keypad
1671                 _nc_locale_breaks_acs
1672                 _nc_timed_wait
1673                 _nc_update_screensize
1674
1675                 Use new typedef TRIES to replace "struct tries":
1676
1677                 _nc_add_to_try
1678                 _nc_expand_try
1679                 _nc_remove_key
1680                 _nc_remove_string
1681                 _nc_trace_tries
1682
1683     5.6 (December 17, 2006)
1684         Interface changes:
1685
1686         + generate linkable stubs for some macros:
1687
1688           getbegx, getbegy, getcurx, getcury, getmaxx, getmaxy, getparx,
1689           getpary, getpary,
1690
1691           and (for libncursesw)
1692
1693           wgetbkgrnd
1694
1695         Added extensions:
1696                 nofilter()
1697                 use_legacy_coding()
1698
1699         Added internal functions:
1700                 _nc_first_db
1701                 _nc_get_source
1702                 _nc_handle_sigwinch
1703                 _nc_is_abs_path
1704                 _nc_is_dir_path
1705                 _nc_is_file_path
1706                 _nc_keep_tic_dir
1707                 _nc_keep_tic_dir
1708                 _nc_last_db
1709                 _nc_next_db
1710                 _nc_read_termtype
1711                 _nc_tic_dir
1712
1713                 Also (if using the hashed database configuration):
1714
1715                 _nc_db_close
1716                 _nc_db_first
1717                 _nc_db_get
1718                 _nc_db_have_data
1719                 _nc_db_have_index
1720                 _nc_db_next
1721                 _nc_db_open
1722                 _nc_db_put
1723
1724                 otherwise
1725
1726                 _nc_hashed_db
1727
1728         Removed internal functions:
1729                 none
1730
1731         Modified internal functions:
1732                 _nc_add_to_try
1733                 _nc_do_color
1734                 _nc_expand_try
1735                 _nc_remove_key
1736                 _nc_setupscreen
1737
1738     5.5 (October 10, 2005)
1739         Interface changes:
1740
1741         + terminfo installs "xterm-new" as "xterm" entry rather than
1742           "xterm-old" (aka xterm-r6).
1743
1744         + terminfo data is installed using the tic -x option (few systems
1745           still use ncurses 4.2).
1746
1747         + modify C++ binding to work with newer C++ compilers by providing
1748           initializers and using modern casts.  Old-style header names are
1749           still used in this release to allow compiling with not-so-old
1750           compilers.
1751
1752         + form and menu libraries now work with wide-character data.
1753           Applications which bypassed the form library and manipulated the
1754           FIELD.buf data directly will not work properly with libformw, since
1755           that no longer points to an array of char.  The set_field_buffer()
1756           and field_buffer() functions translate to/from the actual field
1757           data.
1758
1759         + change SP->_current_attr to a pointer, adjust ifdef's to ensure that
1760           libtinfo.so and libtinfow.so have the same ABI.  The reason for this
1761           is that the corresponding data which belongs to the upper-level
1762           ncurses library has a different size in each model.
1763
1764         + winnstr() now returns multibyte character strings for the
1765           wide-character configuration.
1766
1767         + assume_default_colors() no longer requires that use_default_colors()
1768           be called first.
1769
1770         + data_ahead() now works with wide-characters.
1771
1772         + slk_set() and slk_wset() now accept and store multibyte or
1773           multicolumn characters.
1774
1775         + start_color() now returns OK if colors have already been started.
1776           start_color() also returns ERR if it cannot allocate memory.
1777
1778         + pair_content() now returns -1 for consistency with init_pair() if it
1779           corresponds to the default-color.
1780
1781         + unctrl() now returns null if its parameter does not correspond
1782           to an unsigned char.
1783
1784         Added extensions:
1785                 Experimental mouse version 2 supports wheel mice with buttons
1786                 4 and 5.  This requires ABI 6 because it modifies the encoding
1787                 of mouse events.
1788
1789                 Experimental extended colors allows encoding of 256 foreground
1790                 and background colors, e.g., with the xterm-256color or
1791                 xterm-88color terminfo entries.  This requires ABI 6 because
1792                 it changes the size of cchar_t.
1793
1794         Added internal functions:
1795                 _nc_check_termtype2
1796                 _nc_resolve_uses2
1797                 _nc_retrace_cptr
1798                 _nc_retrace_cvoid_ptr
1799                 _nc_retrace_void_ptr
1800                 _nc_setup_term
1801
1802         Removed internal functions:
1803                 none
1804
1805         Modified internal functions:
1806                 _nc_insert_ch
1807                 _nc_save_str
1808                 _nc_trans_string
1809
1810     5.4 (February 8, 2004)
1811         Interface changes:
1812
1813         + add the remaining functions for X/Open curses wide-character support.
1814           These are only available if the library is configured using the
1815           --enable-widec option.
1816                 pecho_wchar()
1817                 slk_wset()
1818
1819         + write getyx() and related 2-return macros in terms of getcury(),
1820           getcurx(), etc.
1821
1822         + simplify ifdef for bool declaration in curses.h
1823
1824         + modify ifdef's in curses.h that disabled use of __attribute__() for
1825           g++, since recent versions implement the cases which ncurses uses.
1826
1827         + change some interfaces to use const:
1828                 define_key()
1829                 mvprintw()
1830                 mvwprintw()
1831                 printw()
1832                 vw_printw()
1833                 winsnstr()
1834                 wprintw()
1835
1836         Added extensions:
1837                 key_defined()
1838
1839         Added internal functions:
1840                 _nc_get_locale()
1841                 _nc_insert_ch()
1842                 _nc_is_charable()       wide
1843                 _nc_locale_breaks_acs()
1844                 _nc_pathlast()
1845                 _nc_to_char()           wide
1846                 _nc_to_widechar()       wide
1847                 _nc_tparm_analyze()
1848                 _nc_trace_bufcat()      debug
1849                 _nc_unicode_locale()
1850
1851         Removed internal functions:
1852                 _nc_outstr()
1853                 _nc_sigaction()
1854
1855         Modified internal functions:
1856                 _nc_remove_string()
1857                 _nc_retrace_chtype()
1858
1859     5.3 (October 12, 2002)
1860         Interface changes:
1861
1862         + change type for bool used in headers to NCURSES_BOOL, which usually
1863           is the same as the compiler's definition for 'bool'.
1864
1865         + add all but two functions for X/Open curses wide-character support.
1866           These are only available if the library is configured using the
1867           --enable-widec option.  Missing functions are
1868                 pecho_wchar()
1869                 slk_wset()
1870
1871         + add environment variable $NCURSES_ASSUMED_COLORS to modify the
1872           assume_default_colors() extension.
1873
1874         Added extensions:
1875                 is_term_resized()
1876                 resize_term()
1877
1878         Added internal functions:
1879                 _nc_altcharset_name()   debug
1880                 _nc_reset_colors()
1881                 _nc_retrace_bool()      debug
1882                 _nc_retrace_unsigned()  debug
1883                 _nc_rootname()
1884                 _nc_trace_ttymode()     debug
1885                 _nc_varargs()           debug
1886                 _nc_visbufn()           debug
1887                 _nc_wgetch()
1888
1889         Removed internal functions:
1890                 _nc_background()
1891
1892         Modified internal functions:
1893                 _nc_freeall()           debug
1894
1895     5.2 (October 21, 2000)
1896         Interface changes:
1897
1898         + revert termcap ospeed variable to 'short' (see discussion of the
1899           --with-ospeed configure option).
1900
1901     5.1 (July 8, 2000)
1902         Interface changes:
1903
1904         + made the extended terminal capabilities
1905           (configure --enable-tcap-names) a standard feature.  This should
1906           be transparent to applications that do not require it.
1907
1908         + removed the trace() function and related trace support from the
1909           production library.
1910
1911         + modified curses.h.in, undef'ing some symbols to avoid conflict
1912           with C++ STL.
1913
1914         Added extensions:  assume_default_colors().
1915
1916     5.0 (October 23, 1999)
1917         Interface changes:
1918
1919         + implemented the wcolor_set() and slk_color() functions.
1920
1921         + move macro winch to a function, to hide details of struct ldat
1922
1923         + corrected prototypes for slk_* functions, using chtype rather than
1924           attr_t.
1925
1926         + the slk_attr_{set,off,on} functions need an additional void*
1927           parameter according to XSI.
1928
1929         + modified several prototypes to correspond with 1997 version of X/Open
1930           Curses:  [w]attr_get(), [w]attr_set(), border_set() have different
1931           parameters.  Some functions were renamed or misspelled:
1932           erase_wchar(), in_wchntr(), mvin_wchntr().  Some developers have used
1933           attr_get().
1934
1935         Added extensions:  keybound(), curses_version().
1936
1937         Terminfo database changes:
1938
1939         + change translation for termcap 'rs' to terminfo 'rs2', which is
1940           the documented equivalent, rather than 'rs1'.
1941
1942         The problems are subtler in recent releases.
1943
1944         a) This release provides users with the ability to define their own
1945            terminal capability extensions, like termcap.  To accomplish this,
1946            we redesigned the TERMTYPE struct (in term.h).  Very few
1947            applications use this struct.  They must be recompiled to work with
1948            the 5.0 library.
1949
1950         a) If you use the extended terminfo names (i.e., you used configure
1951            --enable-tcap-names), the resulting terminfo database can have some
1952            entries which are not readable by older versions of ncurses.  This
1953            is a bug in the older versions:
1954
1955            + the terminfo database stores booleans, numbers and strings in
1956              arrays.  The capabilities that are listed in the arrays are
1957              specified by X/Open.  ncurses recognizes a number of obsolete and
1958              extended names which are stored past the end of the specified
1959              entries.
1960
1961            + a change to read_entry.c in 951001 made the library do an lseek()
1962              call incorrectly skipping data which is already read from the
1963              string array.  This happens when the number of strings in the
1964              terminfo data file is greater than STRCOUNT, the number of
1965              specified and obsolete or extended strings.
1966
1967            + as part of alignment with the X/Open final specification, in the
1968              990109 patch we added two new terminfo capabilities:
1969              set_a_attributes and set_pglen_inch).  This makes the indices for
1970              the obsolete and extended capabilities shift up by 2.
1971
1972            + the last two capabilities in the obsolete/extended list are memu
1973              and meml, which are found in most terminfo descriptions for xterm.
1974
1975              When trying to read this terminfo entry, the spurious lseek()
1976              causes the library to attempt to read the final portion of the
1977              terminfo data (the text of the string capabilities) 4 characters
1978              past its starting point, and reads 4 characters too few.  The
1979              library rejects the data, and applications are unable to
1980              initialize that terminal type.
1981
1982            FIX: remove memu and meml from the xterm description.  They are
1983            obsolete, not used by ncurses.  (It appears that the feature was
1984            added to xterm to make it more like hpterm).
1985
1986            This is not a problem if you do not use the -x option of tic to
1987            create a terminfo database with extended names.  Note that the
1988            user-defined terminal capabilities are not affected by this bug,
1989            since they are stored in a table after the older terminfo data ends,
1990            and are invisible to the older libraries.
1991
1992         c) Some developers did not wish to use the C++ binding, and used the
1993            configure --without-cxx option.  This causes problems if someone
1994            uses the ncurses library from C++ because that configure test
1995            determines the type for C++'s bool and makes ncurses match it, since
1996            both C++ and curses are specified to declare bool.  Calling ncurses
1997            functions with the incorrect type for bool will cause execution
1998            errors.  In 5.0 we added a configure option "--without-cxx-binding"
1999            which controls whether the binding itself is built and installed.
2000
2001     4.2 (March 2, 1998)
2002         Interface changes:
2003
2004         + correct prototype for termattrs() as per XPG4 version 2.
2005
2006         + add placeholder prototypes for color_set(), erasewchar(),
2007           term_attrs(), wcolor_set() as per XPG4 version 2.
2008
2009         + add macros getcur[xy] getbeg[xy] getpar[xy], which are defined in
2010           SVr4 headers.
2011
2012         New extensions: keyok() and define_key().
2013
2014         Terminfo database changes:
2015
2016         + corrected definition in curses.h for ACS_LANTERN, which was 'I'
2017           rather than 'i'.
2018
2019     4.1 (May 15, 1997)
2020
2021         We added these extensions:  use_default_colors().  Also added
2022         configure option --enable-const, to support the use of const where
2023         X/Open should have, but did not, specify.
2024
2025         The terminfo database content changed the representation of color for
2026         most entries that use ANSI colors.  SVr4 curses treats the setaf/setab
2027         and setf/setb capabilities differently, interchanging the red/blue
2028         colors in the latter.
2029
2030     4.0 (December 24, 1996)
2031
2032         We bumped to version 4.0 because the newly released Linux dynamic
2033         loader (ld.so.1.8.5) did not load shared libraries whose ABI and REL
2034         versions were inconsistent.  At that point, ncurses ABI was 3.4 and the
2035         REL was 1.9.9g, so we made them consistent.
2036
2037     1.9.9g (December 1, 1996)
2038
2039         This fixed most of the problems with 1.9.9e, and made these interface
2040         changes:
2041
2042         + remove tparam(), which had been provided for compatibility with
2043           some termcap.  tparm() is standard, and does not conflict with
2044           application's fallback for missing tparam().
2045
2046         + turn off hardware echo in initscr().  This changes the sense of the
2047           echo() function, which was initialized to echoing rather than
2048           nonechoing (the latter is specified).  There were several other
2049           corrections to the terminal I/O settings which cause applications to
2050           behave differently.
2051
2052         + implemented several functions (such as attr_on()) which were
2053           available only as macros.
2054
2055         + corrected several typos in curses.h.in (i.e., the mvXXXX macros).
2056
2057         + corrected prototypes for delay_output(),
2058           has_color, immedok() and idcok().
2059
2060         + corrected misspelled getbkgd().  Some applications used the
2061           misspelled name.
2062
2063         + added _yoffset to WINDOW.  The size of WINDOW does not impact
2064           applications, since they use only pointers to WINDOW structs.
2065
2066         These changes were made to the terminfo database:
2067
2068         + removed boolean 'getm' which was available as an extended name.
2069
2070         We added these extensions: wresize(), resizeterm(), has_key() and
2071         mcprint().
2072
2073     1.9.9e (March 24, 1996)
2074
2075         not recommended (a last-minute/untested change left the forms and
2076         menus libraries unusable since they do not repaint the screen).
2077         Foreground/background colors are combined incorrectly, working properly
2078         only on a black background.  When this was released, the X/Open
2079         specification was available only in draft form.
2080
2081         Some applications (such as lxdialog) were "fixed" to work with the
2082         incorrect color scheme.
2083
2084
2085 IF YOU ARE A SYSTEM INTEGRATOR:
2086 ------------------------------
2087
2088     Configuration and Installation:
2089
2090         On platforms where ncurses is assumed to be installed in /usr/lib,
2091         the configure script uses "/usr" as a default.  These include any
2092         that use the Linux kernel, as well as these special cases:
2093
2094                 FreeBSD, NetBSD, OpenBSD, Cygwin, MinGW
2095
2096         For other platforms, the default is "/usr/local".  See the discussion
2097         of the "--disable-overwrite" option.
2098
2099         The location of the terminfo is set indirectly by the "--datadir"
2100         configure option, e.g., /usr/share/terminfo, given a datadir of
2101         /usr/share.  You may want to override this if you are installing
2102         ncurses libraries in nonstandard locations, but wish to share the
2103         terminfo database.
2104
2105         Normally the ncurses library is configured in a pure-terminfo mode;
2106         that is, with the --disable-termcap option.  This makes the ncurses
2107         library smaller and faster.  The ncurses library includes a termcap
2108         emulation that queries the terminfo database, so even applications that
2109         use raw termcap to query terminal characteristics will win (providing
2110         you recompile and relink them!).
2111
2112         If you must configure with termcap fallback enabled, you may also wish
2113         to use the --enable-getcap option.  This speeds up termcap-based
2114         startups, at the expense of not allowing personal termcap entries to
2115         reference the terminfo tree.  See comments in
2116         ncurses/tinfo/read_termcap.c for further details.
2117
2118         Note that if you have $TERMCAP set, ncurses will use that value
2119         to locate termcap data.  In particular, running from xterm will
2120         set $TERMCAP to the contents of the xterm's termcap entry.
2121         If ncurses sees that, it will not examine /etc/termcap.
2122
2123     Keyboard Mapping:
2124
2125         The terminfo file assumes that Shift-Tab generates \E[Z (the ECMA-48
2126         reverse-tabulation sequence) rather than ^I.  Here are the loadkeys -d
2127         mappings that will set this up:
2128
2129                 keycode  15 = Tab             Tab
2130                         alt     keycode  15 = Meta_Tab
2131                         shift   keycode  15 = F26
2132                 string F26 ="\033[Z"
2133
2134     Naming the Console Terminal
2135
2136         In various systems there has been a practice of designating the system
2137         console driver type as `console'.  Please do not do this!  It
2138         complicates peoples' lives, because it can mean that several different
2139         terminfo entries from different operating systems all logically want to
2140         be called `console'.
2141
2142         Please pick a name unique to your console driver and set that up
2143         in the /etc/inittab table or local equivalent.  Send the entry to the
2144         terminfo maintainer (listed in the misc/terminfo file) to be included
2145         in the terminfo file, if it's not already there.  See the
2146         term(7) manual page included with this distribution for more on
2147         conventions for choosing type names.
2148
2149         Here are some recommended primary console names:
2150
2151                 linux   -- Linux console driver
2152                 freebsd -- FreeBSD
2153                 netbsd  -- NetBSD
2154                 bsdos   -- BSD/OS
2155
2156         If you are responsible for integrating ncurses for one of these
2157         distributions, please either use the recommended name or get back
2158         to us explaining why you don't want to, so we can work out nomenclature
2159         that will make users' lives easier rather than harder.
2160
2161
2162 RECENT XTERM VERSIONS:
2163 ---------------------
2164
2165         The terminfo database file included with this distribution assumes you
2166         are running a modern xterm based on XFree86 (i.e., xterm-new).  The
2167         earlier X11R6 entry (xterm-r6) and X11R5 entry (xterm-r5) is provided
2168         as well.  See the --without-xterm-new configure script option if you
2169         are unable to update your system.
2170
2171
2172 CONFIGURING FALLBACK ENTRIES:
2173 ----------------------------
2174
2175         In order to support operation of ncurses programs before the terminfo
2176         tree is accessible (that is, in single-user mode or at OS installation
2177         time) the ncurses library can be compiled to include an array of
2178         pre-fetched fallback entries.  This must be done on a machine which
2179         has ncurses' infocmp and terminfo database installed (as well as
2180         ncurses' tic and infocmp programs).
2181
2182         These entries are checked by setupterm() only when the conventional
2183         fetches from the terminfo tree and the termcap fallback (if configured)
2184         have been tried and failed.  Thus, the presence of a fallback will not
2185         shadow modifications to the on-disk entry for the same type, when that
2186         entry is accessible.
2187
2188         By default, there are no entries on the fallback list.  After you have
2189         built the ncurses suite for the first time, you can change the list
2190         (the process needs infocmp(1)).  To do so, use the script
2191         ncurses/tinfo/MKfallback.sh.  The configure script option
2192         --with-fallbacks does this (it accepts a comma-separated list of the
2193         names you wish, and does not require a rebuild).
2194
2195         If you wanted (say) to have linux, vt100, and xterm fallbacks, you
2196         might use the commands
2197
2198                 cd ncurses;
2199                 tinfo/MKfallback.sh \
2200                         $TERMINFO \
2201                         ../misc/terminfo.src \
2202                         `which tic` \
2203                         `which infocmp` \
2204                         linux vt100 xterm >fallback.c
2205
2206         The first four parameters of the script are normally supplied by
2207         the configured makefiles via the "--with-fallbacks" option.  They
2208         are
2209
2210                 1) the location of the terminfo database
2211                 2) the source for the terminfo entries
2212                 3) the location of the tic program, used to create a terminfo
2213                    database.
2214                 4) the location of the infocmp program, used to print a terminfo
2215                    description.
2216
2217         Then just rebuild and reinstall the library as you would normally.
2218         You can restore the default empty fallback list with
2219
2220                 tinfo/MKfallback.sh \
2221                         $TERMINFO \
2222                         ../misc/terminfo.src \
2223                         `which tic` \
2224                         `which infocmp` \
2225                         >fallback.c
2226
2227         The overhead for an empty fallback list is one trivial stub function.
2228         Any non-empty fallback list is const'd and therefore lives in shareable
2229         text space.  You can look at the comment trailing each initializer in
2230         the generated ncurses/fallback.c file to see the core cost of the
2231         fallbacks.  A good rule of thumb for modern vt100-like entries is that
2232         each one will cost about 2.5K of text space.
2233
2234
2235 BSD CONVERSION NOTES:
2236 --------------------
2237
2238         If you need to support really ancient BSD programs, you probably
2239         want to configure with the --enable-bsdpad option.  What this does
2240         is enable code in tputs() that recognizes a numeric prefix on a
2241         capability as a request for that much trailing padding in milliseconds.
2242         There are old BSD programs that do things like tputs("50").
2243
2244         (If you are distributing ncurses as a support-library component of
2245         an application you probably want to put the remainder of this section
2246         in the package README file.)
2247
2248         The following note applies only if you have configured ncurses with
2249         --enable-termcap.
2250
2251 ------------------------------- CUT HERE --------------------------------
2252
2253 If you are installing this application privately (either because you
2254 have no root access or want to experiment with it before doing a root
2255 installation), there are a couple of details you need to be aware of.
2256 They have to do with the ncurses library, which uses terminfo rather
2257 than termcap for describing terminal characteristics.
2258
2259 Though the ncurses library is terminfo-based, it can interpret your
2260 TERMCAP variable (if present), any local termcap files you reference
2261 through it, and the system termcap file.  However, to avoid slowing
2262 down your application startup, it does this only once per terminal type!
2263
2264 The first time you load a given terminal type from your termcap
2265 database, the library initialization code will automatically write it
2266 in terminfo format to a subdirectory under $HOME/.terminfo.  After
2267 that, the initialization code will find it there and do a (much
2268 faster) terminfo fetch.
2269
2270 Usually, all this means is that your home directory will silently grow
2271 an invisible .terminfo subdirectory which will get filled in with
2272 terminfo descriptions of terminal types as you invoke them.  If anyone
2273 ever installs a global terminfo tree on your system, this will quietly
2274 stop happening and your $HOME/.terminfo will become redundant.
2275
2276 The objective of all this logic is to make converting from BSD termcap
2277 as painless as possible without slowing down your application (termcap
2278 compilation is expensive).
2279
2280 If you don't have a TERMCAP variable or custom personal termcap file,
2281 you can skip the rest of this dissertation.
2282
2283 If you *do* have a TERMCAP variable and/or a custom personal termcap file
2284 that defines a terminal type, that definition will stop being visible
2285 to this application after the first time you run it, because it will
2286 instead see the terminfo entry that it wrote to $HOME/terminfo the
2287 first time around.
2288
2289 Subsequently, editing the TERMCAP variable or personal TERMCAP file
2290 will have no effect unless you explicitly remove the terminfo entry
2291 under $HOME/terminfo.  If you do that, the entry will be recompiled
2292 from your termcap resources the next time it is invoked.
2293
2294 To avoid these complications, use infocmp(1) and tic(1) to edit the
2295 terminfo directory directly.
2296
2297 ------------------------------- CUT HERE --------------------------------
2298
2299 USING NCURSES WITH AFS:
2300         AFS treats each directory as a separate logical filesystem, you
2301         can't hard-link across them.  The --enable-symlinks option copes
2302         with this by making tic use symbolic links.
2303
2304 USING NCURSES WITH GPM:
2305         Ncurses 4.1 and up can be configured to use GPM (General Purpose Mouse)
2306         which is used with Linux console.  Be aware that GPM is commonly
2307         installed as a shared library which contains a wrapper for the curses
2308         wgetch() function (libcurses.o).  Some integrators have simplified
2309         linking applications by combining all or part of libcurses.so into the
2310         libgpm.so file, producing symbol conflicts with ncurses (specifically
2311         the wgetch function).  This was originally the BSD curses, but
2312         generally whatever curses library exists on the system.
2313
2314         You may be able to work around this problem by linking as follows:
2315
2316                 cc -o foo foo.o -lncurses -lgpm -lncurses
2317
2318         but the linker may not cooperate, producing mysterious errors.
2319         See the FAQ, as well as the discussion under the --with-gpm option:
2320
2321         https://invisible-island.net/ncurses/ncurses.faq.html#using_gpm_lib
2322
2323 BUILDING NCURSES WITH A CROSS-COMPILER
2324         Ncurses can be built with a cross-compiler.  Some parts must be built
2325         with the host's compiler since they are used for building programs
2326         (e.g., ncurses/make_hash and ncurses/make_keys) that generate tables
2327         that are compiled into the ncurses library.  The essential thing to do
2328         is set the BUILD_CC environment variable to your host's compiler, and
2329         run the configure script configuring for the cross-compiler.
2330
2331         The configure options --with-build-cc, etc., are provided to make this
2332         simpler.  Since make_hash and make_keys use only ANSI C features, it
2333         is normally not necessary to provide the other options such as
2334         --with-build-libs, but they are provided for completeness.
2335
2336         Note that all of the generated source-files which are part of ncurses
2337         will be made if you use
2338
2339                 make sources
2340
2341         This would be useful in porting to an environment which has little
2342         support for the tools used to generate the sources, e.g., sed, awk and
2343         Bourne-shell.
2344
2345         When ncurses has been successfully cross-compiled, you may want to use
2346         "make install" (with a suitable target directory) to construct an
2347         install tree.  Note that in this case (as with the --with-fallbacks
2348         option), ncurses uses the development platform's tic to do the
2349         "make install.data" portion.
2350
2351         The system's tic program is used to install the terminal database,
2352         even for cross-compiles.  For best results, the tic program should
2353         be from the most current version of ncurses.
2354
2355 BUGS:
2356         Send any feedback to the ncurses mailing list at
2357         bug-ncurses@gnu.org. To subscribe send mail to
2358         bug-ncurses-request@gnu.org with body that reads:
2359         subscribe ncurses <your-email-address-here>
2360
2361         The Hacker's Guide in the doc directory includes some guidelines
2362         on how to report bugs in ways that will get them fixed most quickly.
2363
2364 -- vile:txtmode