xref: /freebsd/contrib/ncurses/README (revision 21817992b3314c908ab50f0bb88d2ee750b9c4ac)
14a1a9510SRong-En Fan-------------------------------------------------------------------------------
2*21817992SBaptiste Daroussin-- Copyright 2020-2021,2023 Thomas E. Dickey                                 --
3e1865124SBaptiste Daroussin-- Copyright 1998-2012,2018 Free Software Foundation, Inc.                   --
44a1a9510SRong-En Fan--                                                                           --
54a1a9510SRong-En Fan-- Permission is hereby granted, free of charge, to any person obtaining a   --
64a1a9510SRong-En Fan-- copy of this software and associated documentation files (the             --
74a1a9510SRong-En Fan-- "Software"), to deal in the Software without restriction, including       --
84a1a9510SRong-En Fan-- without limitation the rights to use, copy, modify, merge, publish,       --
94a1a9510SRong-En Fan-- distribute, distribute with modifications, sublicense, and/or sell copies --
104a1a9510SRong-En Fan-- of the Software, and to permit persons to whom the Software is furnished  --
114a1a9510SRong-En Fan-- to do so, subject to the following conditions:                            --
124a1a9510SRong-En Fan--                                                                           --
134a1a9510SRong-En Fan-- The above copyright notice and this permission notice shall be included   --
144a1a9510SRong-En Fan-- in all copies or substantial portions of the Software.                    --
154a1a9510SRong-En Fan--                                                                           --
164a1a9510SRong-En Fan-- THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS   --
174a1a9510SRong-En Fan-- OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF                --
184a1a9510SRong-En Fan-- MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN --
194a1a9510SRong-En Fan-- NO EVENT SHALL THE ABOVE COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,       --
204a1a9510SRong-En Fan-- DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR     --
214a1a9510SRong-En Fan-- OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE --
224a1a9510SRong-En Fan-- USE OR OTHER DEALINGS IN THE SOFTWARE.                                    --
234a1a9510SRong-En Fan--                                                                           --
244a1a9510SRong-En Fan-- Except as contained in this notice, the name(s) of the above copyright    --
254a1a9510SRong-En Fan-- holders shall not be used in advertising or otherwise to promote the      --
264a1a9510SRong-En Fan-- sale, use or other dealings in this Software without prior written        --
274a1a9510SRong-En Fan-- authorization.                                                            --
284a1a9510SRong-En Fan-------------------------------------------------------------------------------
29*21817992SBaptiste Daroussin-- $Id: README,v 1.31 2023/10/28 14:49:04 tom Exp $
300e3d5408SPeter Wemm-------------------------------------------------------------------------------
310e3d5408SPeter Wemm		README file for the ncurses package
320e3d5408SPeter Wemm
330e3d5408SPeter WemmSee the file ANNOUNCE for a summary of ncurses features and ports.
340e3d5408SPeter WemmSee the file INSTALL for instructions on how to build and install ncurses.
350e3d5408SPeter WemmSee the file NEWS for a release history and bug-fix notes.
360e3d5408SPeter WemmSee the file TO-DO for things that still need doing, including known bugs.
370e3d5408SPeter Wemm
38*21817992SBaptiste DaroussinBrowse the file doc/html/ncurses-intro.html for narrative descriptions of how
390e3d5408SPeter Wemmto use ncurses and the panel, menu, and form libraries.
400e3d5408SPeter Wemm
4118259542SPeter WemmBrowse the file doc/html/hackguide.html for a tour of the package internals.
420e3d5408SPeter Wemm
43*21817992SBaptiste DaroussinFind plain text versions of both of these documents in doc/.
44*21817992SBaptiste Daroussin
450e3d5408SPeter WemmROADMAP AND PACKAGE OVERVIEW:
460e3d5408SPeter Wemm
470e3d5408SPeter WemmYou should be reading this file in a directory called:  ncurses-d.d, where d.d
480e3d5408SPeter Wemmis the current version number (see the dist.mk file in this directory for
490e3d5408SPeter Wemmthat).  There should be a number of subdirectories, including `c++', `form',
50*21817992SBaptiste Daroussin`man', `menu', `misc', `ncurses', `panel', `progs', `test', and `Ada95'.
510e3d5408SPeter Wemm
520e3d5408SPeter WemmA full build/install of this package typically installs several libraries, a
530e3d5408SPeter Wemmhandful of utilities, and a database hierarchy.  Here is an inventory of the
540e3d5408SPeter Wemmpieces:
550e3d5408SPeter Wemm
560e3d5408SPeter WemmThe libraries are:
570e3d5408SPeter Wemm
580e3d5408SPeter Wemm	libncurses.a       (normal)
590e3d5408SPeter Wemm	libncurses.so      (shared)
600e3d5408SPeter Wemm	libncurses_g.a     (debug and trace code enabled)
610e3d5408SPeter Wemm	libncurses_p.a     (profiling enabled)
620e3d5408SPeter Wemm
630e3d5408SPeter Wemm	libpanel.a         (normal)
640e3d5408SPeter Wemm	libpanel.so        (shared)
650e3d5408SPeter Wemm	libpanel_g.a       (debug and trace code enabled)
660e3d5408SPeter Wemm
670e3d5408SPeter Wemm	libmenu.a          (normal)
680e3d5408SPeter Wemm	libmenu.so         (shared)
690e3d5408SPeter Wemm	libmenu_g.a        (debug enabled)
700e3d5408SPeter Wemm
710e3d5408SPeter Wemm	libform.a          (normal)
720e3d5408SPeter Wemm	libform.so         (shared)
730e3d5408SPeter Wemm	libform_g.a        (debug enabled)
740e3d5408SPeter Wemm
754a1a9510SRong-En FanIf you configure using the --enable-widec option, a "w" is appended to the
764a1a9510SRong-En Fanlibrary names (e.g., libncursesw.a), and the resulting libraries support
774a1a9510SRong-En Fanwide-characters, e.g., via a UTF-8 locale.  The corresponding header files
784a1a9510SRong-En Fanare compatible with the non-wide-character configuration; wide-character
794a1a9510SRong-En Fanfeatures are provided by ifdef's in the header files.  The wide-character
804a1a9510SRong-En Fanlibrary interfaces are not binary-compatible with the non-wide-character
814a1a9510SRong-En Fanversion.
824a1a9510SRong-En Fan
8373f0a83dSXin LIIf you configure using the --enable-reentrant option, a "t" is appended to the
8473f0a83dSXin LIlibrary names (e.g., libncursest.a) and the resulting libraries have a
85*21817992SBaptiste Daroussindifferent binary interface, making the ncurses interface more opaque.
8673f0a83dSXin LI
870e3d5408SPeter WemmThe ncurses libraries implement the curses API.  The panel, menu and forms
880e3d5408SPeter Wemmlibraries implement clones of the SVr4 panel, menu and forms APIs.  The source
890e3d5408SPeter Wemmcode for these lives in the `ncurses', `panel', `menu', and `form' directories
900e3d5408SPeter Wemmrespectively.
910e3d5408SPeter Wemm
920e3d5408SPeter WemmIn the `c++' directory, you'll find code that defines an interface to the
93*21817992SBaptiste Daroussincurses, forms, menus and panels library packaged as C++ classes, and a demo
94*21817992SBaptiste Daroussinprogram in C++ to test it.  These class definition modules are not installed
95*21817992SBaptiste Daroussinby the 'make install.libs' rule as libncurses++.
960e3d5408SPeter Wemm
970e3d5408SPeter WemmIn the `Ada95' directory, you'll find code and documentation for an
980e3d5408SPeter WemmAda95 binding of the curses API, to be used with the GNAT compiler.
990e3d5408SPeter WemmThis binding is built by a normal top-level `make' if configure detects
1004a1a9510SRong-En Fanan usable version of GNAT (3.11 or above). It is not installed automatically.
1010e3d5408SPeter WemmSee the Ada95 directory for more build and installation instructions and
1020e3d5408SPeter Wemmfor documentation of the binding.
1030e3d5408SPeter Wemm
1040e3d5408SPeter WemmTo do its job, the ncurses code needs your terminal type to be set in the
1050e3d5408SPeter Wemmenvironment variable TERM (normally set by your OS; under UNIX, getty(1)
106*21817992SBaptiste Daroussintypically does this, but you can override it in your .profile); and, it needs
107*21817992SBaptiste Daroussina database of terminal descriptions in which to look up your terminal type's
1080e3d5408SPeter Wemmcapabilities.
1090e3d5408SPeter Wemm
1100e3d5408SPeter WemmIn older (V7/BSD) versions of curses, the database was a flat text file,
1110e3d5408SPeter Wemm/etc/termcap; in newer (USG/USL) versions, the database is a hierarchy of
1120e3d5408SPeter Wemmfast-loading binary description blocks under /usr/lib/terminfo.  These binary
1130e3d5408SPeter Wemmblocks are compiled from an improved editable text representation called
1140e3d5408SPeter Wemm`terminfo' format (documented in man/terminfo.5).  The ncurses library can use
1150e3d5408SPeter Wemmeither /etc/termcap or the compiled binary terminfo blocks, but prefers the
1160e3d5408SPeter Wemmsecond form.
1170e3d5408SPeter Wemm
1180e3d5408SPeter WemmIn the `misc' directory, there is a text file terminfo.src, in editable
1190e3d5408SPeter Wemmterminfo format, which can be used to generate the terminfo binaries (that's
1200e3d5408SPeter Wemmwhat make install.data does).  If the package was built with the
121*21817992SBaptiste Daroussin--enable-termcap option enabled, and the ncurses library cannot find a
122*21817992SBaptiste Daroussinterminfo description for your terminal, it will fall back to the termcap file
123*21817992SBaptiste Daroussinsupplied with your system (which the ncurses package installation leaves
124*21817992SBaptiste Daroussinstrictly alone).
1250e3d5408SPeter Wemm
1260e3d5408SPeter WemmThe utilities are as follows:
1270e3d5408SPeter Wemm
1280e3d5408SPeter Wemm	tic             -- terminfo source to binary compiler
1290e3d5408SPeter Wemm	infocmp         -- terminfo binary to source decompiler/comparator
1300e3d5408SPeter Wemm	clear           -- emits clear-screen for current terminal
13173f0a83dSXin LI	tabs            -- set tabs on a terminal
1320e3d5408SPeter Wemm	tput            -- shell-script access to terminal capabilities.
1330e3d5408SPeter Wemm	toe             -- table of entries utility
1340e3d5408SPeter Wemm	tset            -- terminal-initialization utility
1350e3d5408SPeter Wemm
1360e3d5408SPeter WemmThe first two (tic and infocmp) are used for manipulating terminfo
1370e3d5408SPeter Wemmdescriptions; the next two (clear and tput) are for use in shell scripts.  The
1380e3d5408SPeter Wemmlast (tset) is provided for 4.4BSD compatibility.  The source code for all of
1390e3d5408SPeter Wemmthese lives in the `progs' directory.
1400e3d5408SPeter Wemm
14118259542SPeter WemmDetailed documentation for all libraries and utilities can be found in the
14218259542SPeter Wemm`man' and `doc' directories.  An HTML introduction to ncurses, panels, and
14318259542SPeter Wemmmenus programming lives in the `doc/html' directory.  Manpages in HTML format
14418259542SPeter Wemmare under `doc/html/man'.
1450e3d5408SPeter Wemm
1460e3d5408SPeter WemmThe `test' directory contains programs that can be used to verify or
1470e3d5408SPeter Wemmdemonstrate the functions of the ncurses libraries.  See test/README for
1480e3d5408SPeter Wemmdescriptions of these programs.  Notably, the `ncurses' utility is designed to
1490e3d5408SPeter Wemmhelp you systematically exercise the library functions.
1500e3d5408SPeter Wemm
1510e3d5408SPeter WemmAUTHORS:
1520e3d5408SPeter Wemm
1530e3d5408SPeter WemmPavel Curtis:
1540e3d5408SPeter Wemm	wrote the original ncurses
1550e3d5408SPeter Wemm
1560e3d5408SPeter WemmZeyd M. Ben-Halim:
1570e3d5408SPeter Wemm	port of original to Linux and many enhancements.
1580e3d5408SPeter Wemm
1591759abf3SPeter WemmThomas Dickey (maintainer for 1.9.9g through 4.1, resuming with FSF's 5.0):
1600e3d5408SPeter Wemm	configuration scripts, porting, mods to adhere to XSI Curses in the
1610e3d5408SPeter Wemm	areas of background color, terminal modes.  Also memory leak testing,
1620e3d5408SPeter Wemm	the wresize, default colors and key definition extensions and numerous
16373f0a83dSXin LI	bug fixes -- more than half of those enumerated in NEWS beginning with
16473f0a83dSXin LI	the internal release 1.8.9, see
16573f0a83dSXin LI
166aae38d10SBaptiste Daroussin		https://invisible-island.net/personal/changelogs.html
1670e3d5408SPeter Wemm
1680e3d5408SPeter WemmFlorian La Roche (official maintainer for FSF's ncurses 4.2)
1690e3d5408SPeter Wemm	Beginning with release 4.2, ncurses is distributed under an MIT-style
1700e3d5408SPeter Wemm	license.
1710e3d5408SPeter Wemm
1720e3d5408SPeter WemmEric S. Raymond:
1730e3d5408SPeter Wemm	the man pages, infocmp(1), tput(1), clear(1), captoinfo(1), tset(1),
1740e3d5408SPeter Wemm	toe(1), most of tic(1), trace levels, the HTML intro, wgetnstr() and
1750e3d5408SPeter Wemm	many other entry points, the cursor-movement optimization, the
1760e3d5408SPeter Wemm	scroll-pack optimizer for vertical motions, the mouse interface and
1770e3d5408SPeter Wemm	xterm mouse support, and the ncurses test program.
1780e3d5408SPeter Wemm
1790e3d5408SPeter WemmJuergen Pfeifer
180*21817992SBaptiste Daroussin	The menu and form libraries, C++ bindings for ncurses, menus, forms
181*21817992SBaptiste Daroussin	and panels, as well as the Ada95 binding.  Ongoing support for panel.
1820e3d5408SPeter Wemm
1830e3d5408SPeter WemmCONTRIBUTORS:
1840e3d5408SPeter Wemm
1850e3d5408SPeter WemmAlexander V. Lukyanov
1860e3d5408SPeter Wemm	for numerous fixes and improvements to the optimization logic.
1870e3d5408SPeter Wemm
1880e3d5408SPeter WemmDavid MacKenzie
1890e3d5408SPeter Wemm	for first-class bug-chasing and methodical testing.
1900e3d5408SPeter Wemm
1910e3d5408SPeter WemmRoss Ridge
1920e3d5408SPeter Wemm	for the code that hacks termcap parameterized strings into terminfo.
1930e3d5408SPeter Wemm
1940e3d5408SPeter WemmWarren Tucker and Gerhard Fuernkranz,
1950e3d5408SPeter Wemm	for writing and sending the panel library.
1960e3d5408SPeter Wemm
1970e3d5408SPeter WemmHellmuth Michaelis,
1980e3d5408SPeter Wemm	for many patches and testing the optimization code.
1990e3d5408SPeter Wemm
2000e3d5408SPeter WemmEric Newton, Ulrich Drepper, and Anatoly Ivasyuk:
2010e3d5408SPeter Wemm	the C++ code.
2020e3d5408SPeter Wemm
2030e3d5408SPeter WemmJonathan Ross,
2040e3d5408SPeter Wemm	for lessons in using sed.
2050e3d5408SPeter Wemm
2060e3d5408SPeter WemmKeith Bostic (maintainer of 4.4BSD curses)
2070e3d5408SPeter Wemm	for help, criticism, comments, bug-finding, and being willing to
2080e3d5408SPeter Wemm	deep-six BSD curses for this one when it grew up.
2090e3d5408SPeter Wemm
2100e3d5408SPeter WemmRichard Stallman,
2110e3d5408SPeter Wemm	for his commitment to making ncurses free software.
2120e3d5408SPeter Wemm
2130e3d5408SPeter WemmCountless other people have contributed by reporting bugs, sending fixes,
2140e3d5408SPeter Wemmsuggesting improvements, and generally whining about ncurses :-)
2150e3d5408SPeter Wemm
2160e3d5408SPeter WemmBUGS:
2170e3d5408SPeter Wemm	See the INSTALL file for bug and developer-list addresses.
21818259542SPeter Wemm	The Hacker's Guide in the doc directory includes some guidelines
2190e3d5408SPeter Wemm	on how to report bugs in ways that will get them fixed most quickly.
220*21817992SBaptiste Daroussin
221*21817992SBaptiste Daroussin-- vile:txtmode fc=78
222