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