Clang Tool Chain

May 19, 2026 · View on GitHub

Run C++ like a shell script. Build once, run everywhere. The entire C/C++/WASM toolchain in one pip install.

#!/usr/bin/env -S uvx clang-tool-chain-build-run --cached

#include <iostream>
int main() {
    std::cout << "Hello, World!\n";
}

chmod +x hello.cpp && ./hello.cpp  # That's it. No makefiles, no build steps.
# First run auto-installs clang-tool-chain via uvx (only needs: pip install uv)

Build Actually Portable Executables with Cosmopolitan:

clang-tool-chain-cosmocc hello.c -o hello.com
# This .com file runs natively on Windows, Linux, macOS, FreeBSD - unchanged.

One pip install, 35+ tools auto-download: Full Clang/LLVM 21 • Complete Emscripten/WASM pipeline • IWYU • clang-format/tidy • LLDB debugger • Cosmopolitan libc • Native C++ launcher for zero-overhead builds • No admin rights needed • Works offline after first use

⚡ Quick Start

# Install
pip install clang-tool-chain

# Compile C/C++ - toolchain auto-downloads on first use (~71-91 MB)
clang-tool-chain-c hello.c -o hello
clang-tool-chain-cpp hello.cpp -o hello
./hello

Build systems: Set CC=clang-tool-chain-c and CXX=clang-tool-chain-cpp for Make/CMake/Meson.

WebAssembly: clang-tool-chain-emcc game.c -o game.js && node game.js

Portable executables: clang-tool-chain-cosmocc hello.c -o hello.com (runs on Windows/Linux/macOS/FreeBSD)

Executable scripts: Add shebang #!/usr/bin/env -S uvx clang-tool-chain-build-run --cached to C++ files.

📖 Complete Quick Start Guide - Detailed examples, CMake integration, workflows, tips.

📊 Test Matrix

Comprehensive test coverage across all platforms and tool categories ensures reliability and quality.

48 GitHub Actions workflows covering all platform+tool combinations:

5 platforms: Windows x64, Linux x86_64, Linux ARM64, macOS x86_64, macOS ARM64
13 tool categories: clang, clang-sccache, emscripten, emscripten-sccache, iwyu, lldb, format-lint, binary-utils, cosmocc, lib-deploy, libunwind, valgrind, cosmocc+valgrind

Live Test Status

Tool Category	Windows x64	Linux ARM64	macOS x86_64	macOS ARM64
clang
clang+sccache
emscripten
emscripten+sccache
iwyu
format-lint
binary-utils
lldb
cosmocc
lib-deploy
libunwind
valgrind	N/A (Docker)		N/A (Docker)	N/A (Docker)
cosmocc+valgrind	N/A	N/A	N/A	N/A

📖 Complete Test Matrix Documentation - Tool category descriptions, test organization, running tests locally.

📋 All Commands (44 Total)

Comprehensive reference of all available commands organized by category.

Compiler Commands (6)

Command	Description
`clang-tool-chain-c`	C compiler (GNU ABI, cross-platform)
`clang-tool-chain-cpp`	C++ compiler (GNU ABI, cross-platform)
`clang-tool-chain-c-msvc`	C compiler (MSVC ABI, Windows only)
`clang-tool-chain-cpp-msvc`	C++ compiler (MSVC ABI, Windows only)
`clang-tool-chain-cosmocc`	C compiler for Actually Portable Executables
`clang-tool-chain-cosmocpp`	C++ compiler for Actually Portable Executables

Compiler Commands with sccache (5)

Command	Description
`clang-tool-chain-sccache-c`	Cached C compiler (GNU ABI)
`clang-tool-chain-sccache-cpp`	Cached C++ compiler (GNU ABI)
`clang-tool-chain-sccache-c-msvc`	Cached C compiler (MSVC ABI, Windows only)
`clang-tool-chain-sccache-cpp-msvc`	Cached C++ compiler (MSVC ABI, Windows only)
`clang-tool-chain-sccache-stats`	Display sccache statistics

Build Utilities (3)

Command	Description
`clang-tool-chain-build`	Build source files with caching
`clang-tool-chain-build-run`	Build and execute with caching
`clang-tool-chain-run`	Execute cached binary (no rebuild)

Binary Utilities (14)

Command	Description
`clang-tool-chain-ar`	Create, modify, extract from archives (llvm-ar)
`clang-tool-chain-ranlib`	Generate archive symbol index (llvm-ranlib)
`clang-tool-chain-nm`	Display symbol table (llvm-nm)
`clang-tool-chain-objdump`	Disassemble and analyze binaries (llvm-objdump)
`clang-tool-chain-readelf`	Display ELF file information (llvm-readelf)
`clang-tool-chain-readobj`	Display object file information (llvm-readobj)
`clang-tool-chain-size`	Display section sizes (llvm-size)
`clang-tool-chain-strings`	Extract printable strings (llvm-strings)
`clang-tool-chain-strip`	Remove symbols from binaries (llvm-strip)
`clang-tool-chain-cxxfilt`	Demangle C++ symbols (llvm-cxxfilt)
`clang-tool-chain-symbolizer`	Symbolize stack traces (llvm-symbolizer)
`clang-tool-chain-dlltool`	Generate import libraries from .def files (llvm-dlltool)
`clang-tool-chain-lib`	MSVC-compatible library manager (llvm-lib)
`clang-tool-chain-gendef`	Generate .def files from DLL export tables

Format & Lint (2)

Command	Description
`clang-tool-chain-format`	Format C/C++ code (clang-format)
`clang-tool-chain-tidy`	Static analysis and linting (clang-tidy)

IWYU - Include Analyzer (3)

Command	Description
`clang-tool-chain-iwyu`	Analyze #include usage (include-what-you-use)
`clang-tool-chain-iwyu-tool`	Run IWYU on compilation database
`clang-tool-chain-fix-includes`	Auto-fix includes from IWYU output

LLDB - Debugger (2)

Command	Description
`clang-tool-chain-lldb`	Interactive debugger and crash analyzer (lldb)
`clang-tool-chain-lldb-check-python`	Verify Python 3.10 integration status

Emscripten - WebAssembly (5)

Command	Description
`clang-tool-chain-emcc`	Emscripten C compiler (C/C++ → WebAssembly)
`clang-tool-chain-empp`	Emscripten C++ compiler (C/C++ → WebAssembly)
`clang-tool-chain-emar`	Emscripten archiver for WebAssembly libraries
`clang-tool-chain-sccache-emcc`	Cached Emscripten C compiler
`clang-tool-chain-sccache-empp`	Cached Emscripten C++ compiler

Valgrind - Dynamic Analysis (2)

Command	Description
`clang-tool-chain-valgrind`	Memory error detector (via Docker)
`clang-tool-chain-callgrind`	Call graph profiler with auto-annotation (via Docker)

Management & Diagnostics (6)

