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 locally. This also downloads recent versions of cmake and ninja, and sets CMAKE_GENERATOR=Ninja by default. Compiling libCat is only routinely tested using ninja, but other build systems may work. The "Ninja Multi-Config" generator is also supported.

mise install-toolchain
cmake -B build/
# mise x -- cmake -B build/
cmake --build build/  
./build/tests/unit_tests
# or ctest --test-dir build/ --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.

Developers are encouraged to set CAT_USE_SANITIZERS (default OFF).

cmake -B build/ -DCAT_USE_SANITIZERS=ON

This will compile every translation unit with AddressSanitizer + UndefinedBehaviorSanitizer. Mutually exclusive with link time optimization. Turning this off in Release / RelWithDebInfo will enable LTO.

Tools

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

cat-format

cmake --build build/ --target cat-format

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

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. This is only applied to libCat sources, so it is not recommended to configure this unless it failed to find a suitable version.

cat-format-check

cmake --build build/ --target cat-format-check

The read-only variant of cat-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.

cat-restyle-comments

cmake --build build/ --target cat-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.

It is idempotent and compatible with our .clang-format comment formatting rules.

cat-restyle-comments-check

cmake --build build/ --target cat-restyle-comments-check

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

cat-tidy

cmake --build build/ --target cat-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.

CMake automatically attempts to find an appropriate version of clang-tidy and run-clang-tidy on PATH (both ship together in the clang-tools-<N> apt package). Override either with -DCAT_CLANG_TIDY_PATH=/path/to/clang-tidy or -DCAT_RUN_CLANG_TIDY_PATH=/path/to/run-clang-tidy. These are only applied to libCat sources, so it is not recommended to configure them unless discovery failed.

cat-tidy-check

cmake --build build/ --target cat-tidy-check

The read-only variant of cat-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. Fix the reported issues (or run cat-tidy to apply the auto-fixable subset).

cat-opt-report

cmake --build build/ --target cat-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.

cat-intermediaries

cmake --build build/ --target cat-intermediaries

Saves compilation byproducts to the build directories. For example:

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.

cat-syntax

cmake --build build/ --target cat-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.

cat-repl

cmake -B build/ -DCAT_BUILD_SHARED=ON
cmake --build build/ --target cat-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.

For scripted use, the wrapper script also accepts a one-shot --eval / --eval-file flag that runs the supplied snippets and exits, e.g.

./build/clang-repl-libcat --eval \
    '#include <cat/string>
     auto _ = cat::println("Meow world!");'

# Meow world!

Piping code on stdin works the same way

echo "1 + 1" | ./build/clang-repl-libcat

# 2

Note this requires CAT_BUILD_SHARED=ON. 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.

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.