What is Catter?
Catter is a build process interception tool. It hooks into child process creation during a build, captures compilation and linker commands, and lets you process them with its built-ins or with handlers: programs of your own, written in any language.
Motivation
Catter was created for clice, a new C++ language server. Language servers depend on a Compilation Database (CDB) to understand how each source file is compiled, but obtaining one is often painful:
- Limited build system support -- CMake only generates CDB when using Makefile or Ninja backends. Many other popular C++ build systems have no native CDB support at all.
- Inaccessible build directories -- When C++ code is built as part of a Python package (or similar), the build directory is managed externally and the CDB file is out of reach.
- Code generators require a full build -- Projects like LLVM use tools such as
tablegenthat generate header files at build time. These files are referenced by-Iflags in the compilation commands, so the language server cannot resolve includes until a full build has run -- even if you only want to read the code.
No existing cross-platform tool solves all of these problems. That is why we created catter.
How It Works
Catter's approach is similar to Bear and scan-build. It intercepts child process creation using platform-specific hooks (LD_PRELOAD on Linux, DYLD_INSERT_LIBRARIES on macOS, DLL injection on Windows). Every intercepted command is sent to a decision-making daemon, which asks the session's handlers what to do with it.
Core Capabilities
Compilation Database Generation
The primary use case. Catter captures compiler invocations across any build system and generates a standard compile_commands.json. No build system plugins or special configuration needed.
Linker Analysis
By capturing linker commands, catter can reconstruct the dependency graph between build targets. This is essential for C++20 modules support: the C++ standard says a program may have at most one module with a given name, and "program" is defined by targets (libraries, executables). This target information is missing from the CDB standard, but catter can infer it from linker commands.
Fake Compilation (Planned)
Instead of forwarding compilation to the real compiler, catter will be able to generate placeholder object files. This lets the build system run to completion without actually compiling, producing a complete CDB in a fraction of the time. Code generators (like tablegen) are still built normally -- catter analyzes dependencies to determine the minimal set of tools that must be genuinely compiled.
Build Profiling
Catter records when each command of a build started, how long it ran and which command started it, and writes them as a trace you open in Perfetto or chrome://tracing, to see how parallel the build really is and where its time goes.
Custom Handlers
A handler, a program of your own that catter speaks to over a small protocol, can observe every command, or decide on each one: run it as it is, run another command in its place, drop it, or abort the build -- without changing the original build files. SDKs for Python and TypeScript speak the protocol for you.
Architecture at a Glance
Catter is organized around capture backends: a capture backend is how catter gets a build's commands. The default, hook, intercepts child process creation through platform hooks (Linux LD_PRELOAD, macOS DYLD_INSERT_LIBRARIES, Windows DLL injection); every captured command is handed to the daemon, which passes it to the session's handlers.
A handler is told when the session starts and how its commands are captured, of each command before it runs (or, under a backend that only observes the build, once it has started) and once it has run, and when the build ends. A handler that decides runs each command as it is, runs it modified, drops it, or aborts the build; one that does not only observes.
For details on the architecture concepts, capture backends, and the IPC flow, see the design documentation and Capture backends.
