hackguide.doc

ncurses-5.4 需要的就来下把 一定会有用的哦

                          A Hacker's Guide to NCURSES

                                   Contents

     * Abstract
     * Objective of the Package
          + Why System V Curses?
          + How to Design Extensions
     * Portability and Configuration
     * Documentation Conventions
     * How to Report Bugs
     * A Tour of the Ncurses Library
          + Library Overview
          + The Engine Room
          + Keyboard Input
          + Mouse Events
          + Output and Screen Updating
     * The Forms and Menu Libraries
     * A Tour of the Terminfo Compiler
          + Translation of Non-use Capabilities
          + Use Capability Resolution
          + Source-Form Translation
     * Other Utilities
     * Style Tips for Developers
     * Porting Hints

                                   Abstract

   This document is a hacker's tour of the ncurses 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.

                           Objective of the Package

   The objective of the ncurses package is to provide a free software API
   for character-cell terminals and terminal emulators with the following
   characteristics:
     * Source-compatible    with    historical   curses   implementations
       (including the original BSD curses and System V curses.
     * Conformant  with the XSI Curses standard issued as part of XPG4 by
       X/Open.
     * High-quality  --  stable and reliable code, wide portability, good
       packaging, superior documentation.
     * Featureful  --  should  eliminate  as  much  of  the drudgery of C
       interface programming as possible, freeing programmers to think at
       a higher level of design.

   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.

Why System V Curses?

   We  used System V curses as a model, reverse-engineering their API, in
   order to fulfill the first two objectives.

   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.

   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.

How to Design Extensions

   The  third  objective (standards conformance) requires that it be easy
   to  condition  source  code  using  ncurses  so  that  the  absence of
   nonstandard extensions does not break the code.

   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 ncurses
   extension.

   For  example,  there is a macro NCURSES_MOUSE_VERSION which XSI Curses
   does  not  define, but which is defined in the ncurses library header.
   You can use this to condition the calls to the mouse API calls.

                         Portability and Configuration

   Code  written  for  ncurses may assume an ANSI-standard C compiler and
   POSIX-compatible  OS  interface.  It may also assume the presence of a
   System-V-compatible select(2) call.

   We encourage (but do not require) developers to make the code friendly
   to less-capable UNIX environments wherever possible.

   We  encourage  developers  to  support  OS-specific  optimizations and
   methods not available under POSIX/ANSI, provided only that:
     * All  such  code  is properly conditioned so the build process does
       not attempt to compile it under a plain ANSI/POSIX environment.
     * Adding    such   implementation   methods   does   not   introduce
       incompatibilities in the ncurses API between platforms.

   We  use GNU autoconf(1) 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.

                           Documentation Conventions

   There  are  three kinds of documentation associated with this package.
   Each has a different preferred format:
     * Package-internal files (README, INSTALL, TO-DO etc.)
     * Manual pages.
     * Everything else (i.e., narrative documentation).

   Our conventions are simple:
    1. Maintain package-internal files in plain text. The expected viewer
       for  them  more(1)  or  an  editor  window;  there's  no  point in
       elaborate mark-up.
    2. Mark  up manual pages in the man macros. These have to be viewable
       through traditional man(1) programs.
    3. Write everything else in HTML.

   When  in  doubt,  HTMLize  a  master and use lynx(1) to generate plain
   ASCII (as we do for the announcement document).

   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.

                              How to Report Bugs

   The  reporting  address  for  bugs  is  [e-mail]. This is a
   majordomo  list;  to join, write to [e-mail] with a
   message containing the line:
             subscribe <name>@<host.domain>

   The  ncurses  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
   ncurses,  there  are some steps you can take before contacting us that
   will help get the bug fixed quickly.

   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.
    1. Develop a recipe to reproduce the bug.
       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.)
    2. Try to reproduce the bug on a different terminal type.
       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.
       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.
       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.
    3. Generate and examine a trace file for the broken behavior.
       Recompile   your  program  with  the  debugging  versions  of  the
       libraries.  Insert  a  trace()  call  with  the  argument  set  to
       TRACE_UPDATE.  (See "Writing Programs with NCURSES" for details on
       trace  levels.) Reproduce your bug, then look at the trace file to
       see what the library was actually doing.
       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.
       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.
       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.
    4. Report details and symptoms, not just interpretations.
       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.
       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.
       If  your  bug  produces a bad update, include a trace file. Try to
       make  the  trace  at the least 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).
       If  your bug produces a core-dump, please include a symbolic stack
       trace generated by gdb(1) or your local equivalent.
       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).
       Include  your ncurses version and your OS/machine type, of course!
       You can find your ncurses version in the curses.h file.

   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.

   The   most  important  of  these  is  mvcur,  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.

   If  you think the vertical-scroll optimization is broken, or just want
   to  understand  how it works better, build hashmap and read the header
   comments  of hardscroll.c and hashmap.c; then try it out. You can also
   test the hardware-scrolling optimization separately with hardscroll.