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