Tickit_Debug - debug logging support for libtickit
$ TICKIT_DEBUG_FLAGS=W TICKIT_DEBUG_FILE=tickit.log a-tickit-program
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.
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.
These messages relate to TickitRenderBuffer (tickit_renderbuffer(7)).
These messages relate to input-system events.
- Drawing operations such as tickit_renderbuffer_text(3).
- Stack state save and restore.
These messages relate to windows.
- Keyboard keypresses.
- Mouse movement and button or wheel events.
- Terminal resize. Transformations (translation, clipping and masking).
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.
- Window destroyed.
- Damage to root window.
- Window is exposed.
- Window hierarchy changed.
- Window scrolls.
- Window propagates a scrollrect to its underlying terminal.
- 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 *.
- Gives the name of a file to open in append mode to write logging lines
- 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
$ 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
The debug system is initialised by calling tickit_debug_init(3). Messages
can be logged using tickit_debug_logf(3) and
tickit(7), tickit_term(7), tickit_renderbuffer(7),