clice-io/catter

Dernière activité source enregistrée: 31 octobre 2026 à 18:04

Catalogue SkillsMP mis à jour: 9 novembre 2026 à 14:22

skills collectés: 13

Étoiles GitHub: 36
Forks GitHub: 4

Installer avec un assistant IA

Copiez ce prompt dans l’assistant IA que vous utilisez.

Follow https://skillsmp.com/skill-install/prompt.md to install Agent Skills from https://github.com/clice-io/catter.

README du dépôt

Fichier source du README : README.md

Lire le README source

Afficher le README complet

# Catter: A New Build Process Interception Tool ![C++ Standard](https://img.shields.io/badge/C++-23-blue.svg) [![GitHub license](https://img.shields.io/github/license/clice-io/catter)](https://github.com/clice-io/catter/blob/main/LICENSE) [![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/clice-io/catter) > [!IMPORTANT] > This project is under active development. Stay tuned for future updates! ## Motivation We are developing a new C++ language server, [clice](https://github.com/clice-io/clice). For it to work correctly, users often need to provide a [Compilation Database (CDB)](https://clang.llvm.org/docs/JSONCompilationDatabase.html). This is a JSON file that records the compilation commands for all source files. Unfortunately, not all C++ build systems support the generation of CDB files. For example, CMake only supports this feature when using `Makefile` or `Ninja` as the build backend. Furthermore, C++ has many other popular build systems, and many of them do not natively support CDB generation, often requiring special workarounds. In some situations, you might not even be able to access a CDB even if it is generated; for instance, when a Python package builds C++ code, you often have no control over the build directory and thus cannot retrieve the corresponding CDB file. Moreover, even with a CDB, a language server might still not function correctly. A classic example is LLVM. Why? Because LLVM uses its own compiled `tablegen` tool for code generation. The generated files are placed in a specific directory, which is then added to the compilation flags with `-I`. This means that if you only run `cmake configure`, these generated files will be missing, causing the language server to fail. You must run `cmake build` to generate them. Unfortunately, it's difficult to configure LLVM to _only_ generate these necessary headers for a minimal build, especially if your goal is just to read the code. A full build of LLVM takes a very long time. It would be ideal if we could build only the minimal required components. Currently, there is no cross-platform tool that completely solves all these issues. This is why we decided to create `catter`. ## Core Features `catter`'s underlying principle is similar to [Bear](https://github.com/rizsotto/Bear) or [scan-build](https://github.com/rizsotto/scan-build). It works by using hooks to intercept any child process creation (including compilation tasks) initiated by the target process. Every captured command goes to handlers: catter's built-ins, or programs of your own in any language, which process these events—for example, to log or modify compilation arguments, analyze build times, and so on. Although its initial motivation was to record compilation commands to generate a CDB, we quickly realized it could be used for much more: - **Analyze Linker Commands to Infer Target Information**: By capturing linker commands, `catter` can analyze the dependency graph between targets. This provides richer target information, which is essential for language servers to properly support C++20 modules. The C++ standard stipulates that a program can have at most one module with the same name, and it is the target information that distinguishes different programs (e.g., libraries vs. executables). This crucial information is missing from the current CDB standard, with no prospects for improvement in the near future. With `catter`, we can solve this problem once and for all, across all build systems. - **Perform "Fake" Compilations**: Instead of forwarding compilation tasks to the actual compiler, `catter` can generate fake placeholder object files. This allows the build system to proceed with its tasks without performing a full, time-consuming compilation. This way, you can obtain a complete CDB without waiting for the entire build process to finish. **Note**: If the build involves code generators, those tools must still be genuinely built. `catter` can automatically analyze dependencies to ensure that only these essential tools are compiled, achieving a true minimal build. - **Profile the Build Process**: Due to issues in the build system's design or poorly written build scripts, the actual degree of build parallelism can be very low. `catter profile` records when each command started, how long it ran and which command started it, and writes a trace you open in Perfetto or `chrome://tracing` to inspect the build's parallelism, its critical path and its slowest steps. - **Patch the Build Process with Custom Handlers**: Users can write their own handlers, in Python, TypeScript or any language that speaks catter's protocol, to patch any command during the build process. This gives you the power to dynamically modify arguments, redirect commands, or inject custom logic into your build without altering the original build files. ## Quick Start Download a prebuilt package for your platform from the [GitHub Releases](https://github.com/clice-io/catter/releases) page, extract it, and make sure the `catter` executable is available on your `PATH`. **Platforms:** Linux (x64), macOS (ARM64), Windows (x64, ARM64) **Release channels:** | Channel | Version | Where to get it | | -------------- | --------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | **Stable** | even minor, e.g. `v0.2.0` | [releases page](https://github.com/clice-io/catter/releases) — none yet | | **Nightly** | odd minor, e.g. `v0.1.2026102902` | [GitHub pre-releases](https://github.com/clice-io/catter/releases) | | **Per-commit** | untagged | artifacts on the [latest green `main` CI runs](https://github.com/clice-io/catter/actions/workflows/main.yml?query=branch%3Amain+is%3Asuccess) | Nightly patch numbers encode the UTC time they were tagged as `YYYYMMDDHH` (year, month, day, hour — e.g. `2026102902` is 2026-10-29 02:00 UTC), so newer is always higher; a nightly is published each day `main` gained tested builds, and nightlies older than 30 days or beyond the newest 25 are deleted, but for the newest one. Every published binary is the exact one that passed the full test suites — releases promote CI builds rather than rebuilding. Generate a compilation database by running your normal build command through `catter`: ```bash catter compile-commands -o compile_commands.json -- make ``` For CMake projects, wrap the build step in the same way: ```bash catter compile-commands -o compile_commands.json -- cmake --build build ``` To see the build's timeline, profile it, and open the `trace.json` it writes in [Perfetto](https://ui.perfetto.dev): ```bash catter profile -- make -j8 ``` The general command format is: ```bash catter <command> [options] -- <build-command> ``` Here, `compile-commands` is the command that writes a compilation database, `-o` sets the output path, and everything after `--` is the build command to intercept. `catter --help` lists the commands, and `catter <command> --help` the options of one. ## Building To build `catter` from source, install [pixi](https://pixi.prefix.dev/) and Git. pixi provides the development environment and task entrypoints, and Bazel, which pixi's tasks run, drives the C++ build with [xclang](https://github.com/clice-io/xclang)'s toolchain. ```bash git clone https://github.com/clice-io/catter.git cd catter pixi run -e dev build # Build into build/RelWithDebInfo/bin/bin pixi run -e dev build Debug # Or the ASan build, into build/Debug/bin/bin ```

Chargement du README du dépôt…

Skills dans ce dépôt

classification en attente

skill

métier

description

mis à jour

cpp-style

non classé

Read before writing, modifying or reviewing any C++ code — redundancy (the rule we care most about), files, what the hook and proxy must preserve, errors and defense, async, logging and output, naming, words, templates, API preferences.