Debian Codegraph @

INSTALL

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