INSTALL revision 178866
1------------------------------------------------------------------------------- 2-- Copyright (c) 1998-2005,2006 Free Software Foundation, Inc. -- 3-- -- 4-- Permission is hereby granted, free of charge, to any person obtaining a -- 5-- copy of this software and associated documentation files (the -- 6-- "Software"), to deal in the Software without restriction, including -- 7-- without limitation the rights to use, copy, modify, merge, publish, -- 8-- distribute, distribute with modifications, sublicense, and/or sell copies -- 9-- of the Software, and to permit persons to whom the Software is furnished -- 10-- to do so, subject to the following conditions: -- 11-- -- 12-- The above copyright notice and this permission notice shall be included -- 13-- in all copies or substantial portions of the Software. -- 14-- -- 15-- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS -- 16-- OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF -- 17-- MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN -- 18-- NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, -- 19-- DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR -- 20-- OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE -- 21-- USE OR OTHER DEALINGS IN THE SOFTWARE. -- 22-- -- 23-- Except as contained in this notice, the name(s) of the above copyright -- 24-- holders shall not be used in advertising or otherwise to promote the -- 25-- sale, use or other dealings in this Software without prior written -- 26-- authorization. -- 27------------------------------------------------------------------------------- 28-- $Id: INSTALL,v 1.124 2008/03/29 18:07:32 tom Exp $ 29--------------------------------------------------------------------- 30 How to install Ncurses/Terminfo on your system 31--------------------------------------------------------------------- 32 33 ************************************************************ 34 * READ ALL OF THIS FILE BEFORE YOU TRY TO INSTALL NCURSES. * 35 ************************************************************ 36 37You should be reading the file INSTALL in a directory called ncurses-d.d, where 38d.d is the current version number. There should be several subdirectories, 39including `c++', `form', `man', `menu', 'misc', `ncurses', `panel', `progs', 40and `test'. See the README file for a roadmap to the package. 41 42If you are a Linux or FreeBSD or NetBSD distribution integrator or packager, 43please read and act on the section titled IF YOU ARE A SYSTEM INTEGRATOR 44below. 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 running over the Andrew File System see the note below on 53USING NCURSES WITH AFS. 54 55If you are cross-compiling, see the note below on BUILDING NCURSES WITH A 56CROSS-COMPILER. 57 58If you want to build the Ada95 binding, go to the Ada95 directory and 59follow the instructions there. The Ada95 binding is not covered below. 60 61If you are using anything but (a) Linux, or (b) one of the 4.4BSD-based 62i386 Unixes, go read the Portability section in the TO-DO file before you 63do anything else. 64 65 66REQUIREMENTS: 67------------ 68 69You will need the following to build and install ncurses under UNIX: 70 71 * ANSI C compiler (gcc, for instance) 72 * sh (bash will do) 73 * awk (mawk or gawk will do) 74 * sed 75 * BSD or System V style install (a script is enclosed) 76 77Ncurses has been also built in the OS/2 EMX environment. 78 79 80INSTALLATION PROCEDURE: 81---------------------- 82 831. First, decide whether you want ncurses to replace your existing library (in 84 which case you'll need super-user privileges) or be installed in parallel 85 with it. 86 87 The --prefix option to configure changes the root directory for installing 88 ncurses. The default is normally in subdirectories of /usr/local, except 89 for systems where ncurses is normally installed as a system library, e.g., 90 Linux, the various BSD systems and Cygwin. Use --prefix=/usr to replace 91 your default curses distribution. 92 93 The package gets installed beneath the --prefix directory as follows: 94 95 In $(prefix)/bin: tic, infocmp, captoinfo, tset, 96 reset, clear, tput, toe 97 In $(prefix)/lib: libncurses*.* libcurses.a 98 In $(prefix)/share/terminfo: compiled terminal descriptions 99 In $(prefix)/include: C header files 100 Under $(prefix)/man: the manual pages 101 102 Note that the configure script attempts to locate previous installation of 103 ncurses, and will set the default prefix according to where it finds the 104 ncurses headers. 105 106 Do not use commands such as 107 108 make install prefix=XXX 109 110 to change the prefix after configuration, since the prefix value is used 111 for some absolute pathnames such as TERMINFO. Instead do this 112 113 make install DESTDIR=XXX 114 115 See also the discussion of --with-install-prefix. 116 1172. Type `./configure' in the top-level directory of the distribution to 118 configure ncurses for your operating system and create the Makefiles. 119 Besides --prefix, various configuration options are available to customize 120 the installation; use `./configure --help' to list the available options. 121 122 If your operating system is not supported, read the PORTABILITY section in 123 the file ncurses/README for information on how to create a configuration 124 file for your system. 125 126 The `configure' script generates makefile rules for one or more object 127 models and their associated libraries: 128 129 libncurses.a (normal) 130 131 libcurses.a (normal, a link to libncurses.a) 132 This gets left out if you configure with --disable-overwrite. 133 134 libncurses.so (shared) 135 136 libncurses_g.a (debug) 137 138 libncurses_p.a (profile) 139 140 libncurses.la (libtool) 141 142 If you configure using the --enable-widec option, a "w" is appended to the 143 library names (e.g., libncursesw.a), and the resulting libraries support 144 wide-characters, e.g., via a UTF-8 locale. The corresponding header files 145 are compatible with the non-wide-character configuration; wide-character 146 features are provided by ifdef's in the header files. The wide-character 147 library interfaces are not binary-compatible with the non-wide-character 148 version. Building and running the wide-character code relies on a fairly 149 recent implementation of libiconv. We have built this configuration on 150 Linux using libiconv, sometimes requiring libutf8. 151 152 If you configure using the --with-pthread option, a "t" is appended to 153 the library names (e.g., libncursest.a, libncursestw.a). 154 155 If you do not specify any models, the normal and debug libraries will be 156 configured. Typing `configure' with no arguments is equivalent to: 157 158 ./configure --with-normal --with-debug --enable-overwrite 159 160 Typing 161 162 ./configure --with-shared 163 164 makes the shared libraries the default, resulting in 165 166 ./configure --with-shared --with-normal --with-debug --enable-overwrite 167 168 If you want only shared libraries, type 169 170 ./configure --with-shared --without-normal --without-debug 171 172 Rules for generating shared libraries are highly dependent upon the choice 173 of host system and compiler. We've been testing shared libraries on Linux 174 and SunOS with gcc, but more work needs to be done to make shared libraries 175 work on other systems. 176 177 If you have libtool installed, you can type 178 179 ./configure --with-libtool 180 181 to generate the appropriate static and/or shared libraries for your 182 platform using libtool. 183 184 You can make curses and terminfo fall back to an existing file of termcap 185 definitions by configuring with --enable-termcap. If you do this, the 186 library will search /etc/termcap before the terminfo database, and will 187 also interpret the contents of the TERM environment variable. See the 188 section BSD CONVERSION NOTES below. 189 1903. Type `make'. Ignore any warnings, no error messages should be produced. 191 This should compile the ncurses library, the terminfo compiler tic(1), 192 captoinfo(1), infocmp(1), toe(1), clear(1) tset(1), reset(1), and tput(1) 193 programs (see the manual pages for explanation of what they do), some test 194 programs, and the panels, menus, and forms libraries. 195 1964. Run ncurses and several other test programs in the test directory to 197 verify that ncurses functions correctly before doing an install that 198 may overwrite system files. Read the file test/README for details on 199 the test programs. 200 201 NOTE: You must have installed the terminfo database, or set the 202 environment variable $TERMINFO to point to a SVr4-compatible terminfo 203 database before running the test programs. Not all vendors' terminfo 204 databases are SVr4-compatible, but most seem to be. Exceptions include 205 DEC's Digital Unix (formerly known as OSF/1). 206 207 If you run the test programs WITHOUT installing terminfo, ncurses may 208 read the termcap file and cache that in $HOME/.terminfo, which will 209 thereafter be used instead of the terminfo database. See the comments 210 on "--enable-getcap-cache", to see why this is a Bad Thing. 211 212 It is possible to configure ncurses to use other terminfo database formats. 213 A few are provided as examples in the include-directory (see --with-caps). 214 215 The ncurses program is designed specifically to test the ncurses library. 216 You can use it to verify that the screen highlights work correctly, that 217 cursor addressing and window scrolling works OK, etc. 218 2195. Once you've tested, you can type `make install' to install libraries, 220 the programs, the terminfo database and the manual pages. Alternately, you 221 can type `make install' in each directory you want to install. In the 222 top-level directory, you can do a partial install using these commands: 223 224 'make install.progs' installs tic, infocmp, etc... 225 'make install.includes' installs the headers. 226 'make install.libs' installs the libraries (and the headers). 227 'make install.data' installs the terminfo data. (Note: `tic' must 228 be installed before the terminfo data can be 229 compiled). 230 'make install.man' installs the manual pages. 231 232 ############################################################################ 233 # CAVEAT EMPTOR: `install.data' run as root will NUKE any existing # 234 # terminfo database. If you have any custom or unusual entries SAVE them # 235 # before you install ncurses. I have a file called terminfo.custom for # 236 # this purpose. Don't forget to run tic on the file once you're done. # 237 ############################################################################ 238 239 The terminfo(5) manual page must be preprocessed with tbl(1) before 240 being formatted by nroff(1). Modern man(1) implementations tend to do 241 this by default, but you may want to look at your version's manual page 242 to be sure. You may also install the manual pages after preprocessing 243 with tbl(1) by specifying the configure option --with-manpage-tbl. 244 245 If the system already has a curses library that you need to keep using 246 you'll need to distinguish between it and ncurses. See the discussion of 247 --disable-overwrite. If ncurses is installed outside the standard 248 directories (/usr/include and /usr/lib) then all your users will need to 249 use the -I option to compile programs and -L to link them. 250 251 If you have another curses installed in your system and you accidentally 252 compile using its curses.h you'll end up with a large number of 253 undefined symbols at link time. 254 255 IF YOU DO NOT HAVE ROOT: Change directory to the `progs' subdirectory 256 and run the `capconvert' script. This script will deduce various things 257 about your environment and use them to build you a private terminfo tree, 258 so you can use ncurses applications. 259 260 If more than one user at your site does this, the space for the duplicate 261 trees is wasted. Try to get your site administrators to install a system- 262 wide terminfo tree instead. 263 264 See the BSD CONVERSION NOTES section below for a few more details. 265 2666. The c++ directory has C++ classes that are built on top of ncurses and 267 panels. You must have c++ (and its libraries) installed before you can 268 compile and run the demo. 269 270 Use --without-cxx-binding to tell configure to not build the C++ bindings 271 and demo. 272 273 If you do not have C++, you must use the --without-cxx option to tell 274 the configure script to not attempt to determine the type of 'bool' 275 which may be supported by C++. IF YOU USE THIS OPTION, BE ADVISED THAT 276 YOU MAY NOT BE ABLE TO COMPILE (OR RUN) NCURSES APPLICATIONS WITH C++. 277 278 279SUMMARY OF CONFIGURE OPTIONS: 280---------------------------- 281 282 The configure script provides a short list of its options when you type 283 284 ./configure --help 285 286 The --help and several options are common to all configure scripts that are 287 generated with autoconf. Those are all listed before the line 288 289 --enable and --with options recognized: 290 291 The other options are specific to this package. We list them in alphabetic 292 order. 293 294 --disable-assumed-color 295 With ncurses 5.1, we introduced a new function, assume_default_colors() 296 which allows applications to specify what the default foreground and 297 background color are assumed to be. Most color applications use 298 full-screen color; but a few do not color the background. While the 299 assumed values can be overridden by invoking assume_default_colors(), 300 you may find it useful to set the assumed values to the pre-5.1 301 convention, using this configure option. 302 303 --disable-big-core 304 Assume machine has little memory. The configure script attempts to 305 determine if your machine has enough memory (about 6Mb) to compile the 306 terminfo database without writing portions to disk. Some allocators 307 return deceptive results, so you may have to override the configure 308 script. Or you may be building tic for a smaller machine. 309 310 --disable-big-strings 311 Disable compile-time optimization of predefined tables which puts 312 all of their strings into a very long string, to reduce relocation 313 overhead. 314 315 --disable-database 316 Use only built-in data. The ncurses libraries normally read terminfo 317 and termcap data from disk. You can configure ncurses to have a 318 built-in database, aka "fallback" entries. Embedded applications may 319 have no need for an external database. Some, but not all of the 320 programs are useful in this configuration, e.g., reset and tput versus 321 infocmp and tic. 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-hashmap 329 Compile without hashmap scrolling-optimization code. This algorithm is 330 the default. 331 332 --disable-home-terminfo 333 The $HOME/.terminfo directory is normally added to ncurses' search 334 list for reading/writing terminfo entries, since that directory is 335 more likely writable than the system terminfo database. Use this 336 option to disable the feature altogether. 337 338 --disable-largefile 339 Disable compiler flags needed to use large-file interfaces. 340 341 --disable-leaks 342 For testing, compile-in code that frees memory that normally would not 343 be freed, to simplify analysis of memory-leaks. 344 345 Any implementation of curses must not free the memory associated with 346 a screen, since (even after calling endwin()), it must be available 347 for use in the next call to refresh(). There are also chunks of 348 memory held for performance reasons. That makes it hard to analyze 349 curses applications for memory leaks. To work around this, build 350 a debugging version of the ncurses library which frees those chunks 351 which it can, and provides the _nc_free_and_exit() function to free 352 the remainder on exit. The ncurses utility and test programs use this 353 feature, e.g., via the ExitProgram() macro. 354 355 --disable-lp64 356 The header files will ignore use of the _LP64 symbol to make chtype 357 and mmask_t types 32 bits (they may be long on 64-bit hosts, for 358 compatibility with older releases). 359 360 NOTE: this is potentially an ABI change, depending on existing 361 packages. The default for this option is "disabled" for ncurses 362 ABI 5, and "enabled" for ABI 6. 363 364 --disable-macros 365 For testing, use functions rather than macros. The program will run 366 more slowly, but it is simpler to debug. This defines NCURSES_NOMACROS 367 at build time. See also the --enable-expanded option. 368 369 --disable-overwrite 370 If you are installing ncurses on a system which contains another 371 development version of curses, or which could be confused by the loader 372 for another version, we recommend that you leave out the link to 373 -lcurses. The ncurses library is always available as -lncurses. 374 Disabling overwrite also causes the ncurses header files to be 375 installed into a subdirectory, e.g., /usr/local/include/ncurses, 376 rather than the include directory. This makes it simpler to avoid 377 compile-time conflicts with other versions of curses.h 378 379 --disable-relink 380 If --enable-rpath is given, the generated makefiles normally will 381 rebuild the libraries during install. Use this option to simply 382 copy whatever the linked produced. 383 384 This option is ignored if --enable-rpath is not given. 385 386 --disable-root-environ 387 Compile with environment restriction, so certain environment variables 388 are not available when running as root, or via a setuid/setgid 389 application. These are (for example $TERMINFO) those that allow the 390 search path for the terminfo or termcap entry to be customized. 391 392 --disable-scroll-hints 393 Compile without scroll-hints code. This option is ignored when 394 hashmap scrolling is configured, which is the default. 395 396 --disable-tparm-varargs 397 Portable programs should call tparm() using the fixed-length parameter 398 list documented in X/Open. ncurses provides varargs support for this 399 function. Use --disable-tparm-varargs to disable this support. 400 401 --enable-assertions 402 For testing, compile-in assertion code. This is used only for a few 403 places where ncurses cannot easily recover by returning an error code. 404 405 --enable-broken_linker 406 A few platforms have what we consider a broken linker: it cannot link 407 objects from an archive solely by referring to data objects in those 408 files, but requires a function reference. This configure option 409 changes several data references to functions to work around this 410 problem. 411 412 NOTE: With ncurses 5.1, this may not be necessary, since we are 413 told that some linkers interpret uninitialized global data as a 414 different type of reference which behaves as described above. We have 415 explicitly initialized all of the global data to work around the 416 problem. 417 418 --enable-bsdpad 419 Recognize BSD-style prefix padding. Some ancient BSD programs (such as 420 nethack) call tputs("50") to implement delays. 421 422 --enable-colorfgbg 423 Compile with experimental $COLORFGBG code. That environment variable 424 is set by some terminal emulators as a hint to applications, by 425 advertising the default foreground and background colors. During 426 initialization, ncurses sets color pair 0 to match this. 427 428 --enable-const 429 The curses interface as documented in XSI is rather old, in fact 430 including features that precede ANSI C. The prototypes generally do 431 not make effective use of "const". When using stricter compilers (or 432 gcc with appropriate warnings), you may see warnings about the mismatch 433 between const and non-const data. We provide a configure option which 434 changes the interfaces to use const - quieting these warnings and 435 reflecting the actual use of the parameters more closely. The ncurses 436 library uses the symbol NCURSES_CONST for these instances of const, 437 and if you have asked for compiler warnings, will add gcc's const-qual 438 warning. There will still be warnings due to subtle inconsistencies 439 in the interface, but at a lower level. 440 441 NOTE: configuring ncurses with this option may detract from the 442 portability of your applications by encouraging you to use const in 443 places where the XSI curses interface would not allow them. Similar 444 issues arise when porting to SVr4 curses, which uses const in even 445 fewer places. 446 447 --enable-echo 448 Use the option --disable-echo to make the build-log less verbose by 449 suppressing the display of the compile and link commands. This makes 450 it easier to see the compiler warnings. (You can always use "make -n" 451 to see the options that are used). 452 453 --enable-expanded 454 For testing, generate functions for certain macros to make them visible 455 as such to the debugger. See also the --disable-macros option. 456 457 --enable-ext-colors 458 Extend the cchar_t structure to allow more than 16 colors to be 459 encoded. This applies only to the wide-character (--enable-widec) 460 configuration. 461 462 NOTE: using this option will make libraries which are not binary- 463 compatible with libncursesw 5.4. None of the interfaces change, but 464 applications which have an array of cchar_t's must be recompiled. 465 466 --enable-ext-mouse 467 Modify the encoding of mouse state to make room for a 5th mouse button. 468 That allows one to use ncurses with a wheel mouse with xterm or 469 similar X terminal emulators. 470 471 NOTE: using this option will make libraries which are not binary- 472 compatible with libncursesw 5.4. None of the interfaces change, but 473 applications which have mouse mask mmask_t's must be recompiled. 474 475 --enable-getcap 476 Use the 4.4BSD getcap code if available, or a bundled version of it to 477 fetch termcap entries. Entries read in this way cannot use (make 478 cross-references to) the terminfo tree, but it is faster than reading 479 /etc/termcap. 480 481 If configured for one of the *BSD systems, this automatically uses 482 the hashed database system produced using cap_mkdb or similar tools. 483 In that case, there is no advantage in using the --enable-getcap-cache 484 option. 485 486 See also the --with-hashed-db option. 487 488 --enable-getcap-cache 489 Cache translated termcaps under the directory $HOME/.terminfo 490 491 NOTE: this sounds good - it makes ncurses run faster the second time. 492 But look where the data comes from - an /etc/termcap containing lots of 493 entries that are not up to date. If you configure with this option and 494 forget to install the terminfo database before running an ncurses 495 application, you will end up with a hidden terminfo database that 496 generally does not support color and will miss some function keys. 497 498 --enable-hard-tabs 499 Compile-in cursor-optimization code that uses hard-tabs. We would make 500 this a standard feature except for the concern that the terminfo entry 501 may not be accurate, or that your stty settings have disabled the use 502 of tabs. 503 504 --enable-mixed-case 505 Controls whether the filesystem on which the terminfo database resides 506 supports mixed-case filenames (normal for UNIX, but not on other 507 systems). If you do not specify this option, the configure script 508 checks the current filesystem. 509 510 --enable-no-padding 511 Compile-in support for the $NCURSES_NO_PADDING environment variable, 512 which allows you to suppress the effect of non-mandatory padding in 513 terminfo entries. This is the default, unless you have disabled the 514 extended functions. 515 516 --enable-reentrant 517 Compile experimental configuration which improves reentrant use of the 518 library by reducing global and static variables. This option is also 519 set if --with-pthread is used. 520 521 --enable-rpath 522 Use rpath option when generating shared libraries, and (with some 523 restrictions) when linking the corresponding programs. This originally 524 (in 1997) applied mainly to systems using the GNU linker (read the 525 manpage). 526 527 More recently it is useful for systems that require special treatment 528 shared libraries in "unusual" locations. The "system" libraries reside 529 in directories which are on the loader's default search-path. While 530 you may be able to use workarounds such as the $LD_LIBRARY_PATH 531 environment variable, they do not work with setuid applications since 532 the LD_LIBRARY_PATH variable would be unset in that situation. 533 534 This option does not apply to --with-libtool, since libtool makes 535 extra assumptions about rpath. 536 537 --enable-safe-sprintf 538 Compile with experimental safe-sprintf code. You may consider using 539 this if you are building ncurses for a system that has neither 540 vsnprintf() or vsprintf(). It is slow, however. 541 542 --enable-sigwinch 543 Compile support for ncurses' SIGWINCH handler. If your application has 544 its own SIGWINCH handler, ncurses will not use its own. The ncurses 545 handler causes wgetch() to return KEY_RESIZE when the screen-size 546 changes. This option is the default, unless you have disabled the 547 extended functions. 548 549 --enable-signed-char 550 The term.h header declares a Booleans[] array typed "char". But it 551 stores signed values there and "char" is not necessarily signed. 552 Some packagers choose to alter the type of Booleans[] though this 553 is not strictly compatible. This option allows one to implement this 554 alteration without patching the source code. 555 556 --enable-symlinks 557 If your system supports symbolic links, make tic use symbolic links 558 rather than hard links to save diskspace when writing aliases in the 559 terminfo database. 560 561 --enable-tcap-names 562 Compile-in support for user-definable terminal capabilities. Use the 563 -x option of tic and infocmp to treat unrecognized terminal 564 capabilities as user-defined strings. This option is the default, 565 unless you have disabled the extended functions. 566 567 --enable-termcap 568 Compile in support for reading terminal descriptions from termcap if no 569 match is found in the terminfo database. See also the --enable-getcap 570 and --enable-getcap-cache options. 571 572 --enable-warnings 573 Turn on GCC compiler warnings. There should be only a few. 574 575 --enable-wgetch-events 576 Compile with experimental wgetch-events code. See ncurses/README.IZ 577 578 --enable-widec 579 Compile with wide-character code. This makes a different version of 580 the libraries (e.g., libncursesw.so), which stores characters as 581 wide-characters, 582 583 NOTE: applications compiled with this configuration are not compatible 584 with those built for 8-bit characters. You cannot simply make a 585 symbolic link to equate libncurses.so with libncursesw.so 586 587 NOTE: the Ada95 binding may be built against either version of the the 588 ncurses library, but you must decide which: the binding installs the 589 same set of files for either version. Currently (2002/6/22) it does 590 not use the extended features from the wide-character code, so it is 591 probably better to not install the binding for that configuration. 592 593 --enable-xmc-glitch 594 Compile-in support experimental xmc (magic cookie) code. 595 596 --with-abi-version=NUM 597 Override the ABI version, which is used in shared library filenames. 598 Normally this is the same as the release version; some ports have 599 special requirements for compatibility. 600 601 --with-ada-compiler=CMD 602 Specify the Ada95 compiler command (default "gnatmake") 603 604 --with-ada-include=DIR 605 Tell where to install the Ada includes (default: 606 PREFIX/lib/ada/adainclude) 607 608 --with-ada-objects=DIR 609 Tell where to install the Ada objects (default: PREFIX/lib/ada/adalib) 610 611 --with-bool=TYPE 612 If --without-cxx is specified, override the type used for the "bool" 613 declared in curses.h (normally the type is automatically chosen to 614 correspond with that in <stdbool.h>, or defaults to platform-specific 615 sizes). 616 617 --with-build-cc=XXX 618 If cross-compiling, specify a host C compiler, which is needed to 619 compile a few utilities which generate source modules for ncurses. 620 If you do not give this option, the configure script checks if the 621 $BUILD_CC variable is set, and otherwise defaults to gcc or cc. 622 623 --with-build-cflags=XXX 624 If cross-compiling, specify the host C compiler-flags. You might need 625 to do this if the target compiler has unusual flags which confuse the 626 host compiler. 627 628 --with-build-cppflags=XXX 629 If cross-compiling, specify the host C preprocessor-flags. You might 630 need to do this if the target compiler has unusual flags which confuse 631 the host compiler. 632 633 --with-build-ldflags=XXX 634 If cross-compiling, specify the host linker-flags. You might need to 635 do this if the target linker has unusual flags which confuse the host 636 compiler. 637 638 --with-build-libs=XXX 639 If cross-compiling, the host libraries. You might need to do this if 640 the target environment requires unusual libraries. 641 642 --with-caps=XXX 643 Specify an alternate terminfo capabilities file, which makes the 644 configure script look for "include/Caps.XXX". A few systems, e.g., 645 AIX 4.x use the same overall file-format as ncurses for terminfo 646 data, but use different alignments within the tables to support 647 legacy applications. For those systems, you can configure ncurses 648 to use a terminfo database which is compatible with the native 649 applications. 650 651 --with-chtype=TYPE 652 Override type of chtype, which stores the video attributes and (if 653 --enable-widec is not given) a character. Prior to ncurses 5.5, this 654 was always unsigned long, but with ncurses 5.5, it may be unsigned. 655 Use this option if you need to preserve compatibility with 64-bit 656 executables. 657 658 --with-database=XXX 659 Specify the terminfo source file to install. Usually you will wish 660 to install ncurses' default (misc/terminfo.src). Certain systems 661 have special requirements, e.g, OS/2 EMX has a customized terminfo 662 source file. 663 664 --with-dbmalloc 665 For testing, compile and link with Conor Cahill's dbmalloc library. 666 This also sets the --disable-leaks option. 667 668 --with-debug 669 Generate debug-libraries (default). These are named by adding "_g" 670 to the root, e.g., libncurses_g.a 671 672 --with-default-terminfo-dir=XXX 673 Specify the default terminfo database directory. This is normally 674 DATADIR/terminfo, e.g., /usr/share/terminfo. 675 676 --with-dmalloc 677 For testing, compile and link with Gray Watson's dmalloc library. 678 This also sets the --disable-leaks option. 679 680 --with-fallbacks=XXX 681 Specify a list of fallback terminal descriptions which will be 682 compiled into the ncurses library. See CONFIGURING FALLBACK ENTRIES. 683 684 --with-gpm 685 use Alessandro Rubini's GPM library to provide mouse support on the 686 Linux console. Prior to ncurses 5.5, this introduced a dependency on 687 the GPM library. 688 689 Currently ncurses uses the dlsym() function to bind to the library at 690 runtime, so it is only necessary that the library be present when 691 ncurses is built, to obtain the filename (or soname) used in the 692 corresponding dlopen() call. If you give a value for this option, 693 e.g., 694 695 --with-gpm=$HOME/tmp/test-gpm.so 696 697 that overrides the configure check for the soname. 698 699 See also --without-dlsym 700 701 --with-hashed-db[=XXX] 702 Use a hashed database for storing terminfo data rather than storing 703 each compiled entry in a separate binary file within a directory 704 tree. 705 706 In particular, this uses the Berkeley database 1.8.5 interface, as 707 provided by that and its successors db 2, 3, and 4. The actual 708 interface is slightly different in the successor versions of the 709 Berkeley database. The database should have been configured using 710 "--enable-compat185". 711 712 If you use this option for configuring ncurses, tic will only be able 713 to write entries in the hashed database. infocmp can still read 714 entries from a directory tree as well as reading entries from the 715 hashed database. To do this, infocmp determines whether the $TERMINFO 716 variable points to a directory or a file, and reads the directory-tree 717 or hashed database respectively. 718 719 You cannot have a directory containing both hashed-database and 720 filesystem-based terminfo entries. 721 722 Use the parameter value to give the install-prefix used for the 723 datbase, e.g., 724 --with-hashed-db=/usr/local/BigBase 725 to find the corresponding include- and lib-directories under the 726 given directory. 727 728 See also the --enable-getcap option. 729 730 --with-install-prefix=XXX 731 Allows you to specify an alternate location for installing ncurses 732 after building it. The value you specify is prepended to the "real" 733 install location. This simplifies making binary packages. The 734 makefile variable DESTDIR is set by this option. It is also possible 735 to use 736 make install DESTDIR=XXX 737 since the makefiles pass that variable to subordinate makes. 738 739 NOTE: a few systems build shared libraries with fixed pathnames; this 740 option probably will not work for those configurations. 741 742 --with-libtool[=XXX] 743 Generate libraries with libtool. If this option is selected, then it 744 overrides all other library model specifications. Note that libtool 745 must already be installed, uses makefile rules dependent on GNU make, 746 and does not promise to follow the version numbering convention of 747 other shared libraries on your system. However, if the --with-shared 748 option does not succeed, you may get better results with this option. 749 750 If a parameter value is given, it must be the full pathname of the 751 particular version of libtool, e.g., 752 /usr/bin/libtool-1.2.3 753 754 It is possible to rebuild the configure script to use the automake 755 macros for libtool, e.g., AC_PROG_LIBTOOL. See the comments in 756 aclocal.m4 for CF_PROG_LIBTOOL, and ensure that you build configure 757 using the appropriate patch for autoconf from 758 http://invisible-island.net/autoconf/ 759 760 --with-manpage-aliases 761 Tell the configure script you wish to create entries in the 762 man-directory for aliases to manpages which list them, e.g., the 763 functions in the panel manpage. This is the default. You can disable 764 it if your man program does this. You can also disable 765 --with-manpage-symlinks to install files containing a ".so" command 766 rather than symbolic links. 767 768 --with-manpage-format=XXX 769 Tell the configure script how you would like to install man-pages. The 770 option value must be one of these: gzip, compress, BSDI, normal, 771 formatted. If you do not give this option, the configure script 772 attempts to determine which is the case. 773 774 --with-manpage-renames=XXX 775 Tell the configure script that you wish to rename the manpages while 776 installing. Currently the only distribution which does this is 777 the Linux Debian. The option value specifies the name of a file 778 that lists the renamed files, e.g., $srcdir/man/man_db.renames 779 780 --with-manpage-symlinks 781 Tell the configure script that you wish to make symbolic links in the 782 man-directory for aliases to the man-pages. This is the default, but 783 can be disabled for systems that provide this automatically. Doing 784 this on systems that do not support symbolic links will result in 785 copying the man-page for each alias. 786 787 --with-manpage-tbl 788 Tell the configure script that you with to preprocess the manpages 789 by running them through tbl to generate tables understandable by 790 nroff. 791 792 --with-mmask-t=TYPE 793 Override type of mmask_t, which stores the mouse mask. Prior to 794 ncurses 5.5, this was always unsigned long, but with ncurses 5.5, it 795 may be unsigned. Use this option if you need to preserve compatibility 796 with 64-bit executables. 797 798 --with-ospeed=TYPE 799 Override type of ospeed variable, which is part of the termcap 800 compatibility interface. In termcap, this is a 'short', which works 801 for a wide range of baudrates because ospeed is not the actual speed 802 but the encoded value, e.g., B9600 would be a small number such as 13. 803 However the encoding scheme originally allowed for values "only" up to 804 38400bd. A newer set of definitions past 38400bd is not encoded as 805 compactly, and is not guaranteed to fit into a short (see the function 806 cfgetospeed(), which returns a speed_t for this reason). In practice, 807 applications that required knowledge of the ospeed variable, i.e., 808 those using termcap, do not use the higher speeds. Your application 809 (or system, in general) may or may not. 810 811 --with-normal 812 Generate normal (i.e., static) libraries (default). 813 814 Note: on Linux, the configure script will attempt to use the GPM 815 library via the dlsym() function call. Use --without-dlsym to disable 816 this feature, or --without-gpm, depending on whether you wish to use 817 GPM. 818 819 --with-profile 820 Generate profile-libraries These are named by adding "_p" to the root, 821 e.g., libncurses_p.a 822 823 --with-pthread 824 Link with POSIX threads, set --enable-reentrant. The use_window() and 825 use_screen() functions will use mutex's, allowing rudimentary support 826 for multithreaded applications. 827 828 --with-rcs-ids 829 Compile-in RCS identifiers. Most of the C files have an identifier. 830 831 --with-rel-version=NUM 832 Override the release version, which may be used in shared library 833 filenames. This consists of a major and minor version number separated 834 by ".". Normally the major version number is the same as the ABI 835 version; some ports have special requirements for compatibility. 836 837 --with-shared 838 Generate shared-libraries. The names given depend on the system for 839 which you are building, typically using a ".so" suffix, along with 840 symbolic links that refer to the release version. 841 842 NOTE: Unless you override the configure script by setting the $CFLAGS 843 environment variable, these will not be built with the -g debugging 844 option. 845 846 NOTE: For some configurations, e.g., installing a new version of 847 ncurses shared libraries on a machine which already has ncurses 848 shared libraries, you may encounter problems with the linker. 849 For example, it may prevent you from running the build tree's 850 copy of tic (for installing the terminfo database) because it 851 loads the system's copy of the ncurses shared libraries. In that 852 case, using the misc/shlib script may be helpful, since it sets 853 $LD_LIBRARY_PATH to point to the build tree, e.g., 854 ./misc/shlib make install 855 856 --with-shlib-version=XXX 857 Specify whether to use the release or ABI version for shared libraries. 858 This is normally chosen automatically based on the type of system 859 which you are building on. We use it for testing the configure script. 860 861 --with-sysmouse 862 use FreeBSD sysmouse interface provide mouse support on the console. 863 864 --with-system-type=XXX 865 For testing, override the derived host system-type which is used to 866 decide things such as the linker commands used to build shared 867 libraries. This is normally chosen automatically based on the type of 868 system which you are building on. We use it for testing the configure 869 script. 870 871 --with-terminfo-dirs=XXX 872 Specify a search-list of terminfo directories which will be compiled 873 into the ncurses library (default: DATADIR/terminfo) 874 875 --with-termlib[=XXX] 876 When building the ncurses library, organize this as two parts: the 877 curses library (libncurses) and the low-level terminfo library 878 (libtinfo). This is done to accommodate applications that use only 879 the latter. The terminfo library is about half the size of the total. 880 881 If an option value is given, that overrides the name of the terminfo 882 library. For instance, if the wide-character version is built, the 883 terminfo library would be named libtinfow. But the libtinfow interface 884 is upward compatible from libtinfo, so it would be possible to overlay 885 libtinfo.so with a "wide" version of libtinfow.so by renaming it with 886 this option. 887 888 --with-termpath=XXX 889 Specify a search-list of termcap files which will be compiled into the 890 ncurses library (default: /etc/termcap:/usr/share/misc/termcap) 891 892 --with-ticlib[=XXX] 893 When building the ncurses library, build a separate library for 894 the modules that are used only by the utility programs. Normally 895 those would be bundled with the termlib or ncurses libraries. 896 897 If an option value is given, that overrides the name of the tic 898 library. As in termlib, there is no ABI difference between the 899 "wide" libticw.so and libtic.so 900 901 --with-trace 902 Configure the trace() function as part of the all models of the ncurses 903 library. Normally it is part of the debug (libncurses_g) library only. 904 905 --with-valgrind 906 For testing, compile with debug option. 907 This also sets the --disable-leaks option. 908 909 --without-ada 910 Suppress the configure script's check for Ada95, do not build the 911 Ada95 binding and related demo. 912 913 --without-curses-h 914 Don't install the ncurses header with the name "curses.h". Rather, 915 install as "ncurses.h" and modify the installed headers and manpages 916 accordingly. 917 918 --without-cxx 919 XSI curses declares "bool" as part of the interface. C++ also declares 920 "bool". Neither specifies the size and type of booleans, but both 921 insist on the same name. We chose to accommodate this by making the 922 configure script check for the size and type (e.g., unsigned or signed) 923 that your C++ compiler uses for booleans. If you do not wish to use 924 ncurses with C++, use this option to tell the configure script to not 925 adjust ncurses bool to match C++. 926 927 --without-cxx-binding 928 Suppress the configure script's check for C++, do not build the 929 C++ binding and related demo. 930 931 --without-develop 932 Disable development options. This does not include those that change 933 the interface, such as --enable-widec. 934 935 --without-dlsym 936 Do not use dlsym() to load GPM dynamically. 937 938 --without-progs 939 Tell the configure script to suppress the build of ncurses' application 940 programs (e.g., tic). The test applications will still be built if you 941 type "make", though not if you simply do "make install". 942 943 --without-xterm-new 944 Tell the configure script to use "xterm-old" for the entry used in 945 the terminfo database. This will work with variations such as 946 X11R5 and X11R6 xterm. 947 948 949COMPATIBILITY WITH OLDER VERSIONS OF NCURSES: 950-------------------------------------------- 951 952 Because ncurses implements the X/Open Curses Specification, its interface 953 is fairly stable. That does not mean the interface does not change. 954 Changes are made to the documented interfaces when we find differences 955 between ncurses and X/Open or implementations which they certify (such as 956 Solaris). We add extensions to those interfaces to solve problems not 957 addressed by the original curses design, but those must not conflict with 958 the X/Open documentation. 959 960 Here are some of the major interface changes, and related problems which 961 you may encounter when building a system with different versions of 962 ncurses: 963 964 5.6 (December 17, 2006) 965 Interface changes: 966 967 + generate linkable stubs for some macros: 968 969 getbegx, getbegy, getcurx, getcury, getmaxx, getmaxy, getparx, 970 getpary, getpary, 971 972 and (for libncursesw) 973 974 wgetbkgrnd 975 976 Added extensions: 977 nofilter() 978 use_legacy_coding() 979 980 Added internal functions: 981 _nc_first_db 982 _nc_get_source 983 _nc_handle_sigwinch 984 _nc_is_abs_path 985 _nc_is_dir_path 986 _nc_is_file_path 987 _nc_keep_tic_dir 988 _nc_keep_tic_dir 989 _nc_last_db 990 _nc_next_db 991 _nc_read_termtype 992 _nc_tic_dir 993 994 Also (if using the hashed database configuration): 995 996 _nc_db_close 997 _nc_db_first 998 _nc_db_get 999 _nc_db_have_data 1000 _nc_db_have_index 1001 _nc_db_next 1002 _nc_db_open 1003 _nc_db_put 1004 1005 otherwise 1006 1007 _nc_hashed_db 1008 1009 Removed internal functions: 1010 none 1011 1012 Modified internal functions: 1013 _nc_add_to_try 1014 _nc_do_color 1015 _nc_expand_try 1016 _nc_remove_key 1017 _nc_setupscreen 1018 1019 5.5 (October 10, 2005) 1020 Interface changes: 1021 1022 + terminfo installs "xterm-new" as "xterm" entry rather than 1023 "xterm-old" (aka xterm-r6). 1024 1025 + terminfo data is installed using the tic -x option (few systems 1026 still use ncurses 4.2). 1027 1028 + modify C++ binding to work with newer C++ compilers by providing 1029 initializers and using modern casts. Old-style header names are 1030 still used in this release to allow compiling with not-so-old 1031 compilers. 1032 1033 + form and menu libraries now work with wide-character data. 1034 Applications which bypassed the form library and manipulated the 1035 FIELD.buf data directly will not work properly with libformw, since 1036 that no longer points to an array of char. The set_field_buffer() 1037 and field_buffer() functions translate to/from the actual field 1038 data. 1039 1040 + change SP->_current_attr to a pointer, adjust ifdef's to ensure that 1041 libtinfo.so and libtinfow.so have the same ABI. The reason for this 1042 is that the corresponding data which belongs to the upper-level 1043 ncurses library has a different size in each model. 1044 1045 + winnstr() now returns multibyte character strings for the 1046 wide-character configuration. 1047 1048 + assume_default_colors() no longer requires that use_default_colors() 1049 be called first. 1050 1051 + data_ahead() now works with wide-characters. 1052 1053 + slk_set() and slk_wset() now accept and store multibyte or 1054 multicolumn characters. 1055 1056 + start_color() now returns OK if colors have already been started. 1057 start_color() also returns ERR if it cannot allocate memory. 1058 1059 + pair_content() now returns -1 for consistency with init_pair() if it 1060 corresponds to the default-color. 1061 1062 + unctrl() now returns null if its parameter does not correspond 1063 to an unsigned char. 1064 1065 Added extensions: 1066 Experimental mouse version 2 supports wheel mice with buttons 1067 4 and 5. This requires ABI 6 because it modifies the encoding 1068 of mouse events. 1069 1070 Experimental extended colors allows encoding of 256 foreground 1071 and background colors, e.g., with the xterm-256color or 1072 xterm-88color terminfo entries. This requires ABI 6 because 1073 it changes the size of cchar_t. 1074 1075 Added internal functions: 1076 _nc_check_termtype2 1077 _nc_resolve_uses2 1078 _nc_retrace_cptr 1079 _nc_retrace_cvoid_ptr 1080 _nc_retrace_void_ptr 1081 _nc_setup_term 1082 1083 Removed internal functions: 1084 none 1085 1086 Modified internal functions: 1087 _nc_insert_ch 1088 _nc_save_str 1089 _nc_trans_string 1090 1091 5.4 (February 8, 2004) 1092 Interface changes: 1093 1094 + add the remaining functions for X/Open curses wide-character support. 1095 These are only available if the library is configured using the 1096 --enable-widec option. 1097 pecho_wchar() 1098 slk_wset() 1099 1100 + write getyx() and related 2-return macros in terms of getcury(), 1101 getcurx(), etc. 1102 1103 + simplify ifdef for bool declaration in curses.h 1104 1105 + modify ifdef's in curses.h that disabled use of __attribute__() for 1106 g++, since recent versions implement the cases which ncurses uses. 1107 1108 + change some interfaces to use const: 1109 define_key() 1110 mvprintw() 1111 mvwprintw() 1112 printw() 1113 vw_printw() 1114 winsnstr() 1115 wprintw() 1116 1117 Added extensions: 1118 key_defined() 1119 1120 Added internal functions: 1121 _nc_get_locale() 1122 _nc_insert_ch() 1123 _nc_is_charable() wide 1124 _nc_locale_breaks_acs() 1125 _nc_pathlast() 1126 _nc_to_char() wide 1127 _nc_to_widechar() wide 1128 _nc_tparm_analyze() 1129 _nc_trace_bufcat() debug 1130 _nc_unicode_locale() 1131 1132 Removed internal functions: 1133 _nc_outstr() 1134 _nc_sigaction() 1135 1136 Modified internal functions: 1137 _nc_remove_string() 1138 _nc_retrace_chtype() 1139 1140 5.3 (October 12, 2002) 1141 Interface changes: 1142 1143 + change type for bool used in headers to NCURSES_BOOL, which usually 1144 is the same as the compiler's definition for 'bool'. 1145 1146 + add all but two functions for X/Open curses wide-character support. 1147 These are only available if the library is configured using the 1148 --enable-widec option. Missing functions are 1149 pecho_wchar() 1150 slk_wset() 1151 1152 + add environment variable $NCURSES_ASSUMED_COLORS to modify the 1153 assume_default_colors() extension. 1154 1155 Added extensions: 1156 is_term_resized() 1157 resize_term() 1158 1159 Added internal functions: 1160 _nc_altcharset_name() debug 1161 _nc_reset_colors() 1162 _nc_retrace_bool() debug 1163 _nc_retrace_unsigned() debug 1164 _nc_rootname() 1165 _nc_trace_ttymode() debug 1166 _nc_varargs() debug 1167 _nc_visbufn() debug 1168 _nc_wgetch() 1169 1170 Removed internal functions: 1171 _nc_background() 1172 1173 Modified internal functions: 1174 _nc_freeall() debug 1175 1176 5.2 (October 21, 2000) 1177 Interface changes: 1178 1179 + revert termcap ospeed variable to 'short' (see discussion of the 1180 --with-ospeed configure option). 1181 1182 5.1 (July 8, 2000) 1183 Interface changes: 1184 1185 + made the extended terminal capabilities 1186 (configure --enable-tcap-names) a standard feature. This should 1187 be transparent to applications that do not require it. 1188 1189 + removed the trace() function and related trace support from the 1190 production library. 1191 1192 + modified curses.h.in, undef'ing some symbols to avoid conflict 1193 with C++ STL. 1194 1195 Added extensions: assume_default_colors(). 1196 1197 5.0 (October 23, 1999) 1198 Interface changes: 1199 1200 + implemented the wcolor_set() and slk_color() functions. 1201 1202 + move macro winch to a function, to hide details of struct ldat 1203 1204 + corrected prototypes for slk_* functions, using chtype rather than 1205 attr_t. 1206 1207 + the slk_attr_{set,off,on} functions need an additional void* 1208 parameter according to XSI. 1209 1210 + modified several prototypes to correspond with 1997 version of X/Open 1211 Curses: [w]attr_get(), [w]attr_set(), border_set() have different 1212 parameters. Some functions were renamed or misspelled: 1213 erase_wchar(), in_wchntr(), mvin_wchntr(). Some developers have used 1214 attr_get(). 1215 1216 Added extensions: keybound(), curses_version(). 1217 1218 Terminfo database changes: 1219 1220 + change translation for termcap 'rs' to terminfo 'rs2', which is 1221 the documented equivalent, rather than 'rs1'. 1222 1223 The problems are subtler in recent releases. 1224 1225 a) This release provides users with the ability to define their own 1226 terminal capability extensions, like termcap. To accomplish this, 1227 we redesigned the TERMTYPE struct (in term.h). Very few 1228 applications use this struct. They must be recompiled to work with 1229 the 5.0 library. 1230 1231 a) If you use the extended terminfo names (i.e., you used configure 1232 --enable-tcap-names), the resulting terminfo database can have some 1233 entries which are not readable by older versions of ncurses. This 1234 is a bug in the older versions: 1235 1236 + the terminfo database stores booleans, numbers and strings in 1237 arrays. The capabilities that are listed in the arrays are 1238 specified by X/Open. ncurses recognizes a number of obsolete and 1239 extended names which are stored past the end of the specified 1240 entries. 1241 1242 + a change to read_entry.c in 951001 made the library do an lseek() 1243 call incorrectly skipping data which is already read from the 1244 string array. This happens when the number of strings in the 1245 terminfo data file is greater than STRCOUNT, the number of 1246 specified and obsolete or extended strings. 1247 1248 + as part of alignment with the X/Open final specification, in the 1249 990109 patch we added two new terminfo capabilities: 1250 set_a_attributes and set_pglen_inch). This makes the indices for 1251 the obsolete and extended capabilities shift up by 2. 1252 1253 + the last two capabilities in the obsolete/extended list are memu 1254 and meml, which are found in most terminfo descriptions for xterm. 1255 1256 When trying to read this terminfo entry, the spurious lseek() 1257 causes the library to attempt to read the final portion of the 1258 terminfo data (the text of the string capabilities) 4 characters 1259 past its starting point, and reads 4 characters too few. The 1260 library rejects the data, and applications are unable to 1261 initialize that terminal type. 1262 1263 FIX: remove memu and meml from the xterm description. They are 1264 obsolete, not used by ncurses. (It appears that the feature was 1265 added to xterm to make it more like hpterm). 1266 1267 This is not a problem if you do not use the -x option of tic to 1268 create a terminfo database with extended names. Note that the 1269 user-defined terminal capabilities are not affected by this bug, 1270 since they are stored in a table after the older terminfo data ends, 1271 and are invisible to the older libraries. 1272 1273 c) Some developers did not wish to use the C++ binding, and used the 1274 configure --without-cxx option. This causes problems if someone 1275 uses the ncurses library from C++ because that configure test 1276 determines the type for C++'s bool and makes ncurses match it, since 1277 both C++ and curses are specified to declare bool. Calling ncurses 1278 functions with the incorrect type for bool will cause execution 1279 errors. In 5.0 we added a configure option "--without-cxx-binding" 1280 which controls whether the binding itself is built and installed. 1281 1282 4.2 (March 2, 1998) 1283 Interface changes: 1284 1285 + correct prototype for termattrs() as per XPG4 version 2. 1286 1287 + add placeholder prototypes for color_set(), erasewchar(), 1288 term_attrs(), wcolor_set() as per XPG4 version 2. 1289 1290 + add macros getcur[xy] getbeg[xy] getpar[xy], which are defined in 1291 SVr4 headers. 1292 1293 New extensions: keyok() and define_key(). 1294 1295 Terminfo database changes: 1296 1297 + corrected definition in curses.h for ACS_LANTERN, which was 'I' 1298 rather than 'i'. 1299 1300 4.1 (May 15, 1997) 1301 1302 We added these extensions: use_default_colors(). Also added 1303 configure option --enable-const, to support the use of const where 1304 X/Open should have, but did not, specify. 1305 1306 The terminfo database content changed the representation of color for 1307 most entries that use ANSI colors. SVr4 curses treats the setaf/setab 1308 and setf/setb capabilities differently, interchanging the red/blue 1309 colors in the latter. 1310 1311 4.0 (December 24, 1996) 1312 1313 We bumped to version 4.0 because the newly released dynamic loader 1314 (ld.so.1.8.5) on Linux did not load shared libraries whose ABI and REL 1315 versions were inconsistent. At that point, ncurses ABI was 3.4 and the 1316 REL was 1.9.9g, so we made them consistent. 1317 1318 1.9.9g (December 1, 1996) 1319 1320 This fixed most of the problems with 1.9.9e, and made these interface 1321 changes: 1322 1323 + remove tparam(), which had been provided for compatibility with 1324 some termcap. tparm() is standard, and does not conflict with 1325 application's fallback for missing tparam(). 1326 1327 + turn off hardware echo in initscr(). This changes the sense of the 1328 echo() function, which was initialized to echoing rather than 1329 nonechoing (the latter is specified). There were several other 1330 corrections to the terminal I/O settings which cause applications to 1331 behave differently. 1332 1333 + implemented several functions (such as attr_on()) which were 1334 available only as macros. 1335 1336 + corrected several typos in curses.h.in (i.e., the mvXXXX macros). 1337 1338 + corrected prototypes for delay_output(), 1339 has_color, immedok() and idcok(). 1340 1341 + corrected misspelled getbkgd(). Some applications used the 1342 misspelled name. 1343 1344 + added _yoffset to WINDOW. The size of WINDOW does not impact 1345 applications, since they use only pointers to WINDOW structs. 1346 1347 These changes were made to the terminfo database: 1348 1349 + removed boolean 'getm' which was available as an extended name. 1350 1351 We added these extensions: wresize(), resizeterm(), has_key() and 1352 mcprint(). 1353 1354 1.9.9e (March 24, 1996) 1355 1356 not recommended (a last-minute/untested change left the forms and 1357 menus libraries unusable since they do not repaint the screen). 1358 Foreground/background colors are combined incorrectly, working properly 1359 only on a black background. When this was released, the X/Open 1360 specification was available only in draft form. 1361 1362 Some applications (such as lxdialog) were "fixed" to work with the 1363 incorrect color scheme. 1364 1365 1366IF YOU ARE A SYSTEM INTEGRATOR: 1367------------------------------ 1368 1369 Configuration and Installation: 1370 1371 On platforms where ncurses is assumed to be installed in /usr/lib, 1372 the configure script uses "/usr" as a default: 1373 1374 Linux, FreeBSD, NetBSD, OpenBSD, Cygwin 1375 1376 For other platforms, the default is "/usr/local". See the discussion 1377 of the "--disable-overwrite" option. 1378 1379 The location of the terminfo is set indirectly by the "--datadir" 1380 configure option, e.g., /usr/share/terminfo, given a datadir of 1381 /usr/share. You may want to override this if you are installing 1382 ncurses libraries in nonstandard locations, but wish to share the 1383 terminfo database. 1384 1385 Normally the ncurses library is configured in a pure-terminfo mode; 1386 that is, with the --disable-termcap option. This makes the ncurses 1387 library smaller and faster. The ncurses library includes a termcap 1388 emulation that queries the terminfo database, so even applications that 1389 use raw termcap to query terminal characteristics will win (providing 1390 you recompile and relink them!). 1391 1392 If you must configure with termcap fallback enabled, you may also wish 1393 to use the --enable-getcap option. This speeds up termcap-based 1394 startups, at the expense of not allowing personal termcap entries to 1395 reference the terminfo tree. See comments in 1396 ncurses/tinfo/read_termcap.c for further details. 1397 1398 Note that if you have $TERMCAP set, ncurses will use that value 1399 to locate termcap data. In particular, running from xterm will 1400 set $TERMCAP to the contents of the xterm's termcap entry. 1401 If ncurses sees that, it will not examine /etc/termcap. 1402 1403 Keyboard Mapping: 1404 1405 The terminfo file assumes that Shift-Tab generates \E[Z (the ECMA-48 1406 reverse-tabulation sequence) rather than ^I. Here are the loadkeys -d 1407 mappings that will set this up: 1408 1409 keycode 15 = Tab Tab 1410 alt keycode 15 = Meta_Tab 1411 shift keycode 15 = F26 1412 string F26 ="\033[Z" 1413 1414 Naming the Console Terminal 1415 1416 In various systems there has been a practice of designating the system 1417 console driver type as `console'. Please do not do this! It 1418 complicates peoples' lives, because it can mean that several different 1419 terminfo entries from different operating systems all logically want to 1420 be called `console'. 1421 1422 Please pick a name unique to your console driver and set that up 1423 in the /etc/inittab table or local equivalent. Send the entry to the 1424 terminfo maintainer (listed in the misc/terminfo file) to be included 1425 in the terminfo file, if it's not already there. See the 1426 term(7) manual page included with this distribution for more on 1427 conventions for choosing type names. 1428 1429 Here are some recommended primary console names: 1430 1431 linux -- Linux console driver 1432 freebsd -- FreeBSD 1433 netbsd -- NetBSD 1434 bsdos -- BSD/OS 1435 1436 If you are responsible for integrating ncurses for one of these 1437 distribution, please either use the recommended name or get back 1438 to us explaining why you don't want to, so we can work out nomenclature 1439 that will make users' lives easier rather than harder. 1440 1441 1442RECENT XTERM VERSIONS: 1443--------------------- 1444 1445 The terminfo database file included with this distribution assumes you 1446 are running a modern xterm based on XFree86 (i.e., xterm-new). The 1447 earlier X11R6 entry (xterm-r6) and X11R5 entry (xterm-r5) is provided 1448 as well. See the --without-xterm-new configure script option if you 1449 are unable to update your system. 1450 1451 1452CONFIGURING FALLBACK ENTRIES: 1453---------------------------- 1454 1455 In order to support operation of ncurses programs before the terminfo 1456 tree is accessible (that is, in single-user mode or at OS installation 1457 time) the ncurses library can be compiled to include an array of 1458 pre-fetched fallback entries. This must be done on a machine which 1459 has ncurses' infocmp and terminfo database installed. 1460 1461 These entries are checked by setupterm() only when the conventional 1462 fetches from the terminfo tree and the termcap fallback (if configured) 1463 have been tried and failed. Thus, the presence of a fallback will not 1464 shadow modifications to the on-disk entry for the same type, when that 1465 entry is accessible. 1466 1467 By default, there are no entries on the fallback list. After you have 1468 built the ncurses suite for the first time, you can change the list 1469 (the process needs infocmp(1)). To do so, use the script 1470 ncurses/tinfo/MKfallback.sh. A configure script option 1471 --with-fallbacks does this (it accepts a comma-separated list of the 1472 names you wish, and does not require a rebuild). 1473 1474 If you wanted (say) to have linux, vt100, and xterm fallbacks, you 1475 would use the commands 1476 1477 cd ncurses; 1478 tinfo/MKfallback.sh linux vt100 xterm >fallback.c 1479 1480 Then just rebuild and reinstall the library as you would normally. 1481 You can restore the default empty fallback list with 1482 1483 tinfo/MKfallback.sh >fallback.c 1484 1485 The overhead for an empty fallback list is one trivial stub function. 1486 Any non-empty fallback list is const-ed and therefore lives in sharable 1487 text space. You can look at the comment trailing each initializer in 1488 the generated ncurses/fallback.c file to see the core cost of the 1489 fallbacks. A good rule of thumb for modern vt100-like entries is that 1490 each one will cost about 2.5K of text space. 1491 1492 1493BSD CONVERSION NOTES: 1494-------------------- 1495 1496 If you need to support really ancient BSD programs, you probably 1497 want to configure with the --enable-bsdpad option. What this does 1498 is enable code in tputs() that recognizes a numeric prefix on a 1499 capability as a request for that much trailing padding in milliseconds. 1500 There are old BSD programs that do things like tputs("50"). 1501 1502 (If you are distributing ncurses as a support-library component of 1503 an application you probably want to put the remainder of this section 1504 in the package README file.) 1505 1506 The following note applies only if you have configured ncurses with 1507 --enable-termcap. 1508 1509------------------------------- CUT HERE -------------------------------- 1510 1511If you are installing this application privately (either because you 1512have no root access or want to experiment with it before doing a root 1513installation), there are a couple of details you need to be aware of. 1514They have to do with the ncurses library, which uses terminfo rather 1515than termcap for describing terminal characteristics. 1516 1517Though the ncurses library is terminfo-based, it will interpret your 1518TERMCAP variable (if present), any local termcap files you reference 1519through it, and the system termcap file. However, in order to avoid 1520slowing down your application startup, it will only do this once per 1521terminal type! 1522 1523The first time you load a given terminal type from your termcap 1524database, the library initialization code will automatically write it 1525in terminfo format to a subdirectory under $HOME/.terminfo. After 1526that, the initialization code will find it there and do a (much 1527faster) terminfo fetch. 1528 1529Usually, all this means is that your home directory will silently grow 1530an invisible .terminfo subdirectory which will get filled in with 1531terminfo descriptions of terminal types as you invoke them. If anyone 1532ever installs a global terminfo tree on your system, this will quietly 1533stop happening and your $HOME/.terminfo will become redundant. 1534 1535The objective of all this logic is to make converting from BSD termcap 1536as painless as possible without slowing down your application (termcap 1537compilation is expensive). 1538 1539If you don't have a TERMCAP variable or custom personal termcap file, 1540you can skip the rest of this dissertation. 1541 1542If you *do* have a TERMCAP variable and/or a custom personal termcap file 1543that defines a terminal type, that definition will stop being visible 1544to this application after the first time you run it, because it will 1545instead see the terminfo entry that it wrote to $HOME/terminfo the 1546first time around. 1547 1548Subsequently, editing the TERMCAP variable or personal TERMCAP file 1549will have no effect unless you explicitly remove the terminfo entry 1550under $HOME/terminfo. If you do that, the entry will be recompiled 1551from your termcap resources the next time it is invoked. 1552 1553To avoid these complications, use infocmp(1) and tic(1) to edit the 1554terminfo directory directly. 1555 1556------------------------------- CUT HERE -------------------------------- 1557 1558USING NCURSES WITH AFS: 1559 AFS treats each directory as a separate logical filesystem, you 1560 can't hard-link across them. The --enable-symlinks option copes 1561 with this by making tic use symbolic links. 1562 1563USING NCURSES WITH GPM: 1564 Ncurses 4.1 and up can be configured to use GPM (General Purpose 1565 Mouse) which is used on Linux console. Be aware that GPM is commonly 1566 installed as a shared library which contains a wrapper for the curses 1567 wgetch() function (libcurses.o). Some integrators have simplified 1568 linking applications by combining all or part of libcurses.so into the 1569 libgpm.so file, producing symbol conflicts with ncurses (specifically 1570 the wgetch function). This was originally the BSD curses, but 1571 generally whatever curses library exists on the system. 1572 1573 You may be able to work around this problem by linking as follows: 1574 1575 cc -o foo foo.o -lncurses -lgpm -lncurses 1576 1577 but the linker may not cooperate, producing mysterious errors. 1578 See the FAQ, as well as the discussion under the --with-gpm option: 1579 1580 http://invisible-island.net/ncurses/ncurses.faq.html#using_gpm_lib 1581 1582BUILDING NCURSES WITH A CROSS-COMPILER 1583 Ncurses can be built with a cross-compiler. Some parts must be built 1584 with the host's compiler since they are used for building programs 1585 (e.g., ncurses/make_hash and ncurses/make_keys) that generate tables 1586 that are compiled into the ncurses library. The essential thing to do 1587 is set the BUILD_CC environment variable to your host's compiler, and 1588 run the configure script configuring for the cross-compiler. 1589 1590 The configure options --with-build-cc, etc., are provided to make this 1591 simpler. Since make_hash and make_keys use only ANSI C features, it 1592 is normally not necessary to provide the other options such as 1593 --with-build-libs, but they are provided for completeness. 1594 1595 Note that all of the generated source-files which are part of ncurses 1596 will be made if you use 1597 1598 make sources 1599 1600 This would be useful in porting to an environment which has little 1601 support for the tools used to generate the sources, e.g., sed, awk and 1602 Bourne-shell. 1603 1604 When ncurses has been successfully cross-compiled, you may want to use 1605 "make install" (with a suitable target directory) to construct an 1606 install tree. Note that in this case (as with the --with-fallbacks 1607 option), ncurses uses the development platform's tic to do the 1608 "make install.data" portion. 1609 1610BUGS: 1611 Send any feedback to the ncurses mailing list at 1612 bug-ncurses@gnu.org. To subscribe send mail to 1613 bug-ncurses-request@gnu.org with body that reads: 1614 subscribe ncurses <your-email-address-here> 1615 1616 The Hacker's Guide in the doc directory includes some guidelines 1617 on how to report bugs in ways that will get them fixed most quickly. 1618 1619-- vile:txtmode 1620