Command	Description
`clang-tool-chain`	Main CLI (install, purge, info, help)
`clang-tool-chain-test`	Run diagnostic tests (7 checks)
`clang-tool-chain-fetch`	Download toolchain components
`clang-tool-chain-paths`	Display installation paths
`clang-tool-chain-libdeploy`	Deploy runtime library dependencies after the fact
`clang-tool-chain-compile-native`	Compile native C++ launcher for zero-overhead builds

Total: 44 commands providing complete C/C++/WebAssembly toolchain capabilities.

📑 Table of Contents

Getting Started

Quick Start
Test Matrix - Live CI/CD status for all platforms
All Commands - Complete command reference
Installation
Why clang-tool-chain?

Tools by Category

Clang/LLVM Toolchain - C/C++ compilation (17 commands)
Build Utilities - build, build-run, run (3 commands)
Binary Utilities - ar, nm, objdump, strip, readelf, dlltool, gendef (14 commands)
Format & Lint - clang-format, clang-tidy (2 commands)
IWYU - Include analyzer (3 commands)
LLDB - Debugger with Python support (2 commands)
Emscripten - WebAssembly compiler (5 commands)
Native Emscripten Launchers - Zero-overhead emcc/wasm-ld (3 binaries)
Cosmopolitan - APE compiler (2 commands)
Valgrind & Callgrind - Dynamic analysis (2 commands)
Management CLI - install, purge, info, test (4 commands)

🛠️ Clang/LLVM Toolchain

17 commands • Modern C/C++ compiler • Auto SDK detection • GNU/MSVC ABI • sccache support

Platform & Version Matrix

Platform	Architecture	LLVM Version	Archive Size	Linker	Extras	Status
Windows	x86_64	21.1.5	~71-90 MB	lld	MinGW sysroot	✅ Stable
Linux	x86_64	21.1.5	~87 MB	lld	libunwind (bundled)	✅ Stable
Linux	ARM64	21.1.5	~91 MB	lld	libunwind (bundled)	✅ Stable
macOS	x86_64	21.1.6	~77 MB	ld64.lld	-	✅ Stable
macOS	ARM64	21.1.6	~71 MB	ld64.lld	-	✅ Stable

Windows ABI Selection

Feature	GNU ABI (Default)	MSVC ABI
Commands	`clang-tool-chain-c/cpp`	`clang-tool-chain-c/cpp-msvc`
Cross-platform	✅ Yes	❌ Windows only
Visual Studio	❌ Not needed	✅ Required
MinGW Headers	✅ Integrated (~176 MB)	❌ N/A
DLL Deployment	✅ Automatic	❌ Uses MSVC runtime
C++ Standard	✅ C++11+	✅ C++14+
Use Case	Cross-platform projects	Windows-native MSVC projects

Quick Examples

# GNU ABI (cross-platform, default)
clang-tool-chain-cpp hello.cpp -o hello

# MSVC ABI (Windows native)
clang-tool-chain-cpp-msvc main.cpp -o program.exe

# Build system integration
export CC=clang-tool-chain-c CXX=clang-tool-chain-cpp

📖 Complete Documentation - Command reference, environment variables, SDK detection, ABI selection, sanitizers, build system integration.

🔨 Build Utilities

3 commands • SHA256 caching • Shebang support • Auto-run

clang-tool-chain-build-run --cached hello.cpp
chmod +x script.cpp && ./script.cpp

📖 Complete Documentation - Caching details, shebang setup, TDD workflows.

🔧 Binary Utilities

14 commands • LLVM binary tools • ELF/PE/Mach-O support • Archives & symbols • Import library generation

clang-tool-chain-ar rcs libmylib.a obj1.o obj2.o
clang-tool-chain-nm --demangle program
clang-tool-chain-objdump -d program

Filtering DLL Export Tables

When building shared libraries with --export-all-symbols, unwanted symbols (e.g. std:: template instantiations) leak into the export table, bloating the import library. Use gendef + dlltool to filter them:

# 1. Build DLL (exports everything, including std:: symbols)
clang-tool-chain-cpp -shared -Wl,--export-all-symbols -o mylib.dll mylib.cpp

# 2. Extract .def file from DLL
clang-tool-chain-gendef mylib.dll              # -> mylib.def

# 3. Filter unwanted symbols (remove std:: mangled names)
grep -v '_ZN\?K\?St' mylib.def > mylib_filtered.def

# 4. Regenerate a clean import library
clang-tool-chain-dlltool -d mylib_filtered.def -D mylib.dll -l mylib.dll.a -m i386:x86-64

📖 Complete Documentation - All commands, symbol inspection, archive creation, disassembly.

✨ Format & Lint

2 commands • clang-format • clang-tidy • Auto-formatting & static analysis

