libCat 🐈‍⬛

libCat is a non-POSIX compliant C++26 runtime. It has no pthreads nor global malloc(), and currently does not support exceptions. It has type-safe arithmetic, SIMD, fast syscalls, CRTP interfaces,

Building

libCat requires a recent development version of Clang 23 from the trunk branch. mise can be used to fetch an appropriate version. This also installs just, recent versions of build tools, and sets CMAKE_GENERATOR=Ninja Multi-Config by default, but setting CMAKE_GENERATOR is supported (e.g. CMAKE_GENERATOR=Ninja) for all tools and in all release modes. mise is not required, but is highly recommended.

mise install
just build
./build/Release/tests/unit_tests
# or ctest --test-dir build/ -C Release --output-on-failure

The .clang-format and .clang-tidy configurations are only compatible with correspondingly recent builds of clang-tools.

Currently, running libCat requires AVX2. On x86 microarchitectures lacking that, the Intel Software Development Emulator is known to work for libCat binaries. mise does not install this emulator.

just can configure release modes with one or more optional release mode arguments. If no mode argument is passed, just reuses the last explicit mode from this worktree, defaulting to release. Pass -v to show verbose CMake configure messages and build commands.

just build debug
just build release
just build relwithdebinfo

just build all -v
just build debug -v

Developers of libCat are encouraged to enable sanitizers with san. Use nosan to disable them again. If neither argument is passed, CMake keeps the cached CAT_USE_SANITIZERS setting. The order of this argument is arbitrary to the build modes.

just build san
just build nosan

just build san debug
just build debug san release

This will compile every translation unit with AddressSanitizer + UndefinedBehaviorSanitizer. Note that enabling these disables link-time optimization in release and relwithdebinfo.

In an initial build, sanitizers are not enabled. This state may be restored by:

just clean
just clean release
just clean all

Additional optiization or warning flags can be passed in anywhere in the command. -w is special, and disables all compiler warnings in the REPL. These flags are set in the CMake cache, except for -w, which must be used explicitly whenever it is desired.

just build -fomit-frame-pointer -fstrict-bool san -Wno-unused-variable
just build -w release

Tools

libCat provides several developer utilities. They are organized in the cmake/ subdirectory.

The just recipes below use the same build modes as the build recipe. For many of them, build mode is not very relevant. They are implemented as CMake targets, which have the same names prepended by a cat- namespace (e.g. cat-format, cat-syntax).

format

just format

Runs clang-format in place on every libCat implementation source and public header. The files which changed are reported afterwards.

When not using mise, CMake automatically attempts to find an appropriate version of clang-format on PATH. Override its choice with -DCAT_CLANG_FORMAT_PATH=/path/to/clang-format.

format-check

just format-check

The dry-run variant of format primarily intended for CI. Performs the same comparison as cat-format, but instead of rewriting, it reports every file that would be reformatted. If one or more files are reported, then the script exits with an error code.

restyle-comments

just restyle-comments

clang-format does not aggressively merge erroneous line breaks in comments, which are common after mass refactoring. cat-restyle-comments performs more aggressive formatting of comments alone, including project comment spelling rules, but like clang-format it respects blank lines between paragraphs and URL coherence. The ordered style rules are documented at the top of scripts/restyle_prefix_comment_paragraphs.py.

restyle-comments-check

just restyle-comments-check

The dry-run variant, same idea as format-check, reports would restyle: ... for any file where comment restyling would change. Run restyle-comments to fix drift.

tidy

just tidy

Runs clang-tidy across every libCat translation unit via the run-clang-tidy driver, applying fix-its in place and re-formatting touched lines with the project’s .clang-format rules. Uses the build directory’s compile_commands.json, which the tidy target forces CMake to emit.

When not using mise, CMake automatically attempts to find an appropriate version of clang-tidy and run-clang-tidy on PATH. Override either with -DCAT_CLANG_TIDY_PATH=/path/to/clang-tidy or -DCAT_RUN_CLANG_TIDY_PATH=/path/to/run-clang-tidy.

tidy-check

just tidy-check

The dry-run variant of tidy primarily intended for CI. Runs the same clang-tidy pass with -warnings-as-errors=* so any diagnostic exits the script with an error code.

opt-report

just opt-report

Compiles a Clang optimization report and prints the opt-viewer.py invocation required to render the resulting record into an interactive HTML document. Optview2 is not distributed with LLVM, but it may be preferred with this output. CMake attempts to use the same version of this script assosciated with your Clang installation.

intermediaries

just intermediaries
just intermediaries fmt
just intermediaries no-fmt

Saves compilation byproducts to build directories. fmt is unfortunately very slow, so it is disabled by default. Pass fmt to format the resulting .ii files.

build/runtime/_start.ii
build/string/memset.ii
build/string/memset.bc
build/string/memset.s
build/linux/syscall0.ii
build/tests/test_alloc.ii
build/examples/hello.ii

