clang-tool-chain 1.3.0

Clang Tool Chain - C/C++ compilation toolchain utilities

Clang Tool Chain

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 x86_64	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)

Cross-Cutting Features

• Native C++ Launcher - Eliminate Python startup overhead
• Inlined Build Directives
• Executable C++ Scripts
• Windows DLL Deployment
• Address Sanitizer (ASAN)
• Bundled libunwind (Linux)
• sccache Integration

Platform & Configuration

• Platform Support Matrix
• Windows Target Selection
• Configuration
• Performance

Integration & Examples

• CI/CD Integration
• Examples

Reference & Help

• Troubleshooting
• FAQ
• Security
• Advanced Topics

Development

• Development
• Contributing
• Maintainer Tools

Documentation

• Detailed Documentation

---

🛠️ 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	21.1.6	⏳ Planned	✅ Basic	Python integration planned
macOS	ARM64	21.1.6	⏳ Planned	✅ Basic	Python integration planned

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

1. External build systems: When using CMake, Make, or other build systems that don't use clang-tool-chain wrappers directly
2. Third-party binaries: Deploy dependencies for pre-built executables compiled with clang-tool-chain
3. CI/CD pipelines: Add deployment as a separate step after compilation
4. 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:

1. File extension: .exe, .dll, .so, .dylib
2. 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:

1. Adds -I<clang_root>/include for bundled libunwind headers
2. Adds -L<clang_root>/lib for bundled libunwind libraries
3. 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

---

📄 License

This package is distributed under the Apache License 2.0. Bundled Clang/LLVM binaries use Apache License 2.0 with LLVM Exception.

See License Information Documentation for complete licensing details for all components.

---

🙏 Acknowledgments

Thanks to LLVM Project, Zstandard, Emscripten, Cosmopolitan, and all the open source projects that make this possible.

📖 Complete Acknowledgments - Full credits, licenses, and special thanks.

---

📊 Changelog

For full version history and release notes, see CHANGELOG.md.

Key highlights:

• 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