clang-tool-chain-format -i src/*.cpp
clang-tool-chain-tidy -fix file.cpp -- -std=c++17

📖 Complete Documentation - Configuration, style presets, IDE integration, CI/CD examples.

📐 IWYU (Include What You Use)

3 commands • Include analyzer • Auto-fix • Build time optimization

Platform Support Matrix

Platform	Architecture	IWYU Version	Status	Notes
Windows	x86_64	0.25	✅ Full	All features supported
Linux	x86_64	0.25	✅ Full	All features supported
Linux	ARM64	0.25	✅ Full	All features supported
macOS	x86_64	0.25	✅ Full	All features supported
macOS	ARM64	0.25	✅ Full	All features supported

Quick Examples

# Analyze includes with auto-fix
clang-tool-chain-iwyu file.cpp -- -std=c++17 | clang-tool-chain-fix-includes

# Run on entire build directory
clang-tool-chain-iwyu-tool -p build/

📖 Complete Documentation - Usage guide, CMake integration, auto-fix workflows, CI/CD.

🐛 LLDB Debugger

2 commands • Interactive debugging • Crash analysis • Python 3.10 support

Platform & Python Support Matrix

Platform	Architecture	LLDB Version	Python 3.10	Status	Notes
Windows	x86_64	21.1.5	⏳ Pending	✅ Basic	Archive rebuild needed for Python support
Linux	x86_64	21.1.5	✅ Ready	✅ Full	Wrapper complete, archives pending
Linux	ARM64	21.1.5	✅ Ready	✅ Full	Wrapper complete, archives pending
macOS	x86_64	19.1.7*	⏳ Planned	✅ Basic	Python integration planned
macOS	ARM64	21.1.6	⏳ Planned	✅ Basic	Python integration planned

* macOS x86_64 ships LLDB 19.1.7 because upstream LLVM stopped publishing macOS x86_64 prebuilts after 19.x. All other platforms track LLDB 21.x.

Python 3.10 Features: Full backtraces (bt all), Python scripting, advanced variable inspection, LLDB Python API

Quick Examples

# Compile with debug symbols
clang-tool-chain-cpp -g program.cpp -o program

# Interactive debugging
clang-tool-chain-lldb program

# Crash analysis mode (Windows)
clang-tool-chain-lldb --print crash_test.exe

# Check Python integration status
clang-tool-chain-lldb-check-python

📖 Complete Documentation - Commands, Python integration, crash analysis, platform status.

🌐 Emscripten (WebAssembly)

5 commands • C/C++ → WASM • Bundled Node.js • sccache support

Platform & Version Matrix

Platform	Architecture	Emscripten	Node.js	LLVM (bundled)	Status
Windows	x86_64	4.0.19	20.18.2	22.0.0	✅ Full
Linux	x86_64	4.0.21	20.18.2	22.0.0	✅ Full
Linux	ARM64	4.0.21	20.18.2	22.0.0	✅ Full
macOS	x86_64	4.0.19	20.18.2	22.0.0	✅ Full
macOS	ARM64	4.0.19	20.18.2	22.0.0	✅ Full

Note: Emscripten includes its own bundled LLVM 22.0.0, separate from the main clang-tool-chain LLVM (21.1.5/21.1.6).

Quick Examples

# Compile to WebAssembly
clang-tool-chain-emcc hello.c -o hello.js
node hello.js  # Run with bundled Node.js

# Browser output
clang-tool-chain-emcc game.c -o game.html

# With sccache for faster rebuilds
clang-tool-chain-sccache-emcc main.c -o main.js

📖 Complete Documentation - Usage guide, optimization, browser integration, Node.js details.

🚀 Native Emscripten Launchers

3 binaries • Zero Python/Node startup overhead • Drop-in emcc/em++/wasm-ld replacements

Native C++ launchers that bypass Python and Node.js startup overhead when compiling with Emscripten. Standard emcc invocations go through Python (~200ms overhead per call). These native launchers eliminate that overhead entirely after a one-time setup.

Binaries

Binary	Description	Aliases
`ctc-emcc`	Native emcc launcher	`ctc-em++` (auto-detected via argv[0])
`ctc-wasm-ld`	Native wasm-ld launcher	--

Build all with:

clang-tool-chain compile-native <output-dir>

How It Works

ctc-emcc / ctc-em++

Three execution tiers, fastest to slowest:

Tier 1 -- User Template (zero Python, both compile AND link):

# Compile: provide pre-cached clang args template
ctc-emcc --compile-commands=compile_args.json -c foo.cpp -o foo.o

# Link: provide pre-cached wasm-ld args template
ctc-emcc --link-args=link_args.json foo.o -o foo.wasm

Tier 2 -- Auto-Cache (compile -c only, zero Python after first run):

First compile: runs emcc with EMCC_VERBOSE=1, parses the actual clang command from stderr, templatizes it, caches per flag-hash
Subsequent compiles with same flags: reads cache, calls clang directly

Tier 3 -- Python Fallback (link, preprocess, uncached):

Sets up env (EMSCRIPTEN, EM_CONFIG, PATH) and execs python emcc.py with user args

ctc-wasm-ld

First run: invokes Python once to discover the native wasm-ld binary path
All subsequent runs: reads cache, execs wasm-ld directly (zero Python/Node)

Generating Template Files

Use the built-in capture flags to generate templates automatically:

# Capture compile template (runs emcc once, parses the native clang command)
ctc-emcc --capture-compile-commands=compile_args.json -c foo.cpp -o foo.o

# Capture link template (runs emcc once, parses the native wasm-ld command)
ctc-emcc --capture-link-args=link_args.json foo.o -o foo.wasm

This runs emcc normally, intercepts the native clang/wasm-ld command from verbose output, templatizes file paths with {input}/{output} placeholders, and saves the result as a JSON array.

Example generated template:

[
  "~/.clang-tool-chain/emscripten/win/x86_64/bin/clang.exe",
  "-target", "wasm32-unknown-emscripten",
  "--sysroot=.../emscripten/cache/sysroot",
  "-DEMSCRIPTEN",
  "-c", "{input}",
  "-o", "{output}",
  "-std=c++20", "-O2"
]

ctc-emcc Flags

All launcher flags are consumed by the launcher and not passed to emcc:

Flag	Description
`--compile-commands=<file>`	Use pre-cached clang compile template (Tier 1)
`--link-args=<file>`	Use pre-cached wasm-ld link template (Tier 1)
`--capture-compile-commands=<file>`	Run emcc, save clang template to file
`--capture-link-args=<file>`	Run emcc, save wasm-ld template to file
`--dry-run`	Print the command that would be exec'd
`--help` / `-h`	Show launcher help

ctc-wasm-ld Flags

Flag	Description
`--dry-run`	Print the command that would be exec'd
`--help` / `-h`	Show launcher help

All other arguments are passed directly to wasm-ld.

Debug

Set CTC_DEBUG=1 to see which tier is executing and cache hit/miss info.

🌍 Cosmopolitan (Actually Portable Executables)

2 commands • Build-once run-anywhere • Single binary • No runtime deps

Universal Platform Support

Build Platform	Architecture	Cosmocc Version	Output Format	Status
Windows	x86_64	4.0.2	.com (APE)	✅ Full
Linux	x86_64	4.0.2	.com (APE)	✅ Full
Linux	ARM64	4.0.2	.com (APE)	✅ Full
macOS	x86_64	4.0.2	.com (APE)	✅ Full
macOS	ARM64	4.0.2	.com (APE)	✅ Full

APE Runtime Support: Windows x64, Linux x64/ARM64, macOS x64/ARM64, FreeBSD, NetBSD, OpenBSD

Note: Cosmocc produces identical .com files on all platforms - the output is "Actually Portable" and runs natively on all supported operating systems without modification.

Quick Examples

# Install cosmocc toolchain
clang-tool-chain install cosmocc

# Build portable executable
clang-tool-chain-cosmocc hello.c -o hello.com
clang-tool-chain-cosmocpp hello.cpp -o hello.com

# The .com file runs on ANY supported OS
./hello.com  # Works on Linux, macOS, FreeBSD, etc.
# On Windows: hello.com

📖 Complete Documentation - Usage guide, APE format, platform support, Cosmopolitan project.

🔬 Valgrind & Callgrind (Dynamic Analysis)

2 commands • Memory error detection • Call graph profiling • Docker-based • Works from any host platform

Platform Support

Host Platform	Architecture	Status	Notes
Windows	x86_64	✅ Supported	Via Docker Desktop
Linux	x86_64	✅ Supported	Via Docker
Linux	ARM64	✅ Supported	Via Docker
macOS	x86_64	✅ Supported	Via Docker Desktop
macOS	ARM64	✅ Supported	Via Docker Desktop

Requires: Docker installed and running. Valgrind binaries (~5 MB) auto-download on first use.

Valgrind - Memory Error Detection

Step-by-step guide to find memory leaks and errors:

# Step 1: Compile with debug symbols and no optimization
clang-tool-chain-cpp program.cpp -g -O0 -o program

# Step 2: Run with Valgrind memory checker
clang-tool-chain-valgrind --leak-check=full ./program

# Step 3: Track origins of uninitialized values
clang-tool-chain-valgrind --leak-check=full --track-origins=yes ./program

# Step 4: Use in CI/CD (fail on errors)
clang-tool-chain-valgrind --leak-check=full --error-exitcode=1 ./program

Callgrind - Performance Profiling

Step-by-step guide to find performance bottlenecks:

# Step 1: Compile with debug symbols and no optimization
clang-tool-chain-cpp program.cpp -g -O0 -o program

# Step 2: Profile with callgrind (auto-annotated output)
clang-tool-chain-callgrind ./program

# Step 3: Save annotated report to a file
clang-tool-chain-callgrind -o profile_report.txt ./program

# Step 4: Keep raw output for KCachegrind/QCachegrind GUI
clang-tool-chain-callgrind --raw ./program
kcachegrind callgrind.out.*   # Open in GUI (Linux)
qcachegrind callgrind.out.*   # Open in GUI (macOS/Windows)

Callgrind End-to-End Example

Write a program with an intentionally expensive function:

// profile_test.c
#include <stdio.h>

__attribute__((noinline))
int expensive_compute(int n) {
    volatile int sum = 0;
    for (int i = 0; i < n; i++)
        for (int j = 0; j < n; j++)
            sum += (i * j) % 17;
    return sum;
}

__attribute__((noinline))
int cheap_compute(int n) {
    volatile int sum = 0;
    for (int i = 0; i < n; i++)
        sum += i;
    return sum;
}

int main() {
    int a = expensive_compute(1000);  // ~1M iterations
    int b = cheap_compute(100);       // 100 iterations
    printf("expensive=%d cheap=%d\n", a, b);
}

Compile and profile:

# Compile with debug symbols (cosmocc for cross-platform Linux ELF)
clang-tool-chain-cosmocc profile_test.c -g -O0 -o profile_test.com

# Run callgrind
clang-tool-chain-callgrind ./profile_test.com

Callgrind output clearly identifies expensive_compute as the bottleneck:

Ir                   file:function
------------------------------------------------------------
22,009,013 (99.92%)  profile_test.c:expensive_compute [/workdir/profile_test.com.dbg]

The expensive O(n^2) function consumed 99.92% of all instructions, while cheap_compute and main together account for <0.1% — too small to appear above the default 95% annotation threshold.

Works with Cosmopolitan (cosmocc)

Both tools automatically detect APE .com files and use the .dbg sidecar:

clang-tool-chain-cosmocc -g -O0 program.c -o program.com
clang-tool-chain-valgrind --track-origins=yes ./program.com   # auto-redirects to .dbg
clang-tool-chain-callgrind ./program.com                      # auto-redirects to .dbg

📖 Valgrind Documentation - Memory leak detection, Docker setup, cosmocc integration. 📖 Callgrind Documentation - Call graph profiling, KCachegrind, performance analysis.

⚙️ Management CLI

4 diagnostic commands + 1 main CLI • Pre-install • PATH management • Diagnostics • Cleanup

Main CLI Subcommands

clang-tool-chain install <target>    # Pre-install toolchains
clang-tool-chain uninstall <target>  # Remove PATH entries
clang-tool-chain purge              # Remove all downloaded toolchains
clang-tool-chain info               # Show installation details
clang-tool-chain help               # Show help message

Available Targets:

clang - Core Clang/LLVM toolchain
clang-env - Add Clang binaries to system PATH
iwyu - Include What You Use analyzer
iwyu-env - Add IWYU to system PATH
lldb - LLDB debugger
lldb-env - Add LLDB to system PATH
emscripten - Emscripten WebAssembly SDK
emscripten-env - Add Emscripten to system PATH
cosmocc - Cosmopolitan Libc toolchain

Diagnostic Commands

clang-tool-chain-test     # Run 7 diagnostic tests
clang-tool-chain-fetch    # Download toolchain components
clang-tool-chain-paths    # Display installation paths

Quick Examples

# Pre-install Clang toolchain
clang-tool-chain install clang

# Add to system PATH (no clang-tool-chain- prefix needed)
clang-tool-chain install clang-env
clang++ hello.cpp -o hello  # Use directly

# Check installation status
clang-tool-chain info

# Run diagnostics
clang-tool-chain test

# Clean everything
clang-tool-chain purge --yes

📖 Complete Documentation - Full command reference, workflows, installation targets.

🚀 Executable C++ Scripts (Shebang Support)

Run C++ files directly like shell scripts with native performance.

#!/usr/bin/env -S uvx clang-tool-chain-build-run --cached
#include <iostream>
int main() { std::cout << "Hello!\n"; }

chmod +x script.cpp && ./script.cpp

📖 Complete Documentation - Examples, TDD workflows, platform setup.

🚀 Native C++ Launcher (Zero Overhead)

Compile a native C++ launcher that replaces the Python wrapper, eliminating Python startup overhead entirely. Ideal for build systems that invoke the compiler hundreds or thousands of times.

Why Native?

The default clang-tool-chain-c / clang-tool-chain-cpp commands are Python scripts that locate and invoke the bundled Clang binary. Each invocation pays ~50-100ms of Python startup cost. For a single compilation this is negligible, but in a large build with thousands of translation units, it adds up.

The native launcher (ctc-clang / ctc-clang++) is a single-file C++17 program compiled to a standalone binary. It provides all the same features as the Python wrapper -- directive parsing, sysroot injection, linker flag translation, sanitizer setup, DLL/SO deployment -- with near-zero startup overhead.

Quick Start

# Compile the native launcher (uses the bundled clang to compile itself)
clang-tool-chain-compile-native ./native-tools

# Use the native launcher directly
./native-tools/ctc-clang hello.c -o hello
./native-tools/ctc-clang++ hello.cpp -o hello

# Or use in build systems
export CC=/path/to/native-tools/ctc-clang
export CXX=/path/to/native-tools/ctc-clang++
cmake -B build && cmake --build build

Features

The native launcher supports everything the Python wrapper does:

Inlined directives - @link, @std, @cflags, @platform parsed in a background thread
Sysroot injection - Bundled headers for Windows (MinGW), Linux, macOS
Linker flag translation - GNU flags auto-translated to platform-native equivalents
LLD linker - Forces fast LLD linker across all platforms
Sanitizer setup - ASAN/LSAN environment variables and symbolizer paths
DLL/SO deployment - Post-link dependency copying on Windows and Linux
Path caching - Writes a .ctc-cache file for instant toolchain discovery on subsequent runs
Auto-install - Downloads and installs the toolchain on first use if not present

Environment Variables

Variable	Effect
`CLANG_TOOL_CHAIN_NO_AUTO`	Bypass all auto-injection (sysroot, flags, directives)
`CLANG_TOOL_CHAIN_NO_DIRECTIVES`	Skip directive parsing
`CLANG_TOOL_CHAIN_NO_SYSROOT`	Skip sysroot injection
`CTC_DEBUG`	Enable verbose debug output

📝 Inlined Build Directives

Embed build configuration in source files - no makefiles needed.

// @link: [pthread, m]
// @std: c++17
#include <pthread.h>
int main() { /* code */ }

