NAME

       Tickit_Debug - debug logging support for libtickit

SYNOPSIS

       $ TICKIT_DEBUG_FLAGS=W TICKIT_DEBUG_FILE=tickit.log a-tickit-program

DESCRIPTION

       The  libtickit library contains a debug logging system that other parts of the library use
       to report on interesting events and  behaviours,  that  may  help  developers  to  observe
       internal  details and assist in the development and debugging of applications that use the
       library.

       Debug messages themselves each have a flag name, which is a short string  identifying  the
       library  component  or  event  that caused that message. A given set of these flags can be
       enabled during a debugging session, causing only those messages to  be  printed.  Messages
       pertaining to flags that are not enabled will not be printed.

FLAGS

       Each  flag  name  starts  with  an  upper-case  letter indicating the library component it
       relates to, then lower-case letters to indicate the particular kind of  event  or  message
       within that component.

   B
       These messages relate to TickitRenderBuffer (tickit_renderbuffer(7)).

       Bd     Drawing operations such as tickit_renderbuffer_text(3).

       Bf     Flushing

       Bs     Stack state save and restore.

       Bt

   I
       These messages relate to input-system events.

       Ik     Keyboard keypresses.

       Im     Mouse movement and button or wheel events.

       Ir     Terminal resize.  Transformations (translation, clipping and masking).

   W
       These messages relate to windows.

       W*     Window destroyed.

       Wd     Damage to root window.

       Wx     Window is exposed.

       Wh     Window hierarchy changed.

       Ws     Window scrolls.

       Wsr    Window propagates a scrollrect to its underlying terminal.

ENVIRONMENT

       The  debugging  support is controlled by the following environment variables, which should
       be set before the application starts, or early during its  initialisation  before  it  has
       invoked any libtickit functions.

       TICKIT_DEBUG_FLAGS
              A  comma-separated  list  of  the  flags or flag categories to enable for printing.
              Entire categories of flags can be enabled by list just the initial  capital  letter
              of its name. All the flags can be enabled at once by setting the name *.

       TICKIT_DEBUG_FILE
              Gives the name of a file to open in append mode to write logging lines to.

       TICKIT_DEBUG_FD
              Gives a file descriptor number to write logging lines to.

       One  technique  that  may  be useful to observe logging in real-time while the application
       runs is to arrange for the application to run in a new terminal but have it log  debugging
       output to an existing one. This may be achieved using

       $ TICKIT_DEBUG_FD=3 TICKIT_DEBUG_FLAGS=... $TERM my-tickit-app 3>&2

       This requests that libtickit log to file descriptor 3, which has been created by dup(2)ing
       the original shell's standard output. Debug logging  will  therefore  be  printed  to  the
       existing  terminal where this command was executed, while the application itself draws its
       output to the newly-created one.

FUNCTIONS

       The debug system is initialised by calling tickit_debug_init(3). Messages  can  be  logged
       using tickit_debug_logf(3) and tickit_debug_vlogf(3).

SEE ALSO

       tickit(7), tickit_term(7), tickit_renderbuffer(7), tickit_window(7)

                                                                                  TICKIT_DEBUG(7)