• <file>.ii - preprocessed C++ headers and translation units.
• <file>.bc - LLVM IR bitcode handed to the optimizer.
• <file>.s - target assembly emitted by codegen, equivalent to generated machine code in .o files.

This is useful for manually inspecting macro expansion and optimization, among other purposes.

syntax

just syntax

Compiles a libCat with -fsyntax-only. This is useful for quickly checking if code can compile, without bothering to enter deep LLVM. It will reuse existing precompiled headers, if they are enabled, further accelerating the development loop.

repl

just repl

Launches clang-repl with libCat preloaded so its headers and external linkage symbols resolve at JIT time. The wrapper reads the matching compile flags from the build’s compile_commands.json so the REPL parses the same C++26 / freestanding / SIMD-intrinsic dialect libCat was built against, and pre-loads the ASan runtime when sanitizers are on. This produces a clang-repl-libcat executable that can be called independantly, if desired.

For use in scripts, pass a one-shot snippet or readable path as the final argument, after any conventional clang-repl arguments.

just repl \
    '#include <cat/string> \
     auto _ = cat::println("Meow world!");'

# Meow world!

The input code or file must be in quotes. clang-repl flags are forwarded through automatically.

just repl "1 + 1"
just repl -Wno-unused-variable "1 + 1"
just repl -w
just repl san -fstrict-bool "bool b = 2;"
just repl build/Debug/examples/hello.cpp
just repl "1 + 1"

skip-main prevents evaluating main(). Use drop to evaluate the input, then stay in the REPL.

just repl drop skip-main build/Debug/examples/hello.cpp
# ...
clang-repl> main();

# Hello, world!

Piping code on stdin works the same way.

echo "1 + 1" | just repl release

# 2

The just repl recipe configures the build with CAT_BUILD_SHARED=ON before building the wrapper. Pass extra clang-repl arguments at the end of the command, after a --.

cat-gdb-tests

This target does not require manual invocation. CMake symlinks a .gdbinit configuration that loads GDB pretty printers from gdb_pretty_printers/cat_printers.py to every CMake build directory automatically, granted that the user’s GDB is configured with set auto-load local-gdbinit on. It is registered with ctest.

Other build options

All build options are CMake cache variables; pass them with -D at configure time.

PCH and caching

• CAT_PCH (default ON) - Enable precompiled headers for libCat’s internal build. Private to libCat; downstream consumers of cat keep their own PCH strategy intact whether this is on or off.
• CAT_USE_SCCACHE (default: ON if sccache is on PATH, else OFF) Use sccache as the C++ compiler launcher. Combined with -Xclang -fno-pch-timestamp (added automatically for Clang + PCH builds), this gives near-100% hit rates across build directories and fresh checkouts. Override the binary with -DCAT_SCCACHE_EXECUTABLE=/path/to/sccache.

Library output

• CAT_BUILD_SHARED (default OFF) - Also build libCat as a shared library alongside the default static archive. Required for the cat-repl target. Off by default so the build stays cheap when nobody needs the shared form.
• CAT_USE_SHARED (default OFF) - Link cat against the shared library instead of the static archive, so every in-tree consumer and downstream find_package(cat) user that links cat transparently picks it up. Implies CAT_BUILD_SHARED.

Tests and examples

• CAT_BUILD_UNIT_TESTS (default ON) - Compile the unit_tests binary registered with ctest as UnitTests.
• CAT_BUILD_ALL_EXAMPLES (default ON) - Shortcut that compiles every individual example below.
• CAT_BUILD_EXAMPLE_HELLO / _ECHO / _CLIENT_SERVER / _WINDOW / _CAT (default OFF) - Per-example opt-ins for fine-grained selection when CAT_BUILD_ALL_EXAMPLES=OFF.
• CAT_BUILD_LIBC_EXAMPLES (default OFF) - Build the libc-linked comparison binaries (hello_libc, memcpy_libc, …) used to A/B performance against the freestanding libCat versions.

Tooling overrides

• CAT_LIBCAT_JOBS - Worker count for cat-format, cat-restyle-comments, and cat-restyle-comments-check (capped at 4 in the scripts to limit RAM use, e.g. on WSL2). Use 1 or 2 for tighter machines, or the script -j flag, which is also capped at 4.
• CAT_CLANG_FORMAT_PATH - Path to a specific clang-format binary (defaults to whatever cmake auto-discovers on PATH). Only consulted by the cat-format / cat-format-check targets. cat-restyle-* is separate, uses find_program for python3, and has no -D override.
• CAT_CLANG_TIDY_PATH / CAT_RUN_CLANG_TIDY_PATH - Paths to specific clang-tidy and run-clang-tidy binaries (default to auto-discovery on PATH). Only consulted by the cat-tidy / cat-tidy-check targets.
• CAT_SCCACHE_EXECUTABLE - Path to a specific sccache binary (defaults to find_program on PATH). Only consulted when CAT_USE_SCCACHE=ON.