clang-tool-chain-cpp file.cpp -o program  # Auto-detects!

📖 Complete Documentation - Full directive reference, cross-platform examples.

⚡ sccache Integration

Optional compilation caching for 2-10x faster rebuilds.

pip install clang-tool-chain[sccache]
clang-tool-chain-sccache-cpp main.cpp -o main

📖 Complete Documentation - Installation, configuration, backends, benchmarks.

📦 Installation

pip install clang-tool-chain

Toolchain downloads automatically on first use - no setup needed!

Installation Options

# Option 1: Auto-download (recommended)
clang-tool-chain-c hello.c -o hello  # Downloads on first use

# Option 2: Pre-install
clang-tool-chain install clang       # Pre-download (~71-91 MB)

# Option 3: Add to PATH
clang-tool-chain install clang-env   # Use 'clang' directly

📖 Complete Documentation - From-source installation, upgrading, uninstallation, offline setup.

🎯 Why clang-tool-chain?

The Problem: Traditional LLVM needs 1-3 GB downloads, admin rights, manual PATH setup.

The Solution: 71-91 MB, auto-download, no admin rights, works everywhere.

Feature	clang-tool-chain	Full LLVM	zig cc
Size	71-91 MB	1-3 GB	~80 MB
Admin	❌ No	✅ Yes	❌ No
Auto Download	✅ Yes	❌ No	✅ Yes
Version Pin	✅ requirements.txt	❌ No	⚠️ Tied to Zig
Python	✅ Native	❌ Manual	❌ Manual

