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