compiletools

compiletools

C/C++ build tools that requires almost no configuration.

NOTE:: The repository-level README.rst is a symlink to this file, so they are the same canonical document.
Author:: drgeoffathome@gmail.com
Date:: 2026-05-09
Version:: 13.1.4
Manual section:: 1
Manual group:: developers

SYNOPSIS

ct-* [compilation args] [filename.cpp] [–variant=<VARIANT>]

DESCRIPTION

compiletools provides C/C++ build automation with minimal configuration. The tools automatically determine source files, dependencies, and build requirements by analyzing your code.

To build a C or C++ project, simply type:

ct-cake

This automatically determines source files, builds executables, and runs tests. See ct-cake(1) for details.

QUICK START

Try compiletools without installing using uvx:

uvx --from compiletools ct-cake
uvx --from compiletools ct-compilation-database

This runs tools directly without affecting your system. All ct-* tools work with uvx (e.g., uvx --from compiletools ct-config).

INSTALLATION

uv pip install compiletools

Or for development:

git clone https://github.com/DrGeoff/compiletools
cd compiletools
uv pip install -e ".[dev]"

EXAMPLES

Two example trees ship with the package:

src/compiletools/examples-end-to-end/ — buildable mini-projects exercising the full ct-cake --auto pipeline (PCH, C++20 modules, static / dynamic libraries, multi-target apps, sanitizer variants, pkg-config, …). Each has a README describing what it demonstrates; cd into one and run ct-cake to see the build flow end-to-end.
src/compiletools/examples-features/ — focused, fixture-style projects for individual magic-flag annotations and config features (//#PKG-CONFIG=, //#LDFLAGS=, //#PCH=, //#GIT=, append-style variables, …). Useful as copy-paste templates when adding the same feature to your own project.

The examples_registry Python module (example_path(), example_file()) maps these trees from test code; tests under src/compiletools/test_*.py use them as fixtures, so each example is also a worked CI-verified configuration.

KEY FEATURES

Magic Comments: Embed build requirements directly in source files using special comments like //#LDFLAGS=-lpthread or //#PKG-CONFIG=zlib, or pull in an external git repository with //#GIT=<url>. See ct-magicflags(1) and the worked example in src/compiletools/examples-end-to-end/sudoku_tui/.
Automatic Dependency Detection: Traces #include statements to determine what to compile and link. No manual dependency lists needed.
Build Variants: Support for debug, release, and custom build configurations. Use --variant=release to select. See ct-config(1).
Pluggable Build Backends: Choose from the builtin Shake backend (default), Make, Ninja, CMake, or Bazel. Use --backend=<name> to select. See ct-backends(7).
Content-Addressable Caching: Objects, precompiled headers, C++20 module BMIs, and the linker artefacts themselves (executables, static libs, shared libs) are cached in per-variant content-addressable directories (cas-objdir, cas-pchdir, cas-pcmdir, cas-exedir). Cache keys are anchored to the git root, so identical translation units share entries even when the workspace is moved or cloned to a new path. Combined with the default --use-mtime=False, fresh-checkout CI builds (where every source has mtime=now) hit the cache instead of re-running the producer. Trim with ct-trim-cache.
C++20 Modules: First-class support for clang .pcm and gcc .gcm BMI artefacts – including named modules, partitions, header units, and import std – with automatic discovery from import / export module in your sources. See the C++20 Modules Caching section in ct-cake(1).
Precompiled Headers: Mark headers with //#PCH= and ct-cake builds them once and shares them across the project via cas-pchdir.
File Locking: Multi-user/multi-host object file caching with filesystem-aware locking for faster builds in team environments. Enable with file-locking = true.
Minimal Configuration: Works out-of-the-box with sensible defaults. Configuration only needed for customization.

CORE TOOLS

ct-cake: Main build tool. Auto-detects targets, builds executables, runs tests.
ct-compilation-database: Generate compile_commands.json for IDE integration. Auto-detects targets.
ct-config: Inspect configuration resolution and available compilation variants.
ct-magicflags: Show magic flags extracted from source files.
ct-fetch: Clone, update, or report the //#GIT= external git repositories a target tree depends on, without running a build.
ct-headertree: Visualize include dependency structure.
ct-filelist: Generate file lists for packaging and distribution.
ct-timing-report: Analyze build timing data from ct-cake --timing. Interactive TUI, static summary, run comparison, and Chrome Trace export.
ct-trim-cache: Trim aged entries from the object, PCH, PCM, and linker-artefact content-addressable caches with configurable retention.
ct-cache-report: Summarize content-addressable cache occupancy and flag duplication in the object, PCH, PCM, and linker-artefact caches.
ct-debug-pcm-hash-inputs: Dump the seven inputs that drive a C++20 module BMI’s <cas-pcmdir>/<cmd_hash>/ cache path as JSON. Run twice across back-to-back ct-cake invocations and diff the outputs to identify which input drifted when a BMI lands under a fresh subdir on unchanged source.
ct-cas-publish: Helper invoked from generated build recipes: atomically publish a cas-exedir entry to a user-facing bin/<variant>/<name> path via link() + rename(), with EXDEV-only symlink fallback. Not normally run by hand.
ct-cleanup-locks: Clean stale locks from file locking.
ct-check-venv: Verify that the ct-cake on PATH imports the same compiletools as the active venv. Run after git worktree add and a fresh uv pip install -e . to confirm subprocess-driven tools see the expected source tree.
ct-list-backends: List available build backends (make, ninja, cmake, bazel, shake).
Shell Wrappers: Convenience scripts in scripts/: ct-build, ct-build-static-library, ct-build-dynamic-library, ct-watch-build, ct-lock-helper, ct-release.

CONFIGURATION

Options are parsed using ConfigArgParse, allowing configuration via command line, environment variables, or config files.

Configuration hierarchy (lowest to highest priority):

Executable directory (ct/ct.conf.d alongside the ct-* executable)
System config (/etc/xdg/ct/)
Python virtual environment (${python-site-packages}/ct/ct.conf.d)
Package bundled config (<installed-package>/ct.conf.d)
User config (~/.config/ct/)
Project config (<gitroot>/ct.conf.d/)
Git repository root directory
Current working directory, and the nearest-ancestor ct.conf / ct.conf.d of every explicit or –auto-discovered build target (target-anchored layers; same priority tier as the current working directory)
Environment variables (capitalized, e.g., VARIANT=release)
Command-line arguments

All loaded configuration applies to the whole invocation — there is no per-translation-unit scoping. Because target-anchored layers and the current-working-directory layer share one tier, they must agree: if two same-tier config files set the same key to different values (including append-/prepend- keys), the tools stop with an error naming both files and the two remedies (build the subprojects separately, or make the values identical).

For a target outside any git repository (or under --no-git-root) the ancestor walk is bounded only by the filesystem root; a layer it finds at or above your home directory triggers an unconditional ct: warning: because such a file (e.g. a forgotten ~/ct.conf) is almost certainly stray — legitimate user-level config belongs in ~/.config/ct/.

Build variants are composed from axis conf files — one per orthogonal concern: toolchain (gcc, clang), linker (ld, gold, mold, wild), optimization (debug, release), instrumentation (asan, ubsan, tsan, coverage, lto). --variant=gcc,debug,asan (or gcc.debug.asan or gcc debug asan — comma, dot, and whitespace are all equivalent) synthesizes the composition from gcc.conf + debug.conf + asan.conf. No per- combination conf file is required.

Common usage:

ct-cake --variant=gcc,release             # toolchain + opt
ct-cake --variant=clang,debug,asan        # toolchain + opt + sanitizer
ct-cake --variant=gcc,mold,release,lto    # everything composes
ct-cake --append-CXXFLAGS="-march=native"

For details on configuration hierarchy, file format, and variant system, see ct-config(1).

ATTRIBUTION

This project is derived from the original compiletools developed at Zomojo Pty Ltd (between 2011-2019). Zomojo ceased operations in February 2020. This repository continues the development and maintenance of the compiletools project.

Release files for compiletools 13.1.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for compiletools 13.1.4
File	Size	Uploaded
compiletools-13.1.4.tar.gz	3.8 MB	Aug 28, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for compiletools 13.1.4
File	Interpreter	ABI	Platform	Reset
compiletools-13.1.4-py3-none-any.whl 4.2 MB Aug 28, 2026	Python 3	none	any	Details

Total release size: 7.9 MB

Release files / compiletools-13.1.4.tar.gz

Download URL	compiletools-13.1.4.tar.gz
Size	3.8 MB
Tags	Source
SHA-256 checksum How to use checksums	`c4e6c7ff2a5ff8dca37e35e89611942baf3281d46643dcc6b7240beadfb45c46`
BLAKE2b-256 checksum How to use checksums	`d9ff8cecb18436932db85b5bc405550984f07e6278209d4d2065e3487ff7920b`
Upload date	Aug 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Fedora Linux","version":"44","id":"","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`

Release files / compiletools-13.1.4-py3-none-any.whl

Download URL	compiletools-13.1.4-py3-none-any.whl
Size	4.2 MB
Tags	Python 3
SHA-256 checksum How to use checksums	`4e97ccb92711037b50b0e371700a5a3cec79be4a6776ce8da63000f623c5fb7f`
BLAKE2b-256 checksum How to use checksums	`524c7b95168d85dd7de676e88c5c74a6a67fcd340d6de0f12d4fa0a0c4adeb97`
Upload date	Aug 28, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`uv/0.12.3 {"installer":{"name":"uv","version":"0.12.3","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Fedora Linux","version":"44","id":"","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}`