Perfect for: CI/CD • Education • Teams • Python projects • Quick prototyping

📖 Complete Documentation - Detailed comparison, use cases, tradeoff analysis.

✨ Features

44 wrapper commands • Auto-download • 94% size reduction • Cross-platform • Auto library deployment • Universal linker flags • Native C++ launcher

Zero Configuration - Auto-downloads to ~/.clang-tool-chain/
Ultra-Compact - 71-91 MB (94% smaller via zstd-22)
44 Commands - Clang/LLVM, Emscripten, IWYU, LLDB, Valgrind, formatters, binary utils
Cross-Platform - Windows x64, macOS x64/ARM64, Linux x64/ARM64
🚀 Native C++ Launcher - Compile ctc-clang/ctc-clang++ for zero Python overhead in large builds
🎯 Universal Linker Flags - Write GNU-style linker flags once, run everywhere (auto-translates to MSVC on Windows, ld64 on macOS)
Auto Library Deployment - Windows DLLs, Linux .so, macOS .dylib copied automatically
Concurrent-Safe - File locking for parallel builds
Python Native - Seamless Python integration

📖 Complete Documentation - All 43 commands by category, detailed capabilities.

📚 Examples

#include <iostream>
int main() {
    std::cout << "Hello from clang-tool-chain!" << std::endl;
    return 0;
}

clang-tool-chain-cpp hello.cpp -o hello && ./hello
clang-tool-chain-c main.c utils.c math.c -o program

📖 Complete Documentation - Multi-file projects, static libraries, CMake, WebAssembly, Cosmopolitan, executable scripts, directives, Windows examples, IWYU, formatting, debugging, sccache, binary utilities.

🎯 Cross-Platform Linker Flags

Write linker flags once, run everywhere - clang-tool-chain automatically translates GNU-style linker flags to platform-native equivalents.

The Problem (Before)

Platform-specific linker flags force you to write conditional code:

# build.py - platform-specific nightmare
if platform == "windows":
    link_flags = ["-Wl,/FORCE:UNRESOLVED"]  # MSVC style
elif platform == "darwin":
    link_flags = ["-Wl,-undefined,dynamic_lookup"]  # macOS ld64 style
else:
    link_flags = ["-Wl,--allow-shlib-undefined"]  # GNU ld style

The Solution (After)

Use GNU-style flags everywhere - automatic translation:

# build.py - universal flags
link_flags = ["-Wl,--allow-shlib-undefined"]  # Works on ALL platforms!

How It Works

clang-tool-chain automatically translates flags based on the target platform:

Windows: GNU ld flags → MSVC/lld-link equivalents (--allow-shlib-undefined → /FORCE:UNRESOLVED)
macOS: GNU ld flags → ld64.lld equivalents (--no-undefined → -undefined error)
Linux: GNU ld flags pass through unchanged (native support)

Examples

# Shared library with undefined symbols - works everywhere!
clang-tool-chain-cpp -shared -Wl,--allow-shlib-undefined plugin.cpp -o plugin.dll

# Dead code elimination - universal syntax
clang-tool-chain-cpp -Wl,--gc-sections main.cpp -o optimized

# Combined flags - automatic translation
clang-tool-chain-cpp -shared -Wl,--allow-shlib-undefined,--gc-sections lib.cpp -o lib.so

Supported Flag Translations

GNU ld Flag	Windows (MSVC)	macOS (ld64)	Linux
`--allow-shlib-undefined`	`/FORCE:UNRESOLVED`	(removed)	(pass through)
`--no-undefined`	(removed, default)	`-undefined error`	(pass through)
`--gc-sections`	`/OPT:REF`	(pass through)	(pass through)
`-shared`	`/DLL`	(pass through)	(pass through)

📖 Complete Flag Mapping - Full translation table, environment variables, advanced usage.

Backward Compatibility

Platform-native flags still work (MSVC on Windows, ld64 on macOS):

# MSVC-style flags still work on Windows
clang-tool-chain-cpp -Wl,/FORCE:UNRESOLVED plugin.cpp -o plugin.dll  # Windows only

# Mixed GNU/MSVC flags supported for migration
clang-tool-chain-cpp -Wl,--gc-sections,/FORCE:UNRESOLVED lib.cpp  # Translates --gc-sections only

Disable Translation

# Suppress translation warnings
export CLANG_TOOL_CHAIN_NO_LINKER_COMPAT_NOTE=1

📦 Automatic Library Deployment

Zero-config dependency deployment across all platforms

clang-tool-chain automatically detects and copies required runtime libraries to your output directory, ensuring executables run immediately without PATH/LD_LIBRARY_PATH configuration.

Windows (Automatic)

# MinGW DLLs automatically deployed
clang-tool-chain-cpp hello.cpp -o hello.exe
# Output: Deployed 3 MinGW DLL(s) for hello.exe
# hello.exe, libwinpthread-1.dll, libgcc_s_seh-1.dll, libstdc++-6.dll

.\hello.exe  # Runs immediately - no PATH setup needed!

Linux (Opt-in via --deploy-dependencies)

