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
| Command | Description |
|---|---|
compile-commands | Generate a compile_commands.json file from captured compiler commands. See Compilation Database. |
tree | Render captured commands as a command tree. See Command Tree. |
targets | Render captured build targets as a flat target forest. See Target Tree. |
profile | Write the timeline of the build's commands as a trace for Perfetto. See Build Profiling. |
explain | Print how catter analyzes the command after --, without running it. See Explain. |
run | Run 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:
| Option | Description | Default |
|---|---|---|
-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-remote | Let --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>...| Argument | Description |
|---|---|
<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)
| Variable | Purpose |
|---|---|
__key_catter_proxy_path_v1 | Path to the catter-proxy executable |
__key_catter_command_id_v1 | IPC command identifier |
__key_catter_ipc_v1 | The 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.
