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

These details have not been verified by PyPI

Project links

Project description

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 • 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.

45 GitHub Actions workflows covering all platform+tool combinations:

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

Live Test Status

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

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

📋 All Commands (42 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 (11)

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)

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

Management & Diagnostics (5)

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

Total: 42 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 (11 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)
Cosmopolitan - APE compiler (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

11 commands • LLVM binary tools • ELF/PE/Mach-O support • Archives & symbols

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

📖 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.

🌍 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.

⚙️ 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.

📝 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

41 wrapper commands • Auto-download • 94% size reduction • Cross-platform • Auto library deployment

Zero Configuration - Auto-downloads to ~/.clang-tool-chain/
Ultra-Compact - 71-91 MB (94% smaller via zstd-22)
41 Commands - Clang/LLVM, Emscripten, IWYU, LLDB, formatters, binary utils
Cross-Platform - Windows x64, macOS x64/ARM64, Linux x64/ARM64
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 41 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.

📦 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).

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

📚 Bundled libunwind (Linux)

Self-contained stack unwinding - no system packages required

On Linux, clang-tool-chain bundles libunwind headers and shared libraries, providing a complete solution for stack unwinding without requiring system packages like libunwind-dev.

What's Bundled

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

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 (use system version instead):

export CLANG_TOOL_CHAIN_NO_BUNDLED_UNWIND=1

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)

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

Project details

These details have not been verified by PyPI

Project links

Release history Release notifications | RSS feed

1.2.9

Apr 2, 2026

1.2.8

Mar 22, 2026

1.2.7

Mar 21, 2026

1.2.6

Mar 21, 2026

1.2.5

Mar 20, 2026

1.2.4

Mar 12, 2026

1.2.3

Mar 12, 2026

1.2.2

Mar 9, 2026

1.2.1

Mar 9, 2026

1.2.0

Mar 9, 2026

1.1.11

Feb 27, 2026

1.1.10

Feb 16, 2026

1.1.9

Feb 10, 2026

1.1.8

Feb 8, 2026

1.1.7

Feb 4, 2026

1.1.6

Feb 2, 2026

1.1.5

Feb 2, 2026

1.1.4

Feb 2, 2026

1.1.3

Feb 1, 2026

1.1.2

Feb 1, 2026

This version

1.1.0

Jan 31, 2026

1.0.47

Jan 31, 2026

1.0.45

Jan 31, 2026

1.0.44

Jan 30, 2026

1.0.43

Jan 30, 2026

1.0.42

Jan 30, 2026

1.0.41

Jan 30, 2026

1.0.40

Jan 30, 2026

1.0.39

Jan 30, 2026

1.0.38

Jan 30, 2026

1.0.37

Jan 30, 2026

1.0.36

Jan 30, 2026

1.0.35

Jan 29, 2026

1.0.34

Jan 26, 2026

1.0.33

Jan 26, 2026

1.0.32

Jan 23, 2026

1.0.31

Jan 17, 2026

1.0.30

Jan 17, 2026

1.0.29

Jan 16, 2026

1.0.28

Jan 16, 2026

1.0.27

Jan 10, 2026

1.0.26

Jan 8, 2026

1.0.25

Jan 8, 2026

1.0.24

Jan 8, 2026

1.0.23

Jan 8, 2026

1.0.22

Jan 7, 2026

1.0.21

Jan 7, 2026

1.0.20

Jan 7, 2026

1.0.18

Jan 5, 2026

1.0.17

Jan 5, 2026

1.0.16

Jan 4, 2026

1.0.15

Jan 3, 2026

1.0.14

Nov 17, 2025

1.0.13

Nov 16, 2025

1.0.12

Nov 16, 2025

1.0.11

Nov 12, 2025

1.0.10

Nov 12, 2025

1.0.9

Nov 12, 2025

1.0.8

Nov 12, 2025

1.0.7

Nov 11, 2025

1.0.5

Nov 11, 2025

1.0.3

Nov 11, 2025

1.0.2

Nov 10, 2025

1.0.1

Nov 10, 2025

1.0.0

Nov 10, 2025

0.0.1

Nov 8, 2025

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release.See tutorial on generating distribution archives.

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

clang_tool_chain-1.1.0-py3-none-any.whl (209.2 kB view details)

Uploaded Jan 31, 2026 Python 3

File details

Details for the file clang_tool_chain-1.1.0-py3-none-any.whl.

File metadata

Download URL: clang_tool_chain-1.1.0-py3-none-any.whl
Upload date: Jan 31, 2026
Size: 209.2 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/6.2.0 CPython/3.13.1

File hashes

Hashes for clang_tool_chain-1.1.0-py3-none-any.whl
Algorithm	Hash digest
SHA256	`8f81a06057d0d74417696acd3c65aeedeb30af80571045dbfe7c8a7863b70c34`
MD5	`7988caf6b2322dbcac1710855b1d1760`
BLAKE2b-256	`64428cede8ff658f2ad6b08d88cc2c8240410f8f9fe246ede48f2725cbfb0db2`

See more details on using hashes here.

clang-tool-chain 1.1.0

Navigation

Verified details

Maintainers

Unverified details

Project links

Meta

Classifiers

Project description

Clang Tool Chain

⚡ Quick Start

📊 Test Matrix

Live Test Status

📋 All Commands (42 Total)

Compiler Commands (6)

Compiler Commands with sccache (5)

Build Utilities (3)

Binary Utilities (11)

Format & Lint (2)

IWYU - Include Analyzer (3)

LLDB - Debugger (2)

Emscripten - WebAssembly (5)

Management & Diagnostics (5)

📑 Table of Contents

Getting Started

Tools by Category

Cross-Cutting Features

Platform & Configuration

Integration & Examples

Reference & Help

Development

Documentation

🛠️ Clang/LLVM Toolchain

Platform & Version Matrix

Windows ABI Selection

Quick Examples

🔨 Build Utilities

🔧 Binary Utilities

✨ Format & Lint

📐 IWYU (Include What You Use)

Platform Support Matrix

Quick Examples

🐛 LLDB Debugger

Platform & Python Support Matrix

Quick Examples

🌐 Emscripten (WebAssembly)

Platform & Version Matrix

Quick Examples

🌍 Cosmopolitan (Actually Portable Executables)

Universal Platform Support

Quick Examples

⚙️ Management CLI

Main CLI Subcommands

Diagnostic Commands

Quick Examples

🚀 Executable C++ Scripts (Shebang Support)

📝 Inlined Build Directives

⚡ sccache Integration

📦 Installation

Installation Options

🎯 Why clang-tool-chain?

✨ Features

📚 Examples

📦 Automatic Library Deployment

Windows (Automatic)

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

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

Configuration

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

Quick Examples

Command Line Options

Use Cases

Supported Formats

Binary Type Detection

🚀 CI/CD Integration

🌍 Platform Support Matrix

⚙️ Configuration

⚡ Performance

🎯 Windows Target Selection

🪟 Windows DLL Deployment