Skip to content

Configuration ​

catter CLI ​

catter <command> [options] -- <build-command>

Every run names a command, and its options come after it. catter --help lists the commands, and catter <command> --help shows the options of one. Without a command, catter lists the commands and exits with an error.

Commands ​

CommandDescription
compile-commandsGenerate a compile_commands.json file from captured compiler commands. See Compilation Database.
treeRender captured commands as a command tree. See Command Tree.
targetsRender captured build targets as a flat target forest. See Target Tree.
profileWrite the timeline of the build's commands as a trace for Perfetto. See Build Profiling.
explainPrint how catter analyzes the command after --, without running it. See Explain.
runRun the build with handlers alone, which decide on and observe its commands. See Handlers.

compile-commands, tree, targets and profile each run a built-in on the build, together with the handlers the command line names, if any. run runs the handlers alone, and needs at least one.

Options ​

compile-commands, tree, targets, profile and run take these options besides their own:

OptionDescriptionDefault
-C, --directory <path>The directory the command runs in.Current directory
--capture <backend>How the build's commands are captured: hook, wrapper, eslogger on macOS, or ptrace on Linux. See Capture backends.hook
--from <file>Replay the build recorded in this file instead of running one.
--handler <command>Start a handler, which decides or observes the build's commands over its stdin and stdout; may be given more than once.
--connect <host:port>Connect to a handler listening at the address, on this machine unless --allow-remote is given; may be given more than once.
--allow-remoteLet --connect reach a handler on another machine.
--handler-timeout <seconds>How long catter waits for a handler to answer, and to exit once the session is over; 0 waits as long as it takes.60

--from takes the place of the build command after --: a run gives one or the other. A relative path is from the -C directory. A recorded build is not captured: --from takes no --capture.

explain takes -C too, and the command to analyze after --.

Exit status ​

catter ends as the build did: with the build's exit code, or, when a signal ended the build, by the same signal. A replayed build ends with the exit code its file records. When catter itself fails, as when the command line is wrong, a handler aborts the build or the compilation database or the trace cannot be written, catter prints why and exits with 1.

Stopping catter stops the build: a SIGTERM, SIGINT or SIGHUP sent to catter goes on to the build command, which ends as it would if it were sent to it, and catter then ends as the build did. A build command ends with catter when catter is killed, but under eslogger.

Data directory ​

catter keeps its logs and the socket of each running session in $HOME/.catter (Linux, macOS) or %LOCALAPPDATA%\catter (Windows). The CATTER_HOME environment variable, when set, names another directory, by an absolute path. On Linux and macOS, what the build's processes log goes to the directory of their session, whatever HOME or CATTER_HOME a build step gives them.

catter-proxy CLI ​

WARNING

catter-proxy is an internal component of catter. It is invoked automatically by catter and is not intended for direct use.

catter-proxy <program> <argv>...
ArgumentDescription
<program>The program to run, as the hook found it
<argv>The program's arguments, the program's name first

It finds the session it reports the command to in its environment, in the variables below.

Environment Variables ​

These variables are set automatically by catter at runtime. They are documented here for reference; you should not need to set them manually.

Unix (Linux / macOS) ​

VariablePurpose
__key_catter_proxy_path_v1Path to the catter-proxy executable
__key_catter_command_id_v1IPC command identifier
__key_catter_ipc_v1The pipe of the catter session
__key_catter_decided_v1 (Linux)The exec catter-proxy started the program with
LD_PRELOAD (Linux)Injects the catter hook shared library
DYLD_INSERT_LIBRARIES (macOS)Injects the catter hook shared library

Windows ​

catter sets none: it gives the hook in each process of the build its session directly, and the build's environment stays as the build made it.