ncurses 5.3
[ncurses.git] / INSTALL
1 -- $Id: INSTALL,v 1.56 2002/09/01 22:42:11 tom Exp $
2 ---------------------------------------------------------------------
3              How to install Ncurses/Terminfo on your system
4 ---------------------------------------------------------------------
5
6     ************************************************************
7     * READ ALL OF THIS FILE BEFORE YOU TRY TO INSTALL NCURSES. *
8     ************************************************************
9
10 You should be reading the file INSTALL in a directory called ncurses-d.d, where
11 d.d is the current version number.  There should be several subdirectories,
12 including `c++', `form', `man', `menu', 'misc', `ncurses', `panel', `progs',
13 and `test'.  See the README file for a roadmap to the package.
14
15 If you are a Linux or FreeBSD or NetBSD distribution integrator or packager,
16 please read and act on the section titled IF YOU ARE A SYSTEM INTEGRATOR
17 below.
18
19 If you are converting from BSD curses and do not have root access, be sure
20 to read the BSD CONVERSION NOTES section below.
21
22 If you are using a version of XFree86 xterm older than 3.1.2F, see the section
23 on RECENT XTERM VERSIONS below.
24
25 If you are trying to build GNU Emacs using ncurses for terminal support,
26 read the USING NCURSES WITH EMACS section below.
27
28 If you are trying to build applications using gpm with ncurses,
29 read the USING NCURSES WITH GPM section below.
30
31 If you are running over the Andrew File System see the note below on
32 USING NCURSES WITH AFS.
33
34 If you are cross-compiling, see the note below on BUILDING NCURSES WITH A
35 CROSS-COMPILER.
36
37 If you want to build the Ada95 binding, go to the Ada95 directory and
38 follow the instructions there.  The Ada95 binding is not covered below.
39
40 If you are using anything but (a) Linux, or (b) one of the 4.4BSD-based
41 i386 Unixes, go read the Portability section in the TO-DO file before you
42 do anything else.
43
44
45 REQUIREMENTS:
46 ------------
47
48 You will need the following in order to build and install ncurses under UNIX:
49
50         * ANSI C compiler  (gcc, for instance)
51         * sh               (bash will do)
52         * awk              (mawk or gawk will do)
53         * sed
54         * BSD or System V style install (a script is enclosed)
55
56 Ncurses has been also built in the OS/2 EMX environment.
57
58
59 INSTALLATION PROCEDURE:
60 ----------------------
61
62 1.  First, decide whether you want ncurses to replace your existing library (in
63     which case you'll need super-user privileges) or be installed in parallel
64     with it.
65
66     The --prefix option to configure changes the root directory for installing
67     ncurses.  The default is in subdirectories of /usr/local.  Use
68     --prefix=/usr to replace your default curses distribution.  This is the
69     default for Linux and BSD/OS users.
70
71     The package gets installed beneath the --prefix directory as follows:
72
73     In $(prefix)/bin:          tic, infocmp, captoinfo, tset,
74                                 reset, clear, tput, toe
75     In $(prefix)/lib:          libncurses*.* libcurses.a
76     In $(prefix)/share/terminfo: compiled terminal descriptions
77     In $(prefix)/include:      C header files
78     Under $(prefix)/man:       the manual pages
79
80     Note however that the configure script attempts to locate previous
81     installation of ncurses, and will set the default prefix according to where
82     it finds the ncurses headers.
83
84 2.  Type `./configure' in the top-level directory of the distribution to
85     configure ncurses for your operating system and create the Makefiles.
86     Besides --prefix, various configuration options are available to customize
87     the installation; use `./configure --help' to list the available options.
88
89     If your operating system is not supported, read the PORTABILITY section in
90     the file ncurses/README for information on how to create a configuration
91     file for your system.
92
93     The `configure' script generates makefile rules for one or more object
94     models and their associated libraries:
95
96         libncurses.a (normal)
97
98         libcurses.a (normal, a link to libncurses.a)
99                 This gets left out if you configure with --disable-overwrite.
100
101         libncurses.so (shared)
102
103         libncurses_g.a (debug)
104
105         libncurses_p.a (profile)
106
107         libncurses.la (libtool)
108
109     If you configure using the --enable-widec option, a "w" is appended to the
110     library names (e.g., libncursesw.a), and the resulting libraries support
111     wide-characters, e.g., via a UTF-8 locale.  The corresponding header files
112     are compatible with the non-wide-character configuration; wide-character
113     features are provided by ifdef's in the header files.  The wide-character
114     library interfaces are not binary-compatible with the non-wide-character
115     version.  Building and running the wide-character code relies on a fairly
116     recent implementation of libiconv.  We have built this configuration on
117     Linux using libiconv, sometimes requiring libutf8.
118
119     If you do not specify any models, the normal and debug libraries will be
120     configured.  Typing `configure' with no arguments is equivalent to:
121
122         ./configure --with-normal --with-debug --enable-overwrite
123
124     Typing
125
126         ./configure --with-shared
127
128     makes the shared libraries the default, resulting in
129
130         ./configure --with-shared --with-normal --with-debug --enable-overwrite
131
132     If you want only shared libraries, type
133
134         ./configure --with-shared --without-normal --without-debug
135
136     Rules for generating shared libraries are highly dependent upon the choice
137     of host system and compiler.  We've been testing shared libraries on Linux
138     and SunOS with gcc, but more work needs to be done to make shared libraries
139     work on other systems.
140
141     If you have libtool installed, you can type
142
143         ./configure --with-libtool
144
145     to generate the appropriate static and/or shared libraries for your
146     platform using libtool.
147
148     You can make curses and terminfo fall back to an existing file of termcap
149     definitions by configuring with --enable-termcap.  If you do this, the
150     library will search /etc/termcap before the terminfo database, and will
151     also interpret the contents of the TERM environment variable.  See the
152     section BSD CONVERSION NOTES below.
153
154 3.  Type `make'.  Ignore any warnings, no error messages should be produced.
155     This should compile the ncurses library, the terminfo compiler tic(1),
156     captoinfo(1), infocmp(1), toe(1), clear(1) tset(1), reset(1), and tput(1)
157     programs (see the manual pages for explanation of what they do), some test
158     programs, and the panels, menus, and forms libraries.
159
160 4.  Run ncurses and several other test programs in the test directory to
161     verify that ncurses functions correctly before doing an install that
162     may overwrite system files.  Read the file test/README for details on
163     the test programs.
164
165     NOTE: You must have installed the terminfo database, or set the
166     environment variable $TERMINFO to point to a SVr4-compatible terminfo
167     database before running the test programs.  Not all vendors' terminfo
168     databases are SVr4-compatible, but most seem to be.  Exceptions include
169     DEC's Digital Unix (formerly known as OSF/1).
170
171     It is possible to configure ncurses to use other terminfo database formats.
172     A few are provided as examples in the include-directory (see --with-caps).
173
174     The ncurses program is designed specifically to test the ncurses library.
175     You can use it to verify that the screen highlights work correctly, that
176     cursor addressing and window scrolling works OK, etc.
177
178 5.  Once you've tested, you can type `make install' to install libraries,
179     the programs, the terminfo database and the manual pages.  Alternately, you
180     can type `make install' in each directory you want to install.  In the
181     top-level directory, you can do a partial install using these commands:
182
183         'make install.progs'    installs tic, infocmp, etc...
184         'make install.includes' installs the headers.
185         'make install.libs'     installs the libraries (and the headers).
186         'make install.data'     installs the terminfo data. (Note: `tic' must
187                                 be installed before the terminfo data can be
188                                 compiled).
189         'make install.man'      installs the manual pages.
190
191   ############################################################################
192   #     CAVEAT EMPTOR: `install.data' run as root will NUKE any existing     #
193   #  terminfo database. If you have any custom or unusual entries SAVE them  #
194   #  before you install ncurses.  I have a file called terminfo.custom for   #
195   #  this purpose.  Don't forget to run tic on the file once you're done.    #
196   ############################################################################
197
198     The terminfo(5) manual page must be preprocessed with tbl(1) before
199     being formatted by nroff(1).  Modern man(1) implementations tend to do
200     this by default, but you may want to look at your version's manual page
201     to be sure.  You may also install the manual pages after preprocessing
202     with tbl(1) by specifying the configure option --with-manpage-tbl.
203
204     If the system already has a curses library that you need to keep using
205     you'll need to distinguish between it and ncurses.  See the discussion of
206     --disable-overwrite.  If ncurses is installed outside the standard
207     directories (/usr/include and /usr/lib) then all your users will need to
208     use the -I option to compile programs and -L to link them.
209
210     If you have another curses installed in your system and you accidentally
211     compile using its curses.h you'll end up with a large number of
212     undefined symbols at link time.
213
214     IF YOU DO NOT HAVE ROOT: Change directory to the `progs' subdirectory
215     and run the `capconvert' script.  This script will deduce various things
216     about your environment and use them to build you a private terminfo tree,
217     so you can use ncurses applications.
218
219     If more than one user at your site does this, the space for the duplicate
220     trees is wasted.  Try to get your site administrators to install a system-
221     wide terminfo tree instead.
222
223     See the BSD CONVERSION NOTES section below for a few more details.
224
225 6.  The c++ directory has C++ classes that are built on top of ncurses and
226     panels.  You must have c++ (and its libraries) installed before you can
227     compile and run the demo.
228
229     Use --without-cxx-binding to tell configure to not build the C++ bindings
230     and demo.
231
232     If you do not have C++, you must use the --without-cxx option to tell
233     the configure script to not attempt to determine the type of 'bool'
234     which may be supported by C++.  IF YOU USE THIS OPTION, BE ADVISED THAT
235     YOU MAY NOT BE ABLE TO COMPILE (OR RUN) NCURSES APPLICATIONS WITH C++.
236
237
238 SUMMARY OF CONFIGURE OPTIONS:
239 ----------------------------
240
241     The configure script provides a short list of its options when you type
242
243         ./configure --help
244
245     The --help and several options are common to all configure scripts that are
246     generated with autoconf.  Those are all listed before the line
247
248         --enable and --with options recognized:
249
250     The other options are specific to this package.  We list them in alphabetic
251     order.
252
253     --disable-assumed-color
254         With ncurses 5.1, we introduced a new function, assume_default_colors()
255         which allows applications to specify what the default foreground and
256         background color are assumed to be.  Most color applications use
257         full-screen color; but a few do not color the background.  While the
258         assumed values can be overridden by invoking assume_default_colors(),
259         you may find it useful to set the assumed values to the pre-5.1
260         convention, using this configure option.
261
262     --disable-big-core
263         Assume machine has little memory.  The configure script attempts to
264         determine if your machine has enough memory (about 6Mb) to compile the
265         terminfo database without writing portions to disk.  Some allocators
266         return deceptive results, so you may have to override the configure
267         script.  Or you may be building tic for a smaller machine.
268
269     --disable-database
270         Use only built-in data.  The ncurses libraries normally read terminfo
271         and termcap data from disk.  You can configure ncurses to have a
272         built-in database, aka "fallback" entries.  Embedded applications may
273         have no need for an external database.  Some, but not all of the
274         programs are useful in this configuration, e.g., reset and tput versus
275         infocmp and tic.
276
277     --disable-ext-funcs
278         Disable function-extensions.  Configure ncurses without the functions
279         that are not specified by XSI.  See ncurses/modules for the exact
280         list of library modules that would be suppressed.
281
282     --disable-hashmap
283         Compile without hashmap scrolling-optimization code.  This algorithm is
284         the default.
285
286     --disable-leaks
287         For testing, compile-in code that frees memory that normally would not
288         be freed, to simplify analysis of memory-leaks.
289
290     --disable-macros
291         For testing, use functions rather than macros.  The program will run
292         more slowly, but it is simpler to debug.  This makes a header file
293         "nomacros.h".  See also the --enable-expanded option.
294
295     --disable-overwrite
296         If you are installing ncurses on a system which contains another
297         development version of curses, or which could be confused by the loader
298         for another version, we recommend that you leave out the link to
299         -lcurses.  The ncurses library is always available as -lncurses.
300         Disabling overwrite also causes the ncurses header files to be
301         installed into a subdirectory, e.g., /usr/local/include/ncurses,
302         rather than the include directory.  This makes it simpler to avoid
303         compile-time conflicts with other versions of curses.h
304
305     --disable-root-environ
306         Compile with environment restriction, so certain environment variables
307         are not available when running as root, or via a setuid/setgid
308         application.  These are (for example $TERMINFO) those that allow the
309         search path for the terminfo or termcap entry to be customized.
310
311     --disable-scroll-hints
312         Compile without scroll-hints code.  This option is ignored when
313         hashmap scrolling is configured, which is the default.
314
315     --enable-add-ons=DIR...
316         This is used to check if this package is a glibc add-on.  This is used
317         only by the glibc makefiles.
318
319     --enable-assertions
320         For testing, compile-in assertion code.  This is used only for a few
321         places where ncurses cannot easily recover by returning an error code.
322
323     --enable-broken_linker
324         A few platforms have what we consider a broken linker:  it cannot link
325         objects from an archive solely by referring to data objects in those
326         files, but requires a function reference.  This configure option
327         changes several data references to functions to work around this
328         problem.
329
330         NOTE:  With ncurses 5.1, this may not be necessary, since we are
331         told that some linkers interpret uninitialized global data as a
332         different type of reference which behaves as described above.  We have
333         explicitly initialized all of the global data to work around the
334         problem.
335
336     --enable-bsdpad
337         Recognize BSD-style prefix padding.  Some ancient BSD programs (such as
338         nethack) call tputs("50") to implement delays.
339
340     --enable-colorfgbg
341         Compile with experimental $COLORFGBG code.  That environment variable
342         is set by some terminal emulators as a hint to applications, by
343         advertising the default foreground and background colors.  During
344         initialization, ncurses sets color pair 0 to match this.
345
346     --enable-const
347         The curses interface as documented in XSI is rather old, in fact
348         including features that precede ANSI C.  The prototypes generally do
349         not make effective use of "const".  When using stricter compilers (or
350         gcc with appropriate warnings), you may see warnings about the mismatch
351         between const and non-const data.  We provide a configure option which
352         changes the interfaces to use const - quieting these warnings and
353         reflecting the actual use of the parameters more closely.  The ncurses
354         library uses the symbol NCURSES_CONST for these instances of const,
355         and if you have asked for compiler warnings, will add gcc's const-qual
356         warning.  There will still be warnings due to subtle inconsistencies
357         in the interface, but at a lower level.
358
359         NOTE:  configuring ncurses with this option may detract from the
360         portability of your applications by encouraging you to use const in
361         places where the XSI curses interface would not allow them.  Similar
362         issues arise when porting to SVr4 curses, which uses const in even
363         fewer places.
364
365     --enable-echo
366         Use the option --disable-echo to make the build-log less verbose by
367         suppressing the display of the compile and link commands.  This makes
368         it easier to see the compiler warnings.  (You can always use "make -n"
369         to see the options that are used).
370
371     --enable-expanded
372         For testing, generate functions for certain macros to make them visible
373         as such to the debugger.  See also the --disable-macros option.
374
375     --enable-getcap
376         Use the 4.4BSD getcap code if available, or a bundled version of it to
377         fetch termcap entries.  Entries read in this way cannot use (make
378         cross-references to) the terminfo tree, but it is faster than reading
379         /etc/termcap.
380
381     --enable-getcap-cache
382         Cache translated termcaps under the directory $HOME/.terminfo
383
384         NOTE:  this sounds good - it makes ncurses run faster the second time. 
385         But look where the data comes from - an /etc/termcap containing lots of
386         entries that are not up to date.  If you configure with this option and
387         forget to install the terminfo database before running an ncurses
388         application, you will end up with a hidden terminfo database that
389         generally does not support color and will miss some function keys.
390
391     --enable-hard-tabs
392         Compile-in cursor-optimization code that uses hard-tabs.  We would make
393         this a standard feature except for the concern that the terminfo entry
394         may not be accurate, or that your stty settings have disabled the use
395         of tabs.
396
397     --enable-no-padding
398         Compile-in support for the $NCURSES_NO_PADDING environment variable,
399         which allows you to suppress the effect of non-mandatory padding in
400         terminfo entries.  This is the default, unless you have disabled the
401         extended functions.
402
403     --enable-rpath
404         Use rpath option when generating shared libraries, and with some
405         restrictions when linking the corresponding programs.  This applies
406         mainly to systems using the GNU linker (read the manpage).
407
408     --enable-safe-sprintf
409         Compile with experimental safe-sprintf code.  You may consider using
410         this if you are building ncurses for a system that has neither
411         vsnprintf() or vsprintf().  It is slow, however.
412
413     --enable-sigwinch
414         Compile support for ncurses' SIGWINCH handler.  If your application has
415         its own SIGWINCH handler, ncurses will not use its own.  The ncurses
416         handler causes wgetch() to return KEY_RESIZE when the screen-size
417         changes.  This option is the default, unless you have disabled the
418         extended functions.
419
420     --enable-symlinks
421         If your system supports symbolic links, make tic use symbolic links
422         rather than hard links to save diskspace when writing aliases in the
423         terminfo database.
424
425     --enable-tcap-names
426         Compile-in support for user-definable terminal capabilities.  Use the
427         -x option of tic and infocmp to treat unrecognized terminal
428         capabilities as user-defined strings.  This option is the default,
429         unless you have disabled the extended functions.
430
431     --enable-termcap
432         Compile in support for reading terminal descriptions from termcap if no
433         match is found in the terminfo database.  See also the --enable-getcap
434         and --enable-getcap-cache options.
435
436     --enable-warnings
437         Turn on GCC compiler warnings.  There should be only a few.
438
439     --enable-widec
440         Compile with experimental wide-character code.  This makes a different
441         version of the libraries (e.g., libncursesw.so), which stores
442         characters as wide-characters,
443
444         NOTE: applications compiled with this configuration are not compatible
445         with those built for 8-bit characters.  You cannot simply make a
446         symbolic link to equate libncurses.so with libncursesw.so
447
448         NOTE: the Ada95 binding may be built against either version of the the
449         ncurses library, but you must decide which:  the binding installs the
450         same set of files for either version.  Currently (2002/6/22) it does
451         not use the extended features from the wide-character code, so it is
452         probably better to not install the binding for that configuration.
453
454     --enable-xmc-glitch
455         Compile-in support experimental xmc (magic cookie) code.
456
457     --with-ada-compiler=CMD
458         Specify the Ada95 compiler command (default "gnatmake")
459
460     --with-ada-include=DIR
461         Tell where to install the Ada includes (default: 
462         PREFIX/lib/ada/adainclude)
463
464     --with-ada-objects=DIR
465         Tell where to install the Ada objects (default:  PREFIX/lib/ada/adalib)
466
467     --with-bool=TYPE
468         If --without-cxx is specified, override the type used for the "bool"
469         declared in curses.h (normally the type is automatically chosen to
470         correspond with that in <stdbool.h>, or defaults to platform-specific
471         sizes).
472
473     --with-build-cc=XXX
474         If cross-compiling, specify a host C compiler, which is needed to
475         compile a few utilties which generate source modules for ncurses.
476         If you do not give this option, the configure script checks if the
477         $BUILD_CC variable is set, and otherwise defaults to gcc or cc.
478
479     --with-build-cflags=XXX
480         If cross-compiling, specify the host C compiler-flags.  You might need
481         to do this if the target compiler has unusual flags which confuse the
482         host compiler.
483
484     --with-build-cppflags=XXX
485         If cross-compiling, specify the host C preprocesor-flags.  You might
486         need to do this if the target compiler has unusual flags which confuse
487         the host compiler.
488
489     --with-build-ldflags=XXX
490         If cross-compiling, specify the host linker-flags.  You might need to
491         do this if the target linker has unusual flags which confuse the host
492         compiler.
493
494     --with-build-libs=XXX
495         If cross-compiling, the host libraries.  You might need to do this if
496         the target environment requires unusual libraries.
497
498     --with-caps=XXX
499         Specify an alternate terminfo capabilities file, which makes the
500         configure script look for "include/Caps.XXX".  A few systems, e.g.,
501         AIX 4.x use the same overall file-format as ncurses for terminfo
502         data, but use different alignments within the tables to support
503         legacy applications.  For those systems, you can configure ncurses
504         to use a terminfo database which is compatible with the native
505         applications.
506
507     --with-database=XXX
508         Specify the terminfo source file to install.  Usually you will wish
509         to install ncurses' default (misc/terminfo.src).  Certain systems
510         have special requirements, e.g, OS/2 EMX has a customized terminfo
511         source file.
512
513     --with-dbmalloc
514         For testing, compile and link with Conor Cahill's dbmalloc library.
515
516     --with-debug
517         Generate debug-libraries (default).  These are named by adding "_g"
518         to the root, e.g., libncurses_g.a
519
520     --with-default-terminfo-dir=XXX
521         Specify the default terminfo database directory.  This is normally
522         DATADIR/terminfo, e.g., /usr/share/terminfo.
523
524     --with-develop
525         Enable experimental/development options.  This does not count those
526         that change the interface, such as --enable-widec.
527
528     --with-dmalloc
529         For testing, compile and link with Gray Watson's dmalloc library.
530
531     --with-fallbacks=XXX
532         Specify a list of fallback terminal descriptions which will be
533         compiled into the ncurses library.  See CONFIGURING FALLBACK ENTRIES.
534
535     --with-gpm
536         use Alessandro Rubini's GPM library to provide mouse support on the
537         Linux console.
538
539     --with-install-prefix=XXX
540         Allows you to specify an alternate location for installing ncurses
541         after building it.  The value you specify is prepended to the "real"
542         install location.  This simplifies making binary packages.
543
544         NOTE:  a few systems build shared libraries with fixed pathnames; this
545         option probably will not work for those configurations.
546
547      --with-libtool
548         Generate libraries with libtool.  If this option is selected, then
549         it overrides all other library model specifications.
550
551     --with-manpage-format=XXX
552         Tell the configure script how you would like to install man-pages.  The
553         option value must be one of these:  gzip, compress, BSDI, normal,
554         formatted.  If you do not give this option, the configure script
555         attempts to determine which is the case.
556
557     --with-manpage-renames=XXX
558         Tell the configure script that you wish to rename the manpages while
559         installing.  Currently the only distribution which does this is
560         the Linux Debian.  The option value specifies the name of a file
561         that lists the renamed files, e.g., $srcdir/man/man_db.renames
562
563     --with-manpage-symlinks
564         Tell the configure script that you wish to make symbolic links in the
565         man-directory for aliases to the man-pages.  This is the default, but
566         can be disabled for systems that provide this automatically.  Doing
567         this on systems that do not support symbolic links will result in
568         copying the man-page for each alias.
569
570     --with-manpage-tbl
571         Tell the configure script that you with to preprocess the manpages
572         by running them through tbl to generate tables understandable by
573         nroff.
574
575     --with-ospeed=TYPE
576         Override type of ospeed variable, which is part of the termcap
577         compatibility interface.  In termcap, this is a 'short', which works
578         for a wide range of baudrates because ospeed is not the actual speed
579         but the encoded value, e.g., B9600 would be a small number such as 13. 
580         However the encoding scheme originally allowed for values "only" up to
581         38400bd.  A newer set of definitions past 38400bd is not encoded as
582         compactly, and is not guaranteed to fit into a short (see the function
583         cfgetospeed(), which returns a speed_t for this reason).  In practice,
584         applications that required knowledge of the ospeed variable, i.e.,
585         those using termcap, do not use the higher speeds.  Your application
586         (or system, in general) may or may not.
587
588     --with-normal
589         Generate normal (i.e., static) libraries (default).
590
591     --with-profile
592         Generate profile-libraries These are named by adding "_p" to the root,
593         e.g., libncurses_p.a
594
595     --with-rcs-ids
596         Compile-in RCS identifiers.  Most of the C files have an identifier.
597
598     --with-shared
599         Generate shared-libraries.  The names given depend on the system for
600         which you are building, typically using a ".so" suffix, along with
601         symbolic links that refer to the release version.
602         
603         NOTE:  Unless you override the configure script by setting the $CFLAGS
604         environment variable, these will not be built with the -g debugging
605         option.
606
607     --with-shlib-version=XXX
608         Specify whether to use the release or ABI version for shared libraries.
609         This is normally chosen automatically based on the type of system
610         which you are building on.  We use it for testing the configure script.
611
612     --with-system-type=XXX
613         For testing, override the derived host system-type which is used to
614         decide things such as the linker commands used to build shared
615         libraries.  This is normally chosen automatically based on the type of
616         system which you are building on.  We use it for testing the configure
617         script.
618
619     --with-terminfo-dirs=XXX
620         Specify a search-list of terminfo directories which will be compiled
621         into the ncurses library (default: DATADIR/terminfo)
622
623     --with-termlib
624         When building the ncurses library, organize this as two parts:  the
625         curses library (libncurses) and the low-level terminfo library
626         (libtinfo).  This is done to accommodate applications that use only
627         the latter.  The terminfo library is about half the size of the total.
628
629     --with-termpath=XXX
630         Specify a search-list of termcap files which will be compiled into the
631         ncurses library (default:  /etc/termcap:/usr/share/misc/termcap)
632
633     --without-ada
634         Suppress the configure script's check for Ada95, do not build the
635         Ada95 binding and related demo.
636
637     --without-curses-h
638         Don't install the ncurses header with the name "curses.h".  Rather,
639         install as "ncurses.h" and modify the installed headers and manpages
640         accordingly.
641
642     --without-cxx
643         XSI curses declares "bool" as part of the interface.  C++ also declares
644         "bool".  Neither specifies the size and type of booleans, but both
645         insist on the same name.  We chose to accommodate this by making the
646         configure script check for the size and type (e.g., unsigned or signed)
647         that your C++ compiler uses for booleans.  If you do not wish to use
648         ncurses with C++, use this option to tell the configure script to not
649         adjust ncurses bool to match C++.
650
651     --without-cxx-binding
652         Suppress the configure script's check for C++, do not build the
653         C++ binding and related demo.
654
655     --without-progs
656         Tell the configure script to suppress the build of ncurses' application
657         programs (e.g., tic).  The test applications will still be built if you
658         type "make", though not if you simply do "make install".
659
660
661 COMPATIBILITY WITH OLDER VERSIONS OF NCURSES:
662 --------------------------------------------
663
664     Because ncurses implements the X/Open Curses Specification, its interface
665     is fairly stable.  That does not mean the interface does not change.
666     Changes are made to the documented interfaces when we find differences
667     between ncurses and X/Open or implementations which they certify (such as
668     Solaris).  We add extensions to those interfaces to solve problems not
669     addressed by the original curses design, but those must not conflict with
670     the X/Open documentation.
671
672     Here are some of the major interface changes, and related problems which
673     you may encounter when building a system with different versions of
674     ncurses:
675
676     5.3 (pre-release)
677         Interface changes:
678
679         + change type for bool used in headers to NCURSES_BOOL, which usually
680           is the same as the compiler's definition for 'bool'.
681
682         + add all but two functions for X/Open curses wide-character support.
683           These are only available if the library is configured using the
684           --enable-widec option.  Missing functions are
685                 pecho_wchar()
686                 slk_wset()
687
688         + add environment variable $NCURSES_ASSUMED_COLORS to modify the
689           assume_default_colors() extension.
690
691         Added extensions:
692                 is_term_resized()
693                 resize_term()
694         Added internal functions:
695                 _nc_altcharset_name()   debug
696                 _nc_rootname()
697                 _nc_trace_ttymode()     debug
698                 _nc_varargs()           debug
699                 _nc_wgetch()
700         Removed internal functions:
701                 _nc_background()
702         Modified internal functions:
703                 _nc_freeall()           debug
704
705     5.2 (October 21, 2000)
706         Interface changes:
707
708         + revert termcap ospeed variable to 'short' (see discussion of the
709           --with-ospeed configure option).
710
711     5.1 (July 8, 2000)
712         Interface changes:
713
714         + made the extended terminal capabilities
715           (configure --enable-tcap-names) a standard feature.  This should
716           be transparent to applications that do not require it.
717
718         + removed the trace() function and related trace support from the
719           production library.
720
721         + modified curses.h.in, undef'ing some symbols to avoid conflict
722           with C++ STL.
723
724         Added extensions:  assume_default_colors().
725
726     5.0 (October 23, 1999)
727         Interface changes:
728
729         + implemented the wcolor_set() and slk_color() functions.
730
731         + move macro winch to a function, to hide details of struct ldat
732
733         + corrected prototypes for slk_* functions, using chtype rather than
734           attr_t.
735
736         + the slk_attr_{set,off,on} functions need an additional void*
737           parameter according to XSI.
738
739         + modified several prototypes to correspond with 1997 version of X/Open
740           Curses:  [w]attr_get(), [w]attr_set(), border_set() have different
741           parameters.  Some functions were renamed or misspelled:
742           erase_wchar(), in_wchntr(), mvin_wchntr().  Some developers have used
743           attr_get().
744
745         Added extensions:  keybound(), curses_version().
746
747         Terminfo database changes:
748
749         + change translation for termcap 'rs' to terminfo 'rs2', which is
750           the documented equivalent, rather than 'rs1'.
751
752         The problems are subtler in recent releases.
753
754         a) This release provides users with the ability to define their own
755            terminal capability extensions, like termcap.  To accomplish this,
756            we redesigned the TERMTYPE struct (in term.h).  Very few
757            applications use this struct.  They must be recompiled to work with
758            the 5.0 library.
759
760         a) If you use the extended terminfo names (i.e., you used configure
761            --enable-tcap-names), the resulting terminfo database can have some
762            entries which are not readable by older versions of ncurses.  This
763            is a bug in the older versions:
764
765            + the terminfo database stores booleans, numbers and strings in
766              arrays.  The capabilities that are listed in the arrays are
767              specified by X/Open.  ncurses recognizes a number of obsolete and
768              extended names which are stored past the end of the specified
769              entries.
770
771            + a change to read_entry.c in 951001 made the library do an lseek()
772              call incorrectly skipping data which is already read from the
773              string array.  This happens when the number of strings in the
774              terminfo data file is greater than STRCOUNT, the number of
775              specified and obsolete or extended strings.
776
777            + as part of alignment with the X/Open final specification, in the
778              990109 patch we added two new terminfo capabilities:
779              set_a_attributes and set_pglen_inch).  This makes the indices for
780              the obsolete and extended capabilities shift up by 2.
781
782            + the last two capabilities in the obsolete/extended list are memu
783              and meml, which are found in most terminfo descriptions for xterm.
784
785              When trying to read this terminfo entry, the spurious lseek()
786              causes the library to attempt to read the final portion of the
787              terminfo data (the text of the string capabilities) 4 characters
788              past its starting point, and reads 4 characters too few.  The
789              library rejects the data, and applications are unable to
790              initialize that terminal type.
791
792            FIX: remove memu and meml from the xterm description.  They are
793            obsolete, not used by ncurses.  (It appears that the feature was
794            added to xterm to make it more like hpterm).
795
796            This is not a problem if you do not use the -x option of tic to
797            create a terminfo database with extended names.  Note that the
798            user-defined terminal capabilities are not affected by this bug,
799            since they are stored in a table after the older terminfo data ends,
800            and are invisible to the older libraries.
801
802         c) Some developers did not wish to use the C++ binding, and used the
803            configure --without-cxx option.  This causes problems if someone
804            uses the ncurses library from C++ because that configure test
805            determines the type for C++'s bool and makes ncurses match it, since
806            both C++ and curses are specified to declare bool.  Calling ncurses
807            functions with the incorrect type for bool will cause execution
808            errors.  In 5.0 we added a configure option "--without-cxx-binding"
809            which controls whether the binding itself is built and installed.
810
811     4.2 (March 2, 1998)
812         Interface changes:
813
814         + correct prototype for termattrs() as per XPG4 version 2.
815
816         + add placeholder prototypes for color_set(), erasewchar(),
817           term_attrs(), wcolor_set() as per XPG4 version 2.
818
819         + add macros getcur[xy] getbeg[xy] getpar[xy], which are defined in
820           SVr4 headers.
821
822         New extensions: keyok() and define_key().
823
824         Terminfo database changes:
825
826         + corrected definition in curses.h for ACS_LANTERN, which was 'I'
827           rather than 'i'.
828
829     4.1 (May 15, 1997)
830
831         We added these extensions:  use_default_colors().  Also added
832         configure option --enable-const, to support the use of const where
833         X/Open should have, but did not, specify.
834
835         The terminfo database content changed the representation of color for
836         most entries that use ANSI colors.  SVr4 curses treats the setaf/setab
837         and setf/setb capabilities differently, interchanging the red/blue
838         colors in the latter.
839
840     4.0 (December 24, 1996)
841
842         We bumped to version 4.0 because the newly released dynamic loader
843         (ld.so.1.8.5) on Linux did not load shared libraries whose ABI and REL
844         versions were inconsistent.  At that point, ncurses ABI was 3.4 and the
845         REL was 1.9.9g, so we made them consistent.
846
847     1.9.9g (December 1, 1996)
848
849         This fixed most of the problems with 1.9.9e, and made these interface
850         changes:
851
852         + remove tparam(), which had been provided for compatibility with
853           some termcap.  tparm() is standard, and does not conflict with
854           application's fallback for missing tparam().
855
856         + turn off hardware echo in initscr().  This changes the sense of the
857           echo() function, which was initialized to echoing rather than
858           nonechoing (the latter is specified).  There were several other
859           corrections to the terminal I/O settings which cause applications to
860           behave differently.
861
862         + implemented several functions (such as attr_on()) which were
863           available only as macros.
864
865         + corrected several typos in curses.h.in (i.e., the mvXXXX macros).
866
867         + corrected prototypes for delay_output(),
868           has_color, immedok() and idcok().
869
870         + corrected misspelled getbkgd().  Some applications used the
871           misspelled name.
872
873         + added _yoffset to WINDOW.  The size of WINDOW does not impact
874           applications, since they use only pointers to WINDOW structs.
875
876         These changes were made to the terminfo database:
877
878         + removed boolean 'getm' which was available as an extended name.
879
880         We added these extensions: wresize(), resizeterm(), has_key() and
881         mcprint().
882
883     1.9.9e (March 24, 1996)
884
885         not recommended (a last-minute/untested change left the forms and
886         menus libraries unusable since they do not repaint the screen).
887         Foreground/background colors are combined incorrectly, working properly
888         only on a black background.  When this was released, the X/Open
889         specification was available only in draft form.
890
891         Some applications (such as lxdialog) were "fixed" to work with the
892         incorrect color scheme.
893
894
895 IF YOU ARE A SYSTEM INTEGRATOR:
896 ------------------------------
897
898     Beginning with 1.9.9, the ncurses distribution includes both a tset
899     utility and /usr/share/tabset directory.  If you are installing ncurses,
900     it is no longer either necessary or desirable to install tset-jv.
901
902     Configuration and Installation:
903
904         Configure with --prefix=/usr to make the install productions put
905         libraries and headers in the correct locations (overwriting any
906         previous curses libraries and headers).  This will put the terminfo
907         hierarchy under /usr/share/terminfo; you may want to override this with
908         --datadir=/usr/share/misc; terminfo and tabset are installed under the
909         data directory.
910
911         Please configure the ncurses library in a pure-terminfo mode; that
912         is, with the --disable-termcap option.   This will make the ncurses
913         library smaller and faster. The ncurses library includes a termcap
914         emulation that queries the terminfo database, so even applications
915         that use raw termcap to query terminal characteristics will win
916         (providing you recompile and relink them!).
917
918         If you must configure with termcap fallback enabled, you may also
919         wish to use the --enable-getcap option.  This option speeds up
920         termcap-based startups, at the expense of not allowing personal
921         termcap entries to reference the terminfo tree.  See the code in
922         ncurses/tinfo/read_termcap.c for details.
923
924         Note that if you have $TERMCAP set, ncurses will use that value
925         to locate termcap data.  In particular, running from xterm will
926         set $TERMCAP to the contents of the xterm's termcap entry.
927         If ncurses sees that, it will not examine /etc/termcap.
928
929     Keyboard Mapping:
930
931         The terminfo file assumes that Shift-Tab generates \E[Z (the ECMA-48
932         reverse-tabulation sequence) rather than ^I.  Here are the loadkeys -d
933         mappings that will set this up:
934
935                 keycode  15 = Tab             Tab
936                         alt     keycode  15 = Meta_Tab
937                         shift   keycode  15 = F26
938                 string F26 ="\033[Z"
939
940     Naming the Console Terminal
941
942         In various Linuxes (and possibly elsewhere) there has been a practice
943         of designating the system console driver type as `console'.  Please
944         do not do this any more!  It complicates peoples' lives, because it
945         can mean that several different terminfo entries from different
946         operating systems all logically want to be called `console'.
947
948         Please pick a name unique to your console driver and set that up
949         in the /etc/inittab table or local equivalent.  Send the entry to the
950         terminfo maintainer (listed in the misc/terminfo file) to be included
951         in the terminfo file, if it's not already there.  See the
952         term(7) manual page included with this distribution for more on
953         conventions for choosing type names.
954
955         Here are some recommended primary console names:
956
957                 linux   -- Linux console driver
958                 freebsd -- FreeBSD
959                 netbsd  -- NetBSD
960                 bsdos   -- BSD/OS
961
962         If you are responsible for integrating ncurses for one of these
963         distribution, please either use the recommended name or get back
964         to us explaining why you don't want to, so we can work out nomenclature
965         that will make users' lives easier rather than harder.
966
967
968 RECENT XTERM VERSIONS:
969 ---------------------
970
971         The terminfo database file included with this distribution assumes you
972         are running an XFree86 xterm based on X11R6 (i.e., xterm-r6).  The
973         earlier X11R5 entry (xterm-r5) is provided as well.
974
975         If you are running XFree86 version 3.2 (actually 3.1.2F and up), you
976         should consider using the xterm-xf86-v32 (or later, the most recent
977         version is always named "xterm-xfree86") entry, which adds ANSI color
978         and the VT220 capabilities which have been added in XFree86.  If you
979         are running a mixed network, however, where this terminal description
980         may be used on an older xterm, you may have problems, since
981         applications that assume these capabilities will produce incorrect
982         output on the older xterm (e.g., highlighting is not cleared).
983
984
985 CONFIGURING FALLBACK ENTRIES:
986 ----------------------------
987
988         In order to support operation of ncurses programs before the terminfo
989         tree is accessible (that is, in single-user mode or at OS installation
990         time) the ncurses library can be compiled to include an array of
991         pre-fetched fallback entries.
992
993         These entries are checked by setupterm() only when the conventional
994         fetches from the terminfo tree and the termcap fallback (if configured)
995         have been tried and failed.  Thus, the presence of a fallback will not
996         shadow modifications to the on-disk entry for the same type, when that
997         entry is accessible.
998
999         By default, there are no entries on the fallback list.  After you
1000         have built the ncurses suite for the first time, you can change
1001         the list (the process needs infocmp(1)).  To do so, use the script
1002         MKfallback.sh.  A configure script option --with-fallbacks does this
1003         (it accepts a comma-separated list of the names you wish, and does
1004         not require a rebuild).
1005
1006         If you wanted (say) to have linux, vt100, and xterm fallbacks, you
1007         would use the commands
1008
1009                 cd ncurses;
1010                 MKfallback.sh linux vt100 xterm >fallback.c
1011
1012         Then just rebuild and reinstall the library as you would normally.
1013         You can restore the default empty fallback list with
1014
1015                 MKfallback.sh >fallback.c
1016
1017         The overhead for an empty fallback list is one trivial stub function.
1018         Any non-empty fallback list is const-ed and therefore lives in sharable
1019         text space.  You can look at the comment trailing each initializer in
1020         the generated ncurses/fallback.c file to see the core cost of the
1021         fallbacks.  A good rule of thumb for modern vt100-like entries is that
1022         each one will cost about 2.5K of text space.
1023
1024
1025 BSD CONVERSION NOTES:
1026 --------------------
1027
1028         If you need to support really ancient BSD programs, you probably
1029         want to configure with the --enable-bsdpad option.  What this does
1030         is enable code in tputs() that recognizes a numeric prefix on a
1031         capability as a request for that much trailing padding in milliseconds.
1032         There are old BSD programs that do things like tputs("50").
1033
1034         (If you are distributing ncurses as a support-library component of
1035         an application you probably want to put the remainder of this section
1036         in the package README file.)
1037
1038         The following note applies only if you have configured ncurses with
1039         --enable-termcap.
1040
1041 ------------------------------- CUT HERE --------------------------------
1042
1043 If you are installing this application privately (either because you
1044 have no root access or want to experiment with it before doing a root
1045 installation), there are a couple of details you need to be aware of.
1046 They have to do with the ncurses library, which uses terminfo rather
1047 than termcap for describing terminal characteristics.
1048
1049 Though the ncurses library is terminfo-based, it will interpret your
1050 TERMCAP variable (if present), any local termcap files you reference
1051 through it, and the system termcap file.  However, in order to avoid
1052 slowing down your application startup, it will only do this once per
1053 terminal type!
1054
1055 The first time you load a given terminal type from your termcap
1056 database, the library initialization code will automatically write it
1057 in terminfo format to a subdirectory under $HOME/.terminfo.  After
1058 that, the initialization code will find it there and do a (much
1059 faster) terminfo fetch.
1060
1061 Usually, all this means is that your home directory will silently grow
1062 an invisible .terminfo subdirectory which will get filled in with
1063 terminfo descriptions of terminal types as you invoke them.  If anyone
1064 ever installs a global terminfo tree on your system, this will quietly
1065 stop happening and your $HOME/.terminfo will become redundant.
1066
1067 The objective of all this logic is to make converting from BSD termcap
1068 as painless as possible without slowing down your application (termcap
1069 compilation is expensive).
1070
1071 If you don't have a TERMCAP variable or custom personal termcap file,
1072 you can skip the rest of this dissertation.
1073
1074 If you *do* have a TERMCAP variable and/or a custom personal termcap file
1075 that defines a terminal type, that definition will stop being visible
1076 to this application after the first time you run it, because it will
1077 instead see the terminfo entry that it wrote to $HOME/terminfo the
1078 first time around.
1079
1080 Subsequently, editing the TERMCAP variable or personal TERMCAP file
1081 will have no effect unless you explicitly remove the terminfo entry
1082 under $HOME/terminfo.  If you do that, the entry will be recompiled
1083 from your termcap resources the next time it is invoked.
1084
1085 To avoid these complications, use infocmp(1) and tic(1) to edit the
1086 terminfo directory directly.
1087
1088 ------------------------------- CUT HERE --------------------------------
1089
1090 USING NCURSES WITH AFS:
1091         AFS treats each directory as a separate logical filesystem, you
1092         can't hard-link across them.  The --enable-symlinks option copes
1093         with this by making tic use symbolic links.
1094
1095 USING NCURSES WITH EMACS:
1096         GNU Emacs has its own termcap support.  By default, it uses a mixture
1097         of those functions and code linked from the host system's libraries.
1098         You need to foil this and shut out the GNU termcap library entirely.
1099
1100         In order to do this, hack the Linux config file (s/linux.h) to contain
1101         a #define TERMINFO and set the symbol LIBS_TERMCAP to "-lncurses".
1102
1103         We have submitted such a change for the 19.30 release, so it may
1104         already be applied in your sources -- check for the #define TERMINFO.
1105
1106 USING NCURSES WITH GPM:
1107         Ncurses 4.1 and up can be configured to use GPM (General Purpose Mouse)
1108         which is used on Linux console.  Be aware that GPM is commonly
1109         installed as a shared library which contains a wrapper for the curses
1110         wgetch() function (libcurses.o).  Some integrators have simplified
1111         linking applications by combining all or part of libcurses.so (the BSD
1112         curses) into the libgpm.so file, producing symbol conflicts with
1113         ncurses (specifically the wgetch function).  You may be able to work
1114         around this problem by linking as follows:
1115
1116                 cc -o foo foo.o -lncurses -lgpm -lncurses
1117
1118         but the linker may not cooperate, producing mysterious errors.
1119         A patched version of gpm is available:
1120
1121                 dickey.his.com:/ncurses/gpm-1.10-970125.tar.gz
1122
1123         This patch is incorporated in gpm 1.12; however some integrators
1124         are slow to update this library.  Current distributions of gpm can
1125         be configured properly using the --without-curses option.
1126
1127 BUILDING NCURSES WITH A CROSS-COMPILER
1128         Ncurses can be built with a cross-compiler.  Some parts must be built
1129         with the host's compiler since they are used for building programs
1130         (e.g., ncurses/make_hash and ncurses/make_keys) that generate tables
1131         that are compiled into the ncurses library.  You should set the
1132         BUILD_CC environment variable to your host's compiler, and run the
1133         configure script configuring for the cross-compiler.
1134
1135         Note that all of the generated source-files which are part of ncurses
1136         will be made if you use
1137
1138                 make sources
1139
1140         This would be useful in porting to an environment which has little
1141         support for the tools used to generate the sources, e.g., sed, awk and
1142         Bourne-shell.
1143
1144 BUGS:
1145         Send any feedback to the ncurses mailing list at
1146         bug-ncurses@gnu.org. To subscribe send mail to
1147         bug-ncurses-request@gnu.org with body that reads:
1148         subscribe ncurses <your-email-address-here>
1149
1150         The Hacker's Guide in the doc directory includes some guidelines
1151         on how to report bugs in ways that will get them fixed most quickly.