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