# Shared libraries deployed with flag
clang-tool-chain-cpp main.cpp -o program --deploy-dependencies -lunwind
# Output: Deployed 1 shared library for program
# program, libunwind.so.8, libunwind.so.8.0.1

./program  # Runs immediately - no LD_LIBRARY_PATH needed!

macOS (Opt-in via --deploy-dependencies)

# Dynamic libraries deployed with flag
clang-tool-chain-cpp main.cpp -o program --deploy-dependencies -lunwind
# Output: Deployed 1 dynamic library for program
# program, libunwind.dylib

./program  # Runs immediately - no DYLD_LIBRARY_PATH needed!

Configuration

Disable deployment:

# Cross-platform
export CLANG_TOOL_CHAIN_NO_DEPLOY_LIBS=1

Enable verbose logging:

export CLANG_TOOL_CHAIN_LIB_DEPLOY_VERBOSE=1
clang-tool-chain-cpp main.cpp -o program --deploy-dependencies
# DEBUG: Detecting dependencies for program
# DEBUG: Found library: libunwind.so.8
# DEBUG: Copying libunwind.so.8 to output directory
# INFO: Deployed 1 shared library for program

Features:

Smart Copying: Timestamp checking avoids unnecessary copies
Symlink Preservation: Linux .so versioning maintained (libunwind.so.8 → libunwind.so.8.0.1)
Hard Link Optimization: Zero disk space when possible (Windows)
System Library Filtering: Only deploys toolchain libraries, excludes system libraries
Non-Fatal: Deployment errors never fail your build (warnings only)
Fast: <300ms overhead per build

📖 Complete Documentation - Detailed deployment guide for all platforms, environment variables, troubleshooting.

📦 Post-Build Library Deployment (clang-tool-chain-libdeploy)

Deploy runtime dependencies after compilation - useful when you've compiled without --deploy-dependencies or when using external build systems.

Quick Examples

# Deploy dependencies for a Windows executable
clang-tool-chain-libdeploy myprogram.exe
# Output: Deployed 3 MinGW DLL(s) for myprogram.exe

# Deploy dependencies for a Linux shared library
clang-tool-chain-libdeploy mylib.so

# Deploy dependencies for a macOS executable
clang-tool-chain-libdeploy myprogram

# Dry run - see what would be deployed without copying
clang-tool-chain-libdeploy --dry-run myprogram.exe
# Output:
# Would deploy 3 libraries:
#   libwinpthread-1.dll <- /path/to/toolchain/lib/libwinpthread-1.dll
#   libgcc_s_seh-1.dll <- /path/to/toolchain/lib/libgcc_s_seh-1.dll
#   libstdc++-6.dll <- /path/to/toolchain/lib/libstdc++-6.dll

Command Line Options

clang-tool-chain-libdeploy [options] <binary>

Options:
  -h, --help            Show help message
  -v, --verbose         Enable verbose output
  -n, --dry-run         Show what would be deployed without copying
  -p, --platform        Override auto-detected platform (windows, linux, darwin)
  -a, --arch            Target architecture (default: auto-detect)

Use Cases

External build systems: When using CMake, Make, or other build systems that don't use clang-tool-chain wrappers directly
Third-party binaries: Deploy dependencies for pre-built executables compiled with clang-tool-chain
CI/CD pipelines: Add deployment as a separate step after compilation
Debugging: Use --dry-run to inspect dependencies without modifying files

Supported Formats

Platform	File Types	Dependencies Deployed
Windows	`.exe`, `.dll`	MinGW runtime DLLs (libwinpthread, libgcc_s, libstdc++, etc.)
Linux	executables, `.so`	libc++, libunwind, sanitizer runtimes
macOS	executables, `.dylib`	libc++, libunwind, sanitizer runtimes

Binary Type Detection

The tool automatically detects binary type from:

File extension: .exe, .dll, .so, .dylib
Magic bytes: ELF (Linux), Mach-O (macOS), PE (Windows)

For executables without extensions (common on Linux/macOS), magic bytes are used for detection.

🚀 CI/CD Integration

name: Build
on: [push, pull_request]
jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest, macos-latest]
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-python@v4
        with:
          python-version: '3.11'
      - run: pip install clang-tool-chain
      - run: clang-tool-chain-cpp main.cpp -o program

📖 Complete Documentation - GitHub Actions with caching, GitLab CI, Docker, Azure Pipelines, CircleCI, Travis CI, multi-platform matrices, best practices.

🌍 Platform Support Matrix

Platform	Architecture	LLVM Version	Archive Size	Bundled Extras	Status
Windows	x86_64	21.1.5	~71-90 MB	MinGW sysroot	✅ Stable
Linux	x86_64	21.1.5	~87 MB	libunwind	✅ Stable
Linux	ARM64	21.1.5	~91 MB	libunwind	✅ Stable
macOS	x86_64	19.1.7	~77 MB	-	✅ Stable
macOS	ARM64	21.1.6	~71 MB	-	✅ Stable

Requirements: Python 3.10+, ~100-400 MB disk space

📖 Complete Documentation - Detailed requirements, LLVM versions, tool-specific support, CI/CD compatibility.

⚙️ Configuration

Key Environment Variables:

CLANG_TOOL_CHAIN_DOWNLOAD_PATH - Override installation location
CLANG_TOOL_CHAIN_NO_DEPLOY_LIBS - Disable automatic library deployment (all platforms)
CLANG_TOOL_CHAIN_NO_DEPLOY_SHARED_LIB - Disable library deployment for shared library outputs only
CLANG_TOOL_CHAIN_LIB_DEPLOY_VERBOSE - Enable verbose library deployment logging
CLANG_TOOL_CHAIN_USE_SYSTEM_LD - Use system linker instead of LLD
CLANG_TOOL_CHAIN_NO_DIRECTIVES - Disable inlined build directives
CLANG_TOOL_CHAIN_NO_BUNDLED_UNWIND - Disable bundled libunwind on Linux (use system version)
CLANG_TOOL_CHAIN_NO_SANITIZER_ENV - Disable automatic ASAN/LSAN options injection at runtime
SDKROOT - Custom macOS SDK path (auto-detected by default)

📖 Complete Documentation - All environment variables, macOS SDK, Windows DLL settings, sccache backends.

⚡ Performance

Compilation: Identical to official LLVM (native binaries, zero wrapper overhead).

Native launcher: Compile ctc-clang/ctc-clang++ with clang-tool-chain-compile-native to eliminate Python startup overhead (~50-100ms per invocation). Essential for large builds with thousands of compiler invocations. See Native C++ Launcher.

Downloads: ~5 seconds (100 Mbps) or ~25 seconds (20 Mbps). Subsequent use: instant.

📖 Complete Documentation - Detailed benchmarks, sccache speedups, memory usage, optimization tips.

🎯 Windows Target Selection

# Default: GNU ABI (MinGW-w64) - Cross-platform, no VS required
clang-tool-chain-cpp hello.cpp -o hello

# MSVC ABI - Windows-native projects, requires Visual Studio
clang-tool-chain-cpp-msvc main.cpp -o program.exe

Feature	GNU ABI	MSVC ABI
Cross-platform	✅ Yes	❌ No
Visual Studio	❌ Not needed	✅ Required
C++11 strict	✅ Yes	❌ C++14+

📖 Complete Documentation - Detailed comparison, DLL deployment, troubleshooting, recommendations.

🪟 Windows DLL Deployment

Automatic MinGW runtime DLL deployment for Windows executables (GNU ABI). Programs run immediately without PATH setup.

📖 Complete Documentation - Environment variables, troubleshooting.

🛡️ Address Sanitizer (ASAN) Support

Full ASAN support with automatic runtime configuration for better stack traces.

Compilation

# Compile with ASAN
clang-tool-chain-cpp -fsanitize=address test.cpp -o test

# With automatic library deployment (recommended)
clang-tool-chain-cpp -fsanitize=address test.cpp -o test --deploy-dependencies

# Run - ASAN errors will be detected
./test

Runtime Environment (Automatic)

When running executables via clang-tool-chain-build-run, optimal sanitizer options are automatically injected to improve stack trace quality - but only when the corresponding sanitizer was used during compilation:

ASAN_OPTIONS=fast_unwind_on_malloc=0:symbolize=1:detect_leaks=1 (when -fsanitize=address is used)
LSAN_OPTIONS=fast_unwind_on_malloc=0:symbolize=1 (when -fsanitize=address or -fsanitize=leak is used)
ASAN_SYMBOLIZER_PATH=/path/to/llvm-symbolizer (automatically detected from clang-tool-chain)

What these options fix:

<unknown module> entries in stack traces from dlopen()'d shared libraries
Missing function names in crash reports (raw addresses like 0x7f5a4f15ac1d instead of my_function)
Incomplete leak detection

Your options are always preserved - if you set ASAN_OPTIONS, LSAN_OPTIONS, or ASAN_SYMBOLIZER_PATH yourself, clang-tool-chain won't override them.

Regular builds are unaffected - sanitizer options are only injected when the compiler flags indicate sanitizers are being used.

Programmatic API (For Build Systems)

External build systems can use the sanitizer environment API to get properly configured environments:

from clang_tool_chain import prepare_sanitizer_environment, get_symbolizer_path

# Option A: Complete environment setup (recommended)
env = prepare_sanitizer_environment(
    base_env=os.environ.copy(),
    compiler_flags=["-fsanitize=address", "-O2"]
)
# env now contains ASAN_OPTIONS, LSAN_OPTIONS, and ASAN_SYMBOLIZER_PATH

# Option B: Just get the symbolizer path
symbolizer = get_symbolizer_path()
if symbolizer:
    os.environ["ASAN_SYMBOLIZER_PATH"] = symbolizer

Available functions:

prepare_sanitizer_environment(base_env, compiler_flags) - Returns environment dict with all sanitizer variables
get_symbolizer_path() - Returns path to llvm-symbolizer or None
detect_sanitizers_from_flags(flags) - Returns (asan_enabled, lsan_enabled) tuple

Configuration

# Disable automatic sanitizer environment injection
export CLANG_TOOL_CHAIN_NO_SANITIZER_ENV=1

# Disable automatic -shared-libasan on Linux (use static ASAN)
export CLANG_TOOL_CHAIN_NO_SHARED_ASAN=1

# Suppress the "automatically injected sanitizer flags" note
export CLANG_TOOL_CHAIN_NO_SANITIZER_NOTE=1

Platform Notes:

Linux: Automatically uses -shared-libasan for proper runtime linking
Windows: Works with both GNU and MSVC ABIs
macOS: Uses bundled LLVM ASAN runtime

Dynamically Loaded Libraries

If you see <unknown module> in ASAN/LSAN stack traces for code in dynamically loaded libraries, apply these fixes:

1. Use RTLD_NOW | RTLD_GLOBAL (not RTLD_LAZY)

void* handle = dlopen(path, RTLD_NOW | RTLD_GLOBAL);  // Good
void* handle = dlopen(path, RTLD_LAZY);               // Bad - causes <unknown module>

2. Skip dlclose() when ASAN is active

ASAN symbolizes at exit; if the library is unloaded, addresses become <unknown module>.

#if !defined(__SANITIZE_ADDRESS__)
    dlclose(handle);  // Only close when not running under ASAN
#endif

On Windows, use the same pattern with FreeLibrary().

See: https://github.com/google/sanitizers/issues/899

📚 libunwind Support (All Platforms)

Cross-platform stack unwinding for debugging and profiling

clang-tool-chain provides libunwind support on all platforms with platform-specific implementations:

Linux: Bundled libunwind (headers + shared libraries) - no system packages required
Windows: MinGW sysroot libunwind - included in toolchain
macOS: System libunwind from macOS SDK - no additional installation required

All platforms support #include <libunwind.h> and -lunwind out of the box.

What's Bundled (Linux)

Component	Files	Size
Headers	`libunwind.h`, `libunwind-common.h`, `libunwind-x86_64.h`/`libunwind-aarch64.h`, `unwind.h`	~20 KB
Libraries	`libunwind.so.`, `libunwind-x86_64.so.` (or `aarch64`)	~300 KB

Platform-Specific Details

Platform	Source	Installation	Symbol Resolution	Notes
Linux	Bundled (from Debian packages)	Automatic with toolchain	✅ Full support via `unw_get_proc_name()`	Includes headers + shared libraries
Windows	MinGW sysroot	Automatic with toolchain	⚠️ Limited - use `llvm-symbolizer`	Stack walking works; symbol resolution requires external tool
macOS	System SDK	Pre-installed with macOS	✅ Full support via `unw_get_proc_name()`	Uses system libunwind

Windows Symbol Resolution:

MinGW libunwind on Windows doesn't support unw_get_proc_name(). While llvm-symbolizer is bundled, Windows ASLR makes runtime address resolution complex.

Recommended: Use clang-tool-chain-lldb for debugging with symbols, or use Linux/macOS for built-in symbol resolution.

Verification (llvm-symbolizer works with static addresses):

# Compile with debug symbols
clang-tool-chain-c program.c -o program.exe -g

# Get function addresses and resolve
llvm-nm program.exe | grep main
# Shows: 1400014d0 T main

llvm-symbolizer -e program.exe -f -C 0x1400014d0
# Shows: main
#        C:\path\to\program.c:10:0

How It Works

When compiling on Linux, clang-tool-chain automatically:

Adds -I<clang_root>/include for bundled libunwind headers
Adds -L<clang_root>/lib for bundled libunwind libraries
Adds -Wl,-rpath,<clang_root>/lib so executables find libunwind at runtime

This means #include <libunwind.h> and -lunwind work out of the box.

Usage Example

// backtrace.c - Print a stack trace using libunwind
#include <stdio.h>
#include <libunwind.h>

void print_backtrace() {
    unw_cursor_t cursor;
    unw_context_t context;
    unw_getcontext(&context);
    unw_init_local(&cursor, &context);

    while (unw_step(&cursor) > 0) {
        char name[256];
        unw_word_t offset;
        unw_get_proc_name(&cursor, name, sizeof(name), &offset);
        printf("  %s+0x%lx\n", name, (unsigned long)offset);
    }
}

int main() {
    print_backtrace();
    return 0;
}

# Compile and link with bundled libunwind - no apt-get install needed!
clang-tool-chain-c backtrace.c -lunwind -o backtrace

# Run without LD_LIBRARY_PATH - works due to embedded rpath
./backtrace

Configuration

Disable bundled libunwind on Linux (use system version instead):

export CLANG_TOOL_CHAIN_NO_BUNDLED_UNWIND=1  # Linux only

Note: This environment variable only applies to Linux. Windows and macOS always use their respective platform sources (MinGW sysroot and system SDK).

Platform Support

Platform	Headers	Libraries	Status
Linux x86_64	✅ Bundled	✅ Bundled	✅ Full
Linux ARM64	✅ Bundled	✅ Bundled	✅ Full
Windows	MinGW sysroot	MinGW sysroot	N/A (different API)
macOS	System	System	N/A (uses system)

📖 Complete Documentation - Detailed usage, API reference, integration with ASAN, advanced examples.

🔧 How It Works

Auto-downloads on first use (~71-91 MB, 10-60 seconds). Subsequent uses are instant.

📖 Complete Documentation - Architecture, download process, installation paths, technical details.

🔧 Additional Utilities

Diagnostic commands: clang-tool-chain-test, clang-tool-chain-fetch, clang-tool-chain-paths

📖 Complete Documentation - Detailed usage, scripting integration.

🔬 Advanced Topics

Offline mode • Version pinning • Airgapped environments • Custom paths • Docker • Advanced sccache

📖 Complete Documentation - Complete guides for advanced use cases.

❓ FAQ

Common questions about first use, offline mode, updates, disk space, Docker, CMake, platform requirements.

📖 Complete Documentation - Frequently asked questions with detailed answers.

🔍 Troubleshooting

Common issues: binaries not found, download failures, permissions, platform requirements.

clang-tool-chain-test  # Run diagnostics
clang-tool-chain info  # Check installation

📖 Complete Documentation - Detailed solutions to common issues.

🔒 Security

SHA256 verification • Safe extraction • HTTPS-only • Transparent trust model

📖 Complete Documentation - Verification procedures, trust model details.

👨‍💻 Development

git clone https://github.com/zackees/clang-tool-chain.git
cd clang-tool-chain
./install              # Install dependencies (uses uv)
./test                 # Run tests
./lint                 # Run linters

📖 Testing Guide - Platform-specific tests, CI/CD integration, writing new tests.

🤝 Contributing

Want to add a new tool? See the Contributing Guide for step-by-step instructions.

Key topics:

Codebase structure and architecture
Creating installers for new tools
Registering entry points in pyproject.toml
Creating binary archives and manifests
Adding tests and CI workflows
Platform-specific considerations

Designed for both human developers and AI agents.

🛠️ Maintainer Tools

For creating and updating binary archives, see the Maintainer Guide.

Topics: Archive creation, binary stripping, compression, manifests, checksums, MinGW sysroot, LLDB builds, dependency troubleshooting.

📚 Detailed Documentation

For in-depth information on specific topics, see the documentation in the docs/ directory:

Tools & Features

Document	Description
Features Overview	Complete feature list and all 41 commands
Clang/LLVM Toolchain	Compiler wrappers, macOS SDK detection, Windows GNU/MSVC ABI
Build Utilities	Build, build-run, caching, shebang support
Binary Utilities	LLVM binary tools (ar, nm, objdump, strip, etc.)
Format & Lint	clang-format and clang-tidy
IWYU	Include What You Use analyzer
LLDB Debugger	LLVM debugger with Python support
Emscripten	WebAssembly compilation
Cosmopolitan Libc	Actually Portable Executables (APE)
sccache Integration	Compilation caching (2-10x speedup)
Inlined Build Directives	Self-contained source files
Bundled libunwind	Linux stack unwinding (headers + libraries)
Valgrind	Memory error detection via Docker
Callgrind	Call graph profiling via Docker

Setup & Configuration

Document	Description
Quick Start Guide	Comprehensive quick start with all major features
Getting Started	Platform-specific setup and common workflows
Installation Guide	Installation, upgrading, uninstallation
Management CLI	CLI commands (install, purge, info, test)
Platform Support	Platform matrix, requirements, compatibility
Configuration	Environment variables and settings
Windows Target Selection	GNU vs MSVC ABI selection
DLL Deployment	Windows MinGW DLL automatic deployment

Integration & Usage

Document	Description
Examples	Code examples and workflows
Executable Scripts	Shebang support details
CI/CD Integration	GitHub Actions, GitLab CI, Docker, Azure
Additional Utilities	Test, fetch, paths commands

Technical & Reference

Document	Description
Why clang-tool-chain?	Comparison matrix, use cases, tradeoff analysis
How It Works	Architecture, download process, technical details
Advanced Topics	Offline mode, version pinning, airgapped setup, Docker
Performance	Benchmarks and optimization
Security	Security practices and verification
Architecture	Technical architecture, manifest system
Parallel Downloads	Multi-threaded range requests
Node.js Integration	Bundled Node.js runtime
Test Matrix	CI/CD test coverage across all platforms
License Information	Complete licensing details for all components

Development & Maintenance

Document	Description
Testing Guide	Test infrastructure, running tests, CI/CD
Contributing	How to add new tools
Maintainer Guide	Binary packaging, archive creation
Acknowledgments	Credits, licenses, special thanks
FAQ	Frequently asked questions
Troubleshooting	Common issues and solutions

Windows GNU ABI with integrated MinGW headers (single archive download)
Bundled Node.js runtime for Emscripten users
Cross-platform support: Windows x64, macOS x64/ARM64, Linux x64/ARM64
LLVM 21.1.5/21.1.6 with 35+ wrapper commands

🚀 Getting Started

pip install clang-tool-chain
echo 'int main() { return 0; }' > hello.c
clang-tool-chain-c hello.c -o hello
./hello

That's it! The toolchain downloads automatically.

📖 Complete Documentation - Installation options, platform-specific notes, common workflows.

Repository: github.com/zackees/clang-tool-chain Issues: github.com/zackees/clang-tool-chain/issues PyPI: pypi.org/project/clang-tool-chain/

Keywords: clang wrapper, llvm python, portable clang, clang installer, llvm toolchain, cross-platform compiler, python clang, automated llvm, clang docker, ci/cd compiler