---
name: "Tickit::Debug"
section: "3pm"
platform: "linux"
package: "libtickit-perl"
version: "0.73-1+b3"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Tickit::Debug"
---

# Tickit::Debug(3pm)

debug logging support for "Tickit"

## NAME

"Tickit::Debug" - debug logging support for "Tickit"

## DESCRIPTION

This module implements the debug logging logic for Tickit. It is controlled by a number of environment variables. It exports a constant called `"DEBUG"` which will be true if the debug logging is enabled; allowing code to efficiently skip over it if it isn't.

Debug messages themselves each have a flag name, which is a short string identifying the Tickit subsystem or kind of event that caused it. A given subset of these flags can be enabled for printing. Flags not enabled will not be printed.

## FLAGS

Each flag name starts with a upper-case letters indicating the subsystem it relates to, then lower-case letters to indicate the particular kind of event or message.

### B (RenderBuffer)

*Bd*

Drawing operations

*Bf*

Flushing

*Bs*

State stack save/restore

*Bt*

Transformations (translate, clip, mask)

### I (Input)

*Ik*

Keyboard events

*Im*

Mouse events

*Ir*

Resize events

### W (Window)

*Wd*

Rectangles of damage queued on the root window for re-expose

*Wh*

Hierarchy changes on Windows (creates, deletes, re-orderings)

*Ws*

Calls to `"$win->scrollrect"`

*Wsr*

Calls to `"$term->scrollrect"` on the root window as part of scrollrect

*Wx*

Expose events on Windows; which may result in calls to its `"on_expose"` handler. As this event is recursive, it prints an indent.

## ENVIRONMENT

### TICKIT\_DEBUG\_FLAGS

A comma-separated list of the flags or flag categories to enable for printing. Each potential flag exists in a category, given by the leading upper-case letters of its name. Entire categories can be enabled by name, as can individual flags.

See the "FLAGS" list above for the available flags.

### TICKIT\_DEBUG\_FD

If set, debug logging is sent directly to the opened filehandle given by this file descriptor number, rather than opening a log file.

Typically this is most useful to start a `"Tickit"`-based application in a new terminal but have its debug logging printed to STDERR of the original terminal the new one was launched from. For example

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

This requests that `"Tickit::Debug"` log to file descriptor 3, which has been created by copying the original shell's standard error output, and so logging is printed to the shell this was run from.

### TICKIT\_DEBUG\_FILE

Gives the name of a file to open and write logging to, if `"TICKIT_DEBUG_FD"` is not set. If this is not set either, a filename will be generated using the PID of the process, named as

```
 tickit-PID.log
```

## METHODS

### log

```
   Tickit::Debug->log( $flag => $format, @args )
```

Prints a line to the debug log if the specified `$flag` is present in the set of enabled flags.

Any arguments that are `"CODE"` references are called and replaced by the list of values they return, then the line itself is generated by calling `"sprintf"` using the format string and the given arguments. It is then printed to the log, prefixed by the flag name and with a linefeed appended.

It is not necessary to include the `"\n"` linefeed in the `$format` itself.

## AUTHOR

Paul Evans \<leonerd@leonerd.org.uk\>