diff options
Diffstat (limited to 'contrib/ncurses/misc/hackguide.html')
| -rw-r--r-- | contrib/ncurses/misc/hackguide.html | 883 |
1 files changed, 883 insertions, 0 deletions
diff --git a/contrib/ncurses/misc/hackguide.html b/contrib/ncurses/misc/hackguide.html new file mode 100644 index 000000000000..417399a68365 --- /dev/null +++ b/contrib/ncurses/misc/hackguide.html @@ -0,0 +1,883 @@ +<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML 3.0//EN"> +<!-- + $Id: hackguide.html,v 1.23 1999/01/17 00:15:48 tom Exp $ +--> +<HTML> +<HEAD> +<TITLE>A Hacker's Guide to Ncurses Internals</TITLE> +<link rev="made" href="mailto:bugs-ncurses@gnu.org"> +<!-- +This document is self-contained, *except* that there is one relative link to +the ncurses-intro.html document, expected to be in the same directory with +this one. +--> +</HEAD> +<BODY> + +<H1>A Hacker's Guide to NCURSES</H1> + +<H1>Contents</H1> +<UL> +<LI><A HREF="#abstract">Abstract</A> +<P> +<LI><A HREF="#objective">Objective of the Package</A> +<UL> +<LI><A HREF="#whysvr4">Why System V Curses?</A> +<LI><A HREF="#extensions">How to Design Extensions</A> +</UL> +<LI><A HREF="#portability">Portability and Configuration</A><UL> +</UL> +<LI><A HREF="#documentation">Documentation Conventions</A> +<P> +<LI><A HREF="#bugtrack">How to Report Bugs</A> +<P> +<LI><A HREF="#ncurslib">A Tour of the Ncurses Library</A> +<UL> +<LI><A HREF="#loverview">Library Overview</A> +<LI><A HREF="#engine">The Engine Room</A> +<LI><A HREF="#input">Keyboard Input</A> +<LI><A HREF="#mouse">Mouse Events</A> +<LI><A HREF="#output">Output and Screen Updating</A> +</UL> +<LI><A HREF="#fmnote">The Forms and Menu Libraries</A> +<P> +<LI><A HREF="#tic">A Tour of the Terminfo Compiler</A> +<UL> +<LI><A HREF="#nonuse">Translation of Non-<STRONG>use</STRONG> Capabilities</A> +<LI><A HREF="#uses">Use Capability Resolution</A> +<LI><A HREF="#translation">Source-Form Translation</A> +</UL> +<LI><A HREF="#utils">Other Utilities</A> +<P> +<LI><A HREF="#style">Style Tips for Developers</A> +<P> +<LI><A HREF="#port">Porting Hints</A> +</UL> + +<H1><A NAME="abstract">Abstract</A></H1> + +This document is a hacker's tour of the <STRONG>ncurses</STRONG> library and utilities. +It discusses design philosophy, implementation methods, and the +conventions used for coding and documentation. It is recommended +reading for anyone who is interested in porting, extending or improving the +package. <P> + +<H1><A NAME="objective">Objective of the Package</A></H1> + +The objective of the <STRONG>ncurses</STRONG> package is to provide a free software API for +character-cell terminals and terminal emulators with the following +characteristics: <P> + +<UL> +<LI>Source-compatible with historical curses implementations (including + the original BSD curses and System V curses. +<P> +<LI>Conformant with the XSI Curses standard issued as part of XPG4 by + X/Open. +<P> +<LI>High-quality -- stable and reliable code, wide portability, good + packaging, superior documentation. +<P> +<LI>Featureful -- should eliminate as much of the drudgery of C interface + programming as possible, freeing programmers to think at a higher + level of design. +</UL> + +These objectives are in priority order. So, for example, source +compatibility with older version must trump featurefulness -- we cannot +add features if it means breaking the portion of the API corresponding +to historical curses versions. <P> + +<H2><A NAME="whysvr4">Why System V Curses?</A></H2> + +We used System V curses as a model, reverse-engineering their API, in +order to fulfill the first two objectives. <P> + +System V curses implementations can support BSD curses programs with +just a recompilation, so by capturing the System V API we also +capture BSD's. <P> + +More importantly for the future, the XSI Curses standard issued by X/Open +is explicitly and closely modeled on System V. So conformance with +System V took us most of the way to base-level XSI conformance. <P> + +<H2><A NAME="extensions">How to Design Extensions</A></H2> + +The third objective (standards conformance) requires that it be easy to +condition source code using <STRONG>ncurses</STRONG> so that the absence of nonstandard +extensions does not break the code. <P> + +Accordingly, we have a policy of associating with each nonstandard extension +a feature macro, so that ncurses client code can use this macro to condition +in or out the code that requires the <STRONG>ncurses</STRONG> extension. <P> + +For example, there is a macro <CODE>NCURSES_MOUSE_VERSION</CODE> which XSI Curses +does not define, but which is defined in the <STRONG>ncurses</STRONG> library header. +You can use this to condition the calls to the mouse API calls. <P> + +<H1><A NAME="portability">Portability and Configuration</A></H1> + +Code written for <STRONG>ncurses</STRONG> may assume an ANSI-standard C compiler and +POSIX-compatible OS interface. It may also assume the presence of a +System-V-compatible <EM>select(2)</EM> call. <P> + +We encourage (but do not require) developers to make the code friendly +to less-capable UNIX environments wherever possible. <P> + +We encourage developers to support OS-specific optimizations and methods +not available under POSIX/ANSI, provided only that: <P> + +<UL> +<LI>All such code is properly conditioned so the build process does not + attempt to compile it under a plain ANSI/POSIX environment. +<P> +<LI>Adding such implementation methods does not introduce incompatibilities + in the <STRONG>ncurses</STRONG> API between platforms. +</UL> + +We use GNU <CODE>autoconf(1)</CODE> as a tool to deal with portability issues. +The right way to leverage an OS-specific feature is to modify the autoconf +specification files (configure.in and aclocal.m4) to set up a new feature +macro, which you then use to condition your code. <P> + +<H1><A NAME="documentation">Documentation Conventions</A></H1> + +There are three kinds of documentation associated with this package. Each +has a different preferred format: <P> + +<UL> +<LI>Package-internal files (README, INSTALL, TO-DO etc.) +<LI>Manual pages. +<LI>Everything else (i.e., narrative documentation). +</UL> + +Our conventions are simple: <P> +<OL> +<LI><STRONG>Maintain package-internal files in plain text.</STRONG> + The expected viewer for them <EM>more(1)</EM> or an editor window; there's + no point in elaborate mark-up. <P> + +<LI><STRONG>Mark up manual pages in the man macros.</STRONG> These have to be viewable + through traditional <EM>man(1)</EM> programs. <P> + +<LI><STRONG>Write everything else in HTML.</STRONG> +</OL> + +When in doubt, HTMLize a master and use <EM>lynx(1)</EM> to generate +plain ASCII (as we do for the announcement document). <P> + +The reason for choosing HTML is that it's (a) well-adapted for on-line +browsing through viewers that are everywhere; (b) more easily readable +as plain text than most other mark-ups, if you don't have a viewer; and (c) +carries enough information that you can generate a nice-looking printed +version from it. Also, of course, it make exporting things like the +announcement document to WWW pretty trivial.<P> + +<H1><A NAME="bugtrack">How to Report Bugs</A></H1> + +The <A NAME="bugreport">reporting address for bugs</A> is +<A HREF="mailto:bug-ncurses@gnu.org">bug-ncurses@gnu.org</A>. +This is a majordomo list; to join, write +to <CODE>bug-ncurses-request@gnu.org</CODE> with a message containing the line: +<PRE> + subscribe <name>@<host.domain> +</PRE> + +The <CODE>ncurses</CODE> code is maintained by a small group of +volunteers. While we try our best to fix bugs promptly, we simply +don't have a lot of hours to spend on elementary hand-holding. We rely +on intelligent cooperation from our users. If you think you have +found a bug in <CODE>ncurses</CODE>, there are some steps you can take +before contacting us that will help get the bug fixed quickly. <P> + +In order to use our bug-fixing time efficiently, we put people who +show us they've taken these steps at the head of our queue. This +means that if you don't, you'll probably end up at the tail end and +have to wait a while. <P> + +<OL> +<LI>Develop a recipe to reproduce the bug. <P> + +Bugs we can reproduce are likely to be fixed very quickly, often +within days. The most effective single thing you can do to get a +quick fix is develop a way we can duplicate the bad behavior -- +ideally, by giving us source for a small, portable test program that +breaks the library. (Even better is a keystroke recipe using one of +the test programs provided with the distribution.) <P> + +<LI>Try to reproduce the bug on a different terminal type. <P> + +In our experience, most of the behaviors people report as library bugs +are actually due to subtle problems in terminal descriptions. This is +especially likely to be true if you're using a traditional +asynchronous terminal or PC-based terminal emulator, rather than xterm +or a UNIX console entry. <P> + +It's therefore extremely helpful if you can tell us whether or not your +problem reproduces on other terminal types. Usually you'll have both +a console type and xterm available; please tell us whether or not your +bug reproduces on both. <P> + +If you have xterm available, it is also good to collect xterm reports for +different window sizes. This is especially true if you normally use an +unusual xterm window size -- a surprising number of the bugs we've seen +are either triggered or masked by these. <P> + +<LI>Generate and examine a trace file for the broken behavior. <P> + +Recompile your program with the debugging versions of the libraries. +Insert a <CODE>trace()</CODE> call with the argument set to <CODE>TRACE_UPDATE</CODE>. +(See <A HREF="ncurses-intro.html#debugging">"Writing Programs with +NCURSES"</A> for details on trace levels.) +Reproduce your bug, then look at the trace file to see what the library +was actually doing. <P> + +Another frequent cause of apparent bugs is application coding errors +that cause the wrong things to be put on the virtual screen. Looking +at the virtual-screen dumps in the trace file will tell you immediately if +this is happening, and save you from the possible embarrassment of being +told that the bug is in your code and is your problem rather than ours. <P> + +If the virtual-screen dumps look correct but the bug persists, it's +possible to crank up the trace level to give more and more information +about the library's update actions and the control sequences it issues +to perform them. The test directory of the distribution contains a +tool for digesting these logs to make them less tedious to wade +through. <P> + +Often you'll find terminfo problems at this stage by noticing that the +escape sequences put out for various capabilities are wrong. If not, +you're likely to learn enough to be able to characterize any bug in +the screen-update logic quite exactly. <P> + +<LI>Report details and symptoms, not just interpretations. <P> + +If you do the preceding two steps, it is very likely that you'll discover +the nature of the problem yourself and be able to send us a fix. This +will create happy feelings all around and earn you good karma for the first +time you run into a bug you really can't characterize and fix yourself. <P> + +If you're still stuck, at least you'll know what to tell us. Remember, we +need details. If you guess about what is safe to leave out, you are too +likely to be wrong. <P> + +If your bug produces a bad update, include a trace file. Try to make +the trace at the <EM>least</EM> voluminous level that pins down the +bug. Logs that have been through tracemunch are OK, it doesn't throw +away any information (actually they're better than un-munched ones because +they're easier to read). <P> + +If your bug produces a core-dump, please include a symbolic stack trace +generated by gdb(1) or your local equivalent. <P> + +Tell us about every terminal on which you've reproduced the bug -- and +every terminal on which you can't. Ideally, sent us terminfo sources +for all of these (yours might differ from ours). <P> + +Include your ncurses version and your OS/machine type, of course! You can +find your ncurses version in the <CODE>curses.h</CODE> file. +</OL> + +If your problem smells like a logic error or in cursor movement or +scrolling or a bad capability, there are a couple of tiny test frames +for the library algorithms in the progs directory that may help you +isolate it. These are not part of the normal build, but do have their +own make productions. <P> + +The most important of these is <CODE>mvcur</CODE>, a test frame for the +cursor-movement optimization code. With this program, you can see +directly what control sequences will be emitted for any given cursor +movement or scroll/insert/delete operations. If you think you've got +a bad capability identified, you can disable it and test again. The +program is command-driven and has on-line help. <P> + +If you think the vertical-scroll optimization is broken, or just want to +understand how it works better, build <CODE>hashmap</CODE> and read the +header comments of <CODE>hardscroll.c</CODE> and <CODE>hashmap.c</CODE>; then try +it out. You can also test the hardware-scrolling optimization separately +with <CODE>hardscroll</CODE>. <P> + +There's one other interactive tester, <CODE>tctest</CODE>, that exercises +translation between termcap and terminfo formats. If you have a serious +need to run this, you probably belong on our development team! <P> + +<H1><A NAME="ncurslib">A Tour of the Ncurses Library</A></H1> + +<H2><A NAME="loverview">Library Overview</A></H2> + +Most of the library is superstructure -- fairly trivial convenience +interfaces to a small set of basic functions and data structures used +to manipulate the virtual screen (in particular, none of this code +does any I/O except through calls to more fundamental modules +described below). The files +<blockquote> +<CODE> +lib_addch.c +lib_bkgd.c +lib_box.c +lib_chgat.c +lib_clear.c +lib_clearok.c +lib_clrbot.c +lib_clreol.c +lib_colorset.c +lib_data.c +lib_delch.c +lib_delwin.c +lib_echo.c +lib_erase.c +lib_gen.c +lib_getstr.c +lib_hline.c +lib_immedok.c +lib_inchstr.c +lib_insch.c +lib_insdel.c +lib_insstr.c +lib_instr.c +lib_isendwin.c +lib_keyname.c +lib_leaveok.c +lib_move.c +lib_mvwin.c +lib_overlay.c +lib_pad.c +lib_printw.c +lib_redrawln.c +lib_scanw.c +lib_screen.c +lib_scroll.c +lib_scrollok.c +lib_scrreg.c +lib_set_term.c +lib_slk.c +lib_slkatr_set.c +lib_slkatrof.c +lib_slkatron.c +lib_slkatrset.c +lib_slkattr.c +lib_slkclear.c +lib_slkcolor.c +lib_slkinit.c +lib_slklab.c +lib_slkrefr.c +lib_slkset.c +lib_slktouch.c +lib_touch.c +lib_unctrl.c +lib_vline.c +lib_wattroff.c +lib_wattron.c +lib_window.c +</CODE> +</blockquote> +are all in this category. They are very +unlikely to need change, barring bugs or some fundamental +reorganization in the underlying data structures. <P> + +These files are used only for debugging support: +<blockquote><code> +lib_trace.c +lib_traceatr.c +lib_tracebits.c +lib_tracechr.c +lib_tracedmp.c +lib_tracemse.c +trace_buf.c +</blockquote></code> +It is rather unlikely you will ever need to change these, unless +you want to introduce a new debug trace level for some reasoon.<P> + +There is another group of files that do direct I/O via <EM>tputs()</EM>, +computations on the terminal capabilities, or queries to the OS +environment, but nevertheless have only fairly low complexity. These +include: +<blockquote><code> +lib_acs.c +lib_beep.c +lib_color.c +lib_endwin.c +lib_initscr.c +lib_longname.c +lib_newterm.c +lib_options.c +lib_termcap.c +lib_ti.c +lib_tparm.c +lib_tputs.c +lib_vidattr.c +read_entry.c. +</blockquote></code> +They are likely to need revision only if +ncurses is being ported to an environment without an underlying +terminfo capability representation. <P> + +These files +have serious hooks into +the tty driver and signal facilities: +<blockquote><code> +lib_kernel.c +lib_baudrate.c +lib_raw.c +lib_tstp.c +lib_twait.c +</blockquote></code> +If you run into porting snafus +moving the package to another UNIX, the problem is likely to be in one +of these files. +The file <CODE>lib_print.c</CODE> uses sleep(2) and also +falls in this category.<P> + +Almost all of the real work is done in the files +<blockquote><code> +hardscroll.c +hashmap.c +lib_addch.c +lib_doupdate.c +lib_getch.c +lib_mouse.c +lib_mvcur.c +lib_refresh.c +lib_setup.c +lib_vidattr.c +</blockquote></code> +Most of the algorithmic complexity in the +library lives in these files. +If there is a real bug in <STRONG>ncurses</STRONG> itself, it's probably here. +We'll tour some of these files in detail +below (see <A HREF="#engine">The Engine Room</A>). <P> + +Finally, there is a group of files that is actually most of the +terminfo compiler. The reason this code lives in the <STRONG>ncurses</STRONG> +library is to support fallback to /etc/termcap. These files include +<blockquote><code> +alloc_entry.c +captoinfo.c +comp_captab.c +comp_error.c +comp_hash.c +comp_parse.c +comp_scan.c +parse_entry.c +read_termcap.c +write_entry.c +</blockquote></code> +We'll discuss these in the compiler tour. <P> + +<H2><A NAME="engine">The Engine Room</A></H2> + +<H3><A NAME="input">Keyboard Input</A></H3> + +All <CODE>ncurses</CODE> input funnels through the function +<CODE>wgetch()</CODE>, defined in <CODE>lib_getch.c</CODE>. This function is +tricky; it has to poll for keyboard and mouse events and do a running +match of incoming input against the set of defined special keys. <P> + +The central data structure in this module is a FIFO queue, used to +match multiple-character input sequences against special-key +capabilities; also to implement pushback via <CODE>ungetch()</CODE>. <P> + +The <CODE>wgetch()</CODE> code distinguishes between function key +sequences and the same sequences typed manually by doing a timed wait +after each input character that could lead a function key sequence. +If the entire sequence takes less than 1 second, it is assumed to have +been generated by a function key press. <P> + +Hackers bruised by previous encounters with variant <CODE>select(2)</CODE> +calls may find the code in <CODE>lib_twait.c</CODE> interesting. It deals +with the problem that some BSD selects don't return a reliable +time-left value. The function <CODE>timed_wait()</CODE> effectively +simulates a System V select. <P> + +<H3><A NAME="mouse">Mouse Events</A></H3> + +If the mouse interface is active, <CODE>wgetch()</CODE> polls for mouse +events each call, before it goes to the keyboard for input. It is +up to <CODE>lib_mouse.c</CODE> how the polling is accomplished; it may vary +for different devices. <P> + +Under xterm, however, mouse event notifications come in via the keyboard +input stream. They are recognized by having the <STRONG>kmous</STRONG> capability +as a prefix. This is kind of klugey, but trying to wire in recognition of +a mouse key prefix without going through the function-key machinery would +be just too painful, and this turns out to imply having the prefix somewhere +in the function-key capabilities at terminal-type initialization. <P> + +This kluge only works because <STRONG>kmous</STRONG> isn't actually used by any +historic terminal type or curses implementation we know of. Best +guess is it's a relic of some forgotten experiment in-house at Bell +Labs that didn't leave any traces in the publicly-distributed System V +terminfo files. If System V or XPG4 ever gets serious about using it +again, this kluge may have to change. <P> + +Here are some more details about mouse event handling: <P> + +The <CODE>lib_mouse()</CODE>code is logically split into a lower level that +accepts event reports in a device-dependent format and an upper level that +parses mouse gestures and filters events. The mediating data structure is a +circular queue of event structures. <P> + +Functionally, the lower level's job is to pick up primitive events and +put them on the circular queue. This can happen in one of two ways: +either (a) <CODE>_nc_mouse_event()</CODE> detects a series of incoming +mouse reports and queues them, or (b) code in <CODE>lib_getch.c</CODE> detects the +<STRONG>kmous</STRONG> prefix in the keyboard input stream and calls _nc_mouse_inline +to queue up a series of adjacent mouse reports. <P> + +In either case, <CODE>_nc_mouse_parse()</CODE> should be called after the +series is accepted to parse the digested mouse reports (low-level +events) into a gesture (a high-level or composite event). <P> + +<H3><A NAME="output">Output and Screen Updating</A></H3> + +With the single exception of character echoes during a <CODE>wgetnstr()</CODE> +call (which simulates cooked-mode line editing in an ncurses window), +the library normally does all its output at refresh time. <P> + +The main job is to go from the current state of the screen (as represented +in the <CODE>curscr</CODE> window structure) to the desired new state (as +represented in the <CODE>newscr</CODE> window structure), while doing as +little I/O as possible. <P> + +The brains of this operation are the modules <CODE>hashmap.c</CODE>, +<CODE>hardscroll.c</CODE> and <CODE>lib_doupdate.c</CODE>; the latter two use +<CODE>lib_mvcur.c</CODE>. Essentially, what happens looks like this: <P> + +The <CODE>hashmap.c</CODE> module tries to detect vertical motion +changes between the real and virtual screens. This information +is represented by the oldindex members in the newscr structure. +These are modified by vertical-motion and clear operations, and both are +re-initialized after each update. To this change-journalling +information, the hashmap code adds deductions made using a modified Heckel +algorithm on hash values generated from the line contents. <P> + +The <CODE>hardscroll.c</CODE> module computes an optimum set of scroll, +insertion, and deletion operations to make the indices match. It calls +<CODE>_nc_mvcur_scrolln()</CODE> in <CODE>lib_mvcur.c</CODE> to do those motions. <P> + +Then <CODE>lib_doupdate.c</CODE> goes to work. Its job is to do line-by-line +transformations of <CODE>curscr</CODE> lines to <CODE>newscr</CODE> lines. Its main +tool is the routine <CODE>mvcur()</CODE> in <CODE>lib_mvcur.c</CODE>. This routine +does cursor-movement optimization, attempting to get from given screen +location A to given location B in the fewest output characters posible. <P> + +If you want to work on screen optimizations, you should use the fact +that (in the trace-enabled version of the library) enabling the +<CODE>TRACE_TIMES</CODE> trace level causes a report to be emitted after +each screen update giving the elapsed time and a count of characters +emitted during the update. You can use this to tell when an update +optimization improves efficiency. <P> + +In the trace-enabled version of the library, it is also possible to disable +and re-enable various optimizations at runtime by tweaking the variable +<CODE>_nc_optimize_enable</CODE>. See the file <CODE>include/curses.h.in</CODE> +for mask values, near the end. <P> + +<H1><A NAME="fmnote">The Forms and Menu Libraries</A></H1> + +The forms and menu libraries should work reliably in any environment you +can port ncurses to. The only portability issue anywhere in them is what +flavor of regular expressions the built-in form field type TYPE_REGEXP +will recognize. <P> + +The configuration code prefers the POSIX regex facility, modeled on +System V's, but will settle for BSD regexps if the former isn't available. <P> + +Historical note: the panels code was written primarily to assist in +porting u386mon 2.0 (comp.sources.misc v14i001-4) to systems lacking +panels support; u386mon 2.10 and beyond use it. This version has been +slightly cleaned up for <CODE>ncurses</CODE>. <P> + +<H1><A NAME="tic">A Tour of the Terminfo Compiler</A></H1> + +The <STRONG>ncurses</STRONG> implementation of <STRONG>tic</STRONG> is rather complex +internally; it has to do a trying combination of missions. This starts +with the fact that, in addition to its normal duty of compiling +terminfo sources into loadable terminfo binaries, it has to be able to +handle termcap syntax and compile that too into terminfo entries. <P> + +The implementation therefore starts with a table-driven, dual-mode +lexical analyzer (in <CODE>comp_scan.c</CODE>). The lexer chooses its +mode (termcap or terminfo) based on the first `,' or `:' it finds in +each entry. The lexer does all the work of recognizing capability +names and values; the grammar above it is trivial, just "parse entries +till you run out of file". <P> + +<H2><A NAME="nonuse">Translation of Non-<STRONG>use</STRONG> Capabilities</A></H2> + +Translation of most things besides <STRONG>use</STRONG> capabilities is pretty +straightforward. The lexical analyzer's tokenizer hands each capability +name to a hash function, which drives a table lookup. The table entry +yields an index which is used to look up the token type in another table, +and controls interpretation of the value. <P> + +One possibly interesting aspect of the implementation is the way the +compiler tables are initialized. All the tables are generated by various +awk/sed/sh scripts from a master table <CODE>include/Caps</CODE>; these +scripts actually write C initializers which are linked to the compiler. +Furthermore, the hash table is generated in the same way, so it doesn't +have to be generated at compiler startup time (another benefit of this +organization is that the hash table can be in shareable text space). <P> + +Thus, adding a new capability is usually pretty trivial, just a matter +of adding one line to the <CODE>include/Caps</CODE> file. We'll have more +to say about this in the section on <A HREF="#translation">Source-Form +Translation</A>. <P> + +<H2><A NAME="uses">Use Capability Resolution</A></H2> + +The background problem that makes <STRONG>tic</STRONG> tricky isn't the capability +translation itself, it's the resolution of <STRONG>use</STRONG> capabilities. Older +versions would not handle forward <STRONG>use</STRONG> references for this reason +(that is, a using terminal always had to follow its use target in the +source file). By doing this, they got away with a simple implementation +tactic; compile everything as it blows by, then resolve uses from compiled +entries. <P> + +This won't do for <STRONG>ncurses</STRONG>. The problem is that that the whole +compilation process has to be embeddable in the <STRONG>ncurses</STRONG> library +so that it can be called by the startup code to translate termcap +entries on the fly. The embedded version can't go promiscuously writing +everything it translates out to disk -- for one thing, it will typically +be running with non-root permissions. <P> + +So our <STRONG>tic</STRONG> is designed to parse an entire terminfo file into a +doubly-linked circular list of entry structures in-core, and then do +<STRONG>use</STRONG> resolution in-memory before writing everything out. This +design has other advantages: it makes forward and back use-references +equally easy (so we get the latter for free), and it makes checking for +name collisions before they're written out easy to do. <P> + +And this is exactly how the embedded version works. But the stand-alone +user-accessible version of <STRONG>tic</STRONG> partly reverts to the historical +strategy; it writes to disk (not keeping in core) any entry with no +<STRONG>use</STRONG> references. <P> + +This is strictly a core-economy kluge, implemented because the +terminfo master file is large enough that some core-poor systems swap +like crazy when you compile it all in memory...there have been reports of +this process taking <STRONG>three hours</STRONG>, rather than the twenty seconds +or less typical on the author's development box. <P> + +So. The executable <STRONG>tic</STRONG> passes the entry-parser a hook that +<EM>immediately</EM> writes out the referenced entry if it has no use +capabilities. The compiler main loop refrains from adding the entry +to the in-core list when this hook fires. If some other entry later +needs to reference an entry that got written immediately, that's OK; +the resolution code will fetch it off disk when it can't find it in +core. <P> + +Name collisions will still be detected, just not as cleanly. The +<CODE>write_entry()</CODE> code complains before overwriting an entry that +postdates the time of <STRONG>tic</STRONG>'s first call to +<CODE>write_entry()</CODE>, Thus it will complain about overwriting +entries newly made during the <STRONG>tic</STRONG> run, but not about +overwriting ones that predate it. <P> + +<H2><A NAME="translation">Source-Form Translation</A></H2> + +Another use of <STRONG>tic</STRONG> is to do source translation between various termcap +and terminfo formats. There are more variants out there than you might +think; the ones we know about are described in the <STRONG>captoinfo(1)</STRONG> +manual page. <P> + +The translation output code (<CODE>dump_entry()</CODE> in +<CODE>ncurses/dump_entry.c</CODE>) is shared with the <STRONG>infocmp(1)</STRONG> +utility. It takes the same internal representation used to generate +the binary form and dumps it to standard output in a specified +format. <P> + +The <CODE>include/Caps</CODE> file has a header comment describing ways you +can specify source translations for nonstandard capabilities just by +altering the master table. It's possible to set up capability aliasing +or tell the compiler to plain ignore a given capability without writing +any C code at all. <P> + +For circumstances where you need to do algorithmic translation, there +are functions in <CODE>parse_entry.c</CODE> called after the parse of each +entry that are specifically intended to encapsulate such +translations. This, for example, is where the AIX <STRONG>box1</STRONG> capability +get translated to an <STRONG>acsc</STRONG> string.<P> + +<H1><A NAME="utils">Other Utilities</A></H1> + +The <STRONG>infocmp</STRONG> utility is just a wrapper around the same +entry-dumping code used by <STRONG>tic</STRONG> for source translation. Perhaps +the one interesting aspect of the code is the use of a predicate +function passed in to <CODE>dump_entry()</CODE> to control which +capabilities are dumped. This is necessary in order to handle both +the ordinary De-compilation case and entry difference reporting. <P> + +The <STRONG>tput</STRONG> and <STRONG>clear</STRONG> utilities just do an entry load +followed by a <CODE>tputs()</CODE> of a selected capability. <P> + +<H1><A NAME="style">Style Tips for Developers</A></H1> + +See the TO-DO file in the top-level directory of the source distribution +for additions that would be particularly useful. <P> + +The prefix <CODE>_nc_</CODE> should be used on library public functions that are +not part of the curses API in order to prevent pollution of the +application namespace. + +If you have to add to or modify the function prototypes in curses.h.in, +read ncurses/MKlib_gen.sh first so you can avoid breaking XSI conformance. + +Please join the ncurses mailing list. See the INSTALL file in the +top level of the distribution for details on the list. <P> + +Look for the string <CODE>FIXME</CODE> in source files to tag minor bugs +and potential problems that could use fixing. <P> + +Don't try to auto-detect OS features in the main body of the C code. +That's the job of the configuration system. <P> + +To hold down complexity, do make your code data-driven. Especially, +if you can drive logic from a table filtered out of +<CODE>include/Caps</CODE>, do it. If you find you need to augment the +data in that file in order to generate the proper table, that's still +preferable to ad-hoc code -- that's why the fifth field (flags) is +there. <P> + +Have fun! <P> + +<H1><A NAME="port">Porting Hints</A></H1> + +The following notes are intended to be a first step towards DOS and Macintosh +ports of the ncurses libraries. <P> + +The following library modules are `pure curses'; they operate only on +the curses internal structures, do all output through other curses +calls (not including <CODE>tputs()</CODE> and <CODE>putp()</CODE>) and do not +call any other UNIX routines such as signal(2) or the stdio library. +Thus, they should not need to be modified for single-terminal +ports. <P> + +<blockquote><code> +lib_addch.c +lib_addstr.c +lib_bkgd.c +lib_box.c +lib_clear.c +lib_clrbot.c +lib_clreol.c +lib_delch.c +lib_delwin.c +lib_erase.c +lib_inchstr.c +lib_insch.c +lib_insdel.c +lib_insstr.c +lib_keyname.c +lib_move.c +lib_mvwin.c +lib_newwin.c +lib_overlay.c +lib_pad.c +lib_printw.c +lib_refresh.c +lib_scanw.c +lib_scroll.c +lib_scrreg.c +lib_set_term.c +lib_touch.c +lib_tparm.c +lib_tputs.c +lib_unctrl.c +lib_window.c +panel.c +</blockquote></code> +<P> + +This module is pure curses, but calls outstr(): <P> + +<blockquote><code> +lib_getstr.c +</blockquote></code> +<P> + +These modules are pure curses, except that they use <CODE>tputs()</CODE> +and <CODE>putp()</CODE>: <P> + +<blockquote><code> +lib_beep.c +lib_color.c +lib_endwin.c +lib_options.c +lib_slk.c +lib_vidattr.c +</blockquote></code> +<P> + +This modules assist in POSIX emulation on non-POSIX systems: <P> +<DL> +<DT> sigaction.c +<DD> signal calls +</DL> + +The following source files will not be needed for a +single-terminal-type port. <P> + +<blockquote><code> +alloc_entry.c +captoinfo.c +clear.c +comp_captab.c +comp_error.c +comp_hash.c +comp_main.c +comp_parse.c +comp_scan.c +dump_entry.c +infocmp.c +parse_entry.c +read_entry.c +tput.c +write_entry.c +</blockquote></code> +<P> + +The following modules will use open()/read()/write()/close()/lseek() on files, +but no other OS calls. <P> + +<DL> +<DT>lib_screen.c +<DD>used to read/write screen dumps +<DT>lib_trace.c +<DD>used to write trace data to the logfile +</DL> + +Modules that would have to be modified for a port start here: <P> + +The following modules are `pure curses' but contain assumptions inappropriate +for a memory-mapped port. <P> + +<dl> +<dt>lib_longname.c<dd>assumes there may be multiple terminals +<dt>lib_acs.c<dd>assumes acs_map as a double indirection +<dt>lib_mvcur.c<dd>assumes cursor moves have variable cost +<dt>lib_termcap.c<dd>assumes there may be multiple terminals +<dt>lib_ti.c<dd>assumes there may be multiple terminals +</dl> + +The following modules use UNIX-specific calls: + +<dl> +<dt>lib_doupdate.c<dd>input checking +<dt>lib_getch.c<dd>read() +<dt>lib_initscr.c<dd>getenv() +<dt>lib_newterm.c +<dt>lib_baudrate.c +<dt>lib_kernel.c<dd>various tty-manipulation and system calls +<dt>lib_raw.c<dd>various tty-manipulation calls +<dt>lib_setup.c<dd>various tty-manipulation calls +<dt>lib_restart.c<dd>various tty-manipulation calls +<dt>lib_tstp.c<dd>signal-manipulation calls +<dt>lib_twait.c<dd>gettimeofday(), select(). +</dl> + +<HR> +<ADDRESS>Eric S. Raymond <esr@snark.thyrsus.com></ADDRESS> +(Note: This is <EM>not</EM> the <A HREF="#bugtrack">bug address</A>!) +</BODY> +</HTML> |