Metadata-Version: 2.4
Name: clang-tool-chain
Version: 1.0.2
Summary: Clang Tool Chain - C/C++ compilation toolchain utilities
Project-URL: Homepage, https://github.com/zackees/clang-tool-chain
Project-URL: Repository, https://github.com/zackees/clang-tool-chain
Project-URL: Issues, https://github.com/zackees/clang-tool-chain/issues
Author: Zachary Vorhies
Maintainer: Zachary Vorhies
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: c,clang,compiler,cpp,toolchain
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Compilers
Requires-Python: >=3.10
Requires-Dist: fasteners>=0.19.0
Requires-Dist: pyzstd>=0.16.0
Requires-Dist: uv-iso-env>=1.0.0
Provides-Extra: dev
Requires-Dist: black>=24.0.0; extra == 'dev'
Requires-Dist: isort>=5.13.0; extra == 'dev'
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pre-commit>=3.6.0; extra == 'dev'
Requires-Dist: pyright>=1.1.350; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-xdist>=3.5.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Requires-Dist: sccache>=0.7.0; extra == 'dev'
Provides-Extra: sccache
Requires-Dist: sccache>=0.7.0; extra == 'sccache'
Description-Content-Type: text/markdown

# Clang Tool Chain

**A zero-configuration Python package that distributes pre-built Clang/LLVM binaries with automatic downloading and installation.**

[![PyPI version](https://img.shields.io/pypi/v/clang-tool-chain.svg)](https://pypi.org/project/clang-tool-chain/)
[![Downloads](https://pepy.tech/badge/clang-tool-chain)](https://pepy.tech/project/clang-tool-chain)
[![Linting](https://github.com/zackees/clang-tool-chain/actions/workflows/lint.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/lint.yml)
[![win](https://github.com/zackees/clang-tool-chain/actions/workflows/test-win.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/test-win.yml)
[![linux-x86](https://github.com/zackees/clang-tool-chain/actions/workflows/test-linux-x86.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/test-linux-x86.yml)
[![linux-arm](https://github.com/zackees/clang-tool-chain/actions/workflows/test-linux-arm.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/test-linux-arm.yml)
[![macos-x86](https://github.com/zackees/clang-tool-chain/actions/workflows/test-macos-x86.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/test-macos-x86.yml)
[![macos-arm](https://github.com/zackees/clang-tool-chain/actions/workflows/test-macos-arm.yml/badge.svg)](https://github.com/zackees/clang-tool-chain/actions/workflows/test-macos-arm.yml)
[![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://opensource.org/licenses/Apache-2.0)
[![Python Version](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)

---

## ⚡ Quick Start

Get compiling in 30 seconds:

```bash
# Install the package
pip install clang-tool-chain

# Compile C code - binaries download automatically on first use!
echo 'int main() { return 0; }' > hello.c
clang-tool-chain-c hello.c -o hello
./hello  # Windows: .\hello.exe

# Verify installation (optional but recommended)
clang-tool-chain-test  # Runs 7 diagnostic tests
```

**That's it!** The LLVM toolchain (~52-91 MB) downloads automatically on first use. No manual setup required.

> **Note:** This package currently uses:
> - **LLVM 21.1.5** for Windows and Linux
> - **LLVM 19.1.6** for macOS (21.1.5 coming soon)
>
> See [Platform Support Matrix](#-platform-support-matrix) for details.

### ⚠️ Windows Users: GNU ABI by Default (v2.0+)

**IMPORTANT:** Starting with v2.0.0, Windows defaults to GNU ABI (MinGW-w64) for cross-platform consistency.

This matches the behavior of [zig cc](https://ziglang.org/learn/overview/#cross-compiling-is-a-first-class-use-case) and ensures consistent C++ ABI across all platforms.

**What this means:**
- ✅ **C++11 strict mode works** - No C++14 extensions in standard library headers
- ✅ **Cross-platform consistency** - Same ABI on Windows/Linux/macOS
- ✅ **Arduino/embedded compatibility** - Matches GCC/GNU toolchain behavior
- ⚠️ **Cannot link with MSVC libraries** - Different C++ ABI (use MSVC variant if needed)

**Default behavior (GNU ABI):**
```bash
clang-tool-chain-c main.c -o program       # Uses x86_64-w64-mingw32 target
clang-tool-chain-cpp main.cpp -o program   # Uses GNU ABI, libc++ stdlib
```

**For MSVC ABI (Windows-specific projects):**
```bash
clang-tool-chain-c-msvc main.c -o program.exe     # Uses x86_64-pc-windows-msvc
clang-tool-chain-cpp-msvc main.cpp -o program.exe # Uses MSVC ABI, MSVC stdlib

# With sccache for compilation caching
clang-tool-chain-sccache-c-msvc main.c -o program.exe
clang-tool-chain-sccache-cpp-msvc main.cpp -o program.exe
```

**Download sizes:**
- **First run (GNU target):** ~100-120 MB (includes MinGW-w64 sysroot)
- **MSVC variant:** ~50 MB (uses Visual Studio SDK if available)

**Windows SDK Requirements:**

MSVC variants require Visual Studio or Windows SDK for system headers/libraries. The package automatically:
- ✅ Detects SDK via environment variables (WindowsSdkDir, VCToolsInstallDir, etc.)
- ⚠️ Shows helpful setup instructions if SDK not found
- 🔧 Suggests alternatives (Visual Studio Dev Prompt, vcvarsall.bat, or GNU ABI)

**When to use MSVC variant:**
- Linking with MSVC-compiled libraries (DLLs with C++ APIs)
- Windows-specific projects requiring Visual Studio integration
- COM/WinRT/Windows Runtime components
- Using Windows SDK features not available in MinGW

**When to use GNU ABI (default):**
- Cross-platform projects (same ABI on all platforms)
- Strict C++11 mode (MSVC requires C++14 extensions)
- No Windows SDK installation required
- Arduino/embedded projects (matches GCC)

### 📋 Command Quick Reference

| Task | Command (Default) | Windows MSVC Variant |
|------|-------------------|---------------------|
| **Compile C** | `clang-tool-chain-c main.c -o program` | `clang-tool-chain-c-msvc main.c -o program.exe` |
| **Compile C++** | `clang-tool-chain-cpp main.cpp -o program` | `clang-tool-chain-cpp-msvc main.cpp -o program.exe` |
| **Cached C** | `clang-tool-chain-sccache-c main.c -o program` | `clang-tool-chain-sccache-c-msvc main.c -o program.exe` |
| **Cached C++** | `clang-tool-chain-sccache-cpp main.cpp -o program` | `clang-tool-chain-sccache-cpp-msvc main.cpp -o program.exe` |
| **Link Objects** | `clang-tool-chain-ld obj1.o obj2.o -o program` | N/A (use compiler) |
| **Create Library** | `clang-tool-chain-ar rcs libname.a obj1.o obj2.o` | Same |
| **Format Code** | `clang-tool-chain-format -i file.cpp` | Same |
| **Check Installation** | `clang-tool-chain info` | Same |
| **Verify Setup** | `clang-tool-chain-test` | Same |

**Note:** MSVC variants (`*-msvc`) are Windows-only and require Visual Studio or Windows SDK. Automatic SDK detection with helpful error messages included.

---

## 📦 Installation

### From PyPI (Recommended)

```bash
pip install clang-tool-chain
```

### From Source

```bash
# Clone the repository
git clone https://github.com/zackees/clang-tool-chain.git
cd clang-tool-chain

# Install dependencies
./install

# Or manually with uv
uv venv --python 3.11
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"
```

**Note:** Binaries download automatically on first use. No manual setup required!

**macOS Users:** Requires Xcode Command Line Tools for system headers. Run `xcode-select --install` if not already installed.

---

## 🎯 Why clang-tool-chain?

### The Problem

Installing LLVM/Clang traditionally requires:
- Large downloads (1-3 GB installer/archive)
- System-wide installation with admin privileges
- Manual PATH configuration
- Platform-specific installation procedures
- Version management headaches in CI/CD

### The Solution

`clang-tool-chain` provides:

| Feature | clang-tool-chain | Full LLVM Install | System Compiler | zig cc |
|---------|------------------|-------------------|-----------------|--------|
| **Size** | 52-91 MB | 1-3 GB | Varies | ~80 MB |
| **Setup Time** | < 30 seconds | 5-15 minutes | Varies | < 30 seconds |
| **Admin Required** | ❌ No | ✅ Yes (usually) | ✅ Yes | ❌ No |
| **Auto Download** | ✅ Yes | ❌ No | ❌ No | ✅ Yes |
| **Version Control** | ✅ Pin in requirements | ❌ System-wide | ❌ System-wide | ⚠️ Tied to Zig version |
| **Cross-Platform** | ✅ Identical on all OS | ❌ Different procedures | ❌ Different versions | ✅ Yes |
| **Cross-Compilation** | Platform-specific | ❌ Complex | ❌ Complex | ✅ Single binary, all targets |
| **CI/CD Ready** | ✅ Zero config | ❌ Complex setup | ⚠️ Depends on runner | ✅ Zero config |
| **Offline After DL** | ✅ Yes | ✅ Yes | ✅ Yes | ✅ Yes |
| **Python Integration** | ✅ Native | ❌ Manual | ❌ Manual | ❌ Manual |

### Perfect For

- **CI/CD Pipelines** - Reproducible builds with pinned toolchain versions
- **Educational Environments** - Students get started instantly without installation hassles
- **Development Teams** - Everyone uses the exact same compiler version
- **Containerized Builds** - Minimal Docker image overhead
- **Python Projects** - Seamless integration with Python build systems

### Not Recommended For

- **Production Embedded Systems** - Use vendor-specific toolchains
- **Kernel Development** - System compilers with specific patches
- **Custom LLVM Builds** - If you need specific LLVM patches/features
- **Air-Gapped Environments** - Requires manual setup (see [Offline Mode](#offline-mode))
- **Cross-Compilation to Different Architectures** - Use `zig cc` for multi-target cross-compilation

---

## ✨ Features

- **Automatic Download on First Use** - Zero-configuration installation to `~/.clang-tool-chain/`
- **Manifest-Based Distribution** - Version-controlled releases with SHA256 checksum verification
- **Ultra-Optimized Archives** - 94.3% size reduction via binary stripping, deduplication, and zstd-22 compression
- **Cross-Platform Support** - Windows x64, macOS x64/ARM64, Linux x64/ARM64
- **Concurrent-Safe Installation** - File locking prevents race conditions in parallel builds
- **Python Wrapper Commands** - 22 entry points for all essential LLVM tools
- **Pre-Built Binaries** - Clang 21.1.5 (Linux/Windows), 19.1.6 (macOS)
- **Essential Toolchain Utilities** - Compilers, linkers, binary utilities, and code formatters
- **Automatic macOS SDK Detection** - Seamlessly finds system headers on macOS without configuration

---

## 🚀 Usage

### CLI Commands

Manage your toolchain installation:

```bash
# Show installation information and available tools
clang-tool-chain info

# Run diagnostic tests (verify installation)
clang-tool-chain test

# List all available wrapper commands
clang-tool-chain list-tools

# Show version of a specific tool
clang-tool-chain version clang
clang-tool-chain version clang++

# Show path to binaries directory
clang-tool-chain path

# Show path to specific tool
clang-tool-chain path clang

# Show package and LLVM versions
clang-tool-chain package-version
```

### Wrapper Commands

#### Compiling C Code

```bash
# Simple compilation
clang-tool-chain-c hello.c -o hello

# With optimization
clang-tool-chain-c -O2 hello.c -o hello

# With debugging symbols
clang-tool-chain-c -g hello.c -o hello

# Check version
clang-tool-chain-c --version
```

#### Compiling C++ Code

```bash
# Simple compilation
clang-tool-chain-cpp hello.cpp -o hello

# With C++20 standard
clang-tool-chain-cpp -std=c++20 hello.cpp -o hello

# With optimization and warnings
clang-tool-chain-cpp -O3 -Wall -Wextra hello.cpp -o hello

# Check version
clang-tool-chain-cpp --version
```

#### Using the Build Utility

The `clang-tool-chain-build` command provides a simple way to compile projects:

```bash
# Build a single C file
clang-tool-chain-build hello.c

# Build a C++ file with custom output name
clang-tool-chain-build hello.cpp -o myprogram

# Build with optimization
clang-tool-chain-build -O2 hello.c
```

#### CMake Integration

**Option 1: Environment Variables (Recommended)**

```cmake
# CMakeLists.txt
cmake_minimum_required(VERSION 3.15)
project(MyProject)

# No changes needed - respects CC/CXX environment variables
add_executable(myapp main.cpp)
```

```bash
export CC=clang-tool-chain-c
export CXX=clang-tool-chain-cpp
cmake -B build
cmake --build build
```

**Option 2: Direct Compiler Specification**

```bash
cmake -B build \
    -DCMAKE_C_COMPILER=clang-tool-chain-c \
    -DCMAKE_CXX_COMPILER=clang-tool-chain-cpp
cmake --build build
```

#### Linking

```bash
# Link object files
clang-tool-chain-ld obj1.o obj2.o -o program

# Create shared library (Linux/macOS)
clang-tool-chain-ld -shared obj1.o obj2.o -o libmylib.so

# Create DLL (Windows)
clang-tool-chain-ld -shared obj1.o obj2.o -o mylib.dll
```

#### Binary Utilities

```bash
# Create static library
clang-tool-chain-ar rcs libmylib.a obj1.o obj2.o

# List symbols in binary
clang-tool-chain-nm program

# List symbols in library
clang-tool-chain-nm libmylib.a

# Disassemble binary
clang-tool-chain-objdump -d program

# Show all headers
clang-tool-chain-objdump -x program

# Strip debug symbols
clang-tool-chain-strip program -o program.stripped

# Copy and modify object files
clang-tool-chain-objcopy --strip-debug program program.stripped

# Generate archive index
clang-tool-chain-ranlib libmylib.a

# Read ELF headers (Linux)
clang-tool-chain-readelf -h program

# Show program headers
clang-tool-chain-readelf -l program
```

#### Code Formatting and Analysis

```bash
# Format C/C++ code (in-place)
clang-tool-chain-format -i myfile.cpp

# Format with specific style
clang-tool-chain-format -i -style=LLVM myfile.cpp

# Check formatting (don't modify)
clang-tool-chain-format myfile.cpp

# Run static analysis
clang-tool-chain-tidy myfile.cpp -- -std=c++17

# Run with specific checks
clang-tool-chain-tidy -checks='-*,readability-*' myfile.cpp --
```

#### sccache Integration (Optional)

Speed up repeated builds with compilation caching:

```bash
# Install with sccache support
pip install clang-tool-chain[sccache]
# Or: cargo install sccache

# Compile with sccache caching
clang-tool-chain-sccache-c main.c -o main
clang-tool-chain-sccache-cpp main.cpp -o main

# Query cache statistics
clang-tool-chain-sccache --show-stats

# Clear cache statistics
clang-tool-chain-sccache --zero-stats

# Manage sccache server
clang-tool-chain-sccache --start-server
clang-tool-chain-sccache --stop-server
clang-tool-chain-sccache --version
```

**How it works:**
- Caches compilation results locally for faster rebuilds
- Transparent caching layer on top of clang
- Requires `sccache` binary in PATH
- Works with distributed caching backends (optional)

### All Available Commands

| Command | Tool | Description |
|---------|------|-------------|
| `clang-tool-chain` | CLI | Main management interface |
| `clang-tool-chain-test` | Diagnostic | Run 7 diagnostic tests to verify installation |
| `clang-tool-chain-fetch` | Fetch utility | Manual download utility for pre-fetching binaries |
| `clang-tool-chain-paths` | Path utility | Get installation paths in JSON format |
| `clang-tool-chain-fetch-archive` | Archive utility | Maintainer tool for creating optimized archives |
| `clang-tool-chain-c` | `clang` | C compiler (GNU ABI on Windows) |
| `clang-tool-chain-cpp` | `clang++` | C++ compiler (GNU ABI on Windows) |
| `clang-tool-chain-c-msvc` | `clang` | C compiler (MSVC ABI, Windows only) |
| `clang-tool-chain-cpp-msvc` | `clang++` | C++ compiler (MSVC ABI, Windows only) |
| `clang-tool-chain-build` | Build utility | Simple build tool for C/C++ |
| `clang-tool-chain-sccache` | `sccache` | Direct sccache access (stats, management) |
| `clang-tool-chain-sccache-c` | `sccache` + `clang` | C compiler with sccache caching |
| `clang-tool-chain-sccache-cpp` | `sccache` + `clang++` | C++ compiler with sccache caching |
| `clang-tool-chain-ld` | `lld` / `lld-link` | LLVM linker |
| `clang-tool-chain-ar` | `llvm-ar` | Archive/library creator |
| `clang-tool-chain-nm` | `llvm-nm` | Symbol table viewer |
| `clang-tool-chain-objdump` | `llvm-objdump` | Object file dumper/disassembler |
| `clang-tool-chain-objcopy` | `llvm-objcopy` | Object file copier/modifier |
| `clang-tool-chain-ranlib` | `llvm-ranlib` | Archive index generator |
| `clang-tool-chain-strip` | `llvm-strip` | Symbol stripper |
| `clang-tool-chain-readelf` | `llvm-readelf` | ELF file reader |
| `clang-tool-chain-as` | `llvm-as` | LLVM assembler |
| `clang-tool-chain-dis` | `llvm-dis` | LLVM disassembler |
| `clang-tool-chain-format` | `clang-format` | Code formatter |
| `clang-tool-chain-tidy` | `clang-tidy` | Static analyzer/linter |

---

## 📚 Examples

### Hello World (C)

```c
// hello.c
#include <stdio.h>

int main() {
    printf("Hello from clang-tool-chain!\n");
    return 0;
}
```

```bash
clang-tool-chain-c hello.c -o hello
./hello
```

### Hello World (C++)

```cpp
// hello.cpp
#include <iostream>

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

```bash
clang-tool-chain-cpp hello.cpp -o hello
./hello
```

### Multi-File Compilation

```c
// math_ops.h
#ifndef MATH_OPS_H
#define MATH_OPS_H
int add(int a, int b);
int multiply(int a, int b);
#endif

// math_ops.c
#include "math_ops.h"
int add(int a, int b) { return a + b; }
int multiply(int a, int b) { return a * b; }

// main.c
#include <stdio.h>
#include "math_ops.h"

int main() {
    printf("5 + 3 = %d\n", add(5, 3));
    printf("5 * 3 = %d\n", multiply(5, 3));
    return 0;
}
```

```bash
# Compile and link in one step
clang-tool-chain-c main.c math_ops.c -o program
./program

# Or compile separately then link
clang-tool-chain-c -c math_ops.c -o math_ops.o
clang-tool-chain-c -c main.c -o main.o
clang-tool-chain-c main.o math_ops.o -o program
./program
```

### Creating a Static Library

```bash
# Compile source files to object files
clang-tool-chain-c -c math_ops.c -o math_ops.o
clang-tool-chain-c -c string_ops.c -o string_ops.o

# Create static library
clang-tool-chain-ar rcs libmylib.a math_ops.o string_ops.o

# Generate archive index (optional but recommended)
clang-tool-chain-ranlib libmylib.a

# Link against the library
clang-tool-chain-c main.c -L. -lmylib -o program
./program
```

### Cross-Platform Build Script

```bash
#!/bin/bash
# build.sh - Cross-platform build script

set -e

# Compile
echo "Compiling..."
clang-tool-chain-c -O2 -Wall -Wextra src/*.c -o myprogram

# Strip symbols for release
echo "Stripping symbols..."
clang-tool-chain-strip myprogram -o myprogram.release

echo "Build complete: myprogram.release"
```

---

## 🚀 CI/CD Integration

### GitHub Actions

```yaml
# .github/workflows/build.yml
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

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: '3.11'

      - name: Install clang-tool-chain
        run: pip install clang-tool-chain

      - name: Compile project
        run: |
          clang-tool-chain-c src/main.c -o program
          ./program  # Binaries download automatically on first use!

      - name: Upload artifact
        uses: actions/upload-artifact@v3
        with:
          name: program-${{ matrix.os }}
          path: program*
```

### GitLab CI

```yaml
# .gitlab-ci.yml
image: python:3.11

stages:
  - build
  - test

build:
  stage: build
  script:
    - pip install clang-tool-chain
    - clang-tool-chain-c src/main.c -o program  # Auto-downloads on first use
    - clang-tool-chain-strip program
  artifacts:
    paths:
      - program

test:
  stage: test
  script:
    - ./program
```

### Docker

```dockerfile
# Dockerfile
FROM python:3.11-slim

# Install clang-tool-chain
RUN pip install clang-tool-chain

# Pre-download binaries (optional - they auto-download on first use)
RUN clang-tool-chain info || true

# Copy source code
COPY src/ /app/src/
WORKDIR /app

# Build
RUN clang-tool-chain-c src/main.c -o program

CMD ["./program"]
```

**Build and run:**
```bash
docker build -t myapp .
docker run myapp
```

### Azure Pipelines

```yaml
# azure-pipelines.yml
trigger:
  - main

pool:
  vmImage: 'ubuntu-latest'

steps:
- task: UsePythonVersion@0
  inputs:
    versionSpec: '3.11'

- script: |
    pip install clang-tool-chain
    clang-tool-chain-c src/main.c -o program
  displayName: 'Build with clang-tool-chain'

- task: PublishBuildArtifacts@1
  inputs:
    pathToPublish: 'program'
    artifactName: 'executable'
```

---

## 🌍 Platform Support Matrix

| Platform | Architecture | LLVM Version | Archive Size | Installed Size | Status |
|----------|--------------|--------------|--------------|----------------|--------|
| Windows  | x86_64       | 21.1.5       | ~100 MB*     | ~350 MB        | ✅ Stable |
| Linux    | x86_64       | 21.1.5       | ~88 MB       | ~350 MB        | ✅ Stable |
| Linux    | ARM64        | 21.1.5       | ~91 MB       | ~340 MB        | ✅ Stable |
| macOS    | x86_64       | 19.1.6       | ~75 MB       | ~300 MB        | ✅ Stable |
| macOS    | ARM64        | 19.1.6       | ~71 MB       | ~285 MB        | ✅ Stable |

\* **Windows Downloads:**
  - **GNU target (default):** ~100 MB (LLVM + MinGW-w64 sysroot)
  - **MSVC target (opt-in):** ~50 MB (LLVM only, requires Visual Studio SDK)

**Note:** macOS uses LLVM 19.1.6 due to availability of pre-built binaries. LLVM 21.1.5 support coming soon.

### Requirements

- **Python**: 3.10 or higher
- **Disk Space**: ~100 MB for archive + ~200-350 MB installed
- **Internet**: Required for initial download (works offline after installation)
- **Operating System**:
  - Windows 10+ (x64)
  - macOS 11+ (x64 or ARM64/Apple Silicon) - **Requires Xcode Command Line Tools**: `xcode-select --install`
  - Linux with glibc 2.27+ (x64 or ARM64)

---

## ⚙️ Configuration

### Environment Variables

- **`CLANG_TOOL_CHAIN_DOWNLOAD_PATH`**: Override default installation location

  ```bash
  # Linux/macOS
  export CLANG_TOOL_CHAIN_DOWNLOAD_PATH=/custom/path
  clang-tool-chain-c hello.c -o hello

  # Windows
  set CLANG_TOOL_CHAIN_DOWNLOAD_PATH=C:\custom\path
  clang-tool-chain-c hello.c -o hello
  ```

  **Use cases:**
  - Testing different toolchain versions
  - Shared installations across projects
  - Network or cache drives
  - CI/CD artifact caching

### macOS SDK Detection (Automatic)

macOS users no longer need to manually configure SDK paths! The toolchain automatically detects your Xcode Command Line Tools SDK using `xcrun`.

**Requirements:**
```bash
xcode-select --install  # One-time setup
```

**How it works:**
- Automatically injects `-isysroot` when compiling on macOS
- Detects SDK via `xcrun --show-sdk-path`
- Respects `SDKROOT` environment variable if set
- Uses explicit `-isysroot` flag if provided by user
- Disabled with `CLANG_TOOL_CHAIN_NO_SYSROOT=1`

**Advanced Configuration:**
```bash
# Use custom SDK path (standard macOS variable)
export SDKROOT=/Library/Developer/CommandLineTools/SDKs/MacOSX.sdk

# Disable automatic SDK detection (not recommended)
export CLANG_TOOL_CHAIN_NO_SYSROOT=1

# Explicit SDK path (takes priority)
clang-tool-chain-c -isysroot /path/to/sdk hello.c -o hello
```

**Automatic injection is skipped when:**
- User explicitly provides `-isysroot` in arguments
- `SDKROOT` environment variable is set
- Freestanding compilation flags are used (`-nostdinc`, `-nostdinc++`, `-nostdlib`, `-ffreestanding`)
- `CLANG_TOOL_CHAIN_NO_SYSROOT=1` is set

No configuration needed - just compile!

---

## ⚡ Performance

### Compilation Speed

clang-tool-chain uses unmodified LLVM binaries - expect **identical performance** to official LLVM releases.

### Download Benchmarks (First Use)

| Connection | Archive Size | Download Time |
|------------|--------------|---------------|
| Fiber (100 Mbps) | 52 MB | ~5 seconds |
| Cable (20 Mbps) | 52 MB | ~25 seconds |
| DSL (5 Mbps) | 52 MB | ~90 seconds |

Subsequent compilations are **instant** (no download).

---

## 🎯 Windows Target Selection

### Default Behavior (GNU ABI - Recommended)

The default Windows target is `x86_64-w64-mingw32` (GNU ABI) for cross-platform consistency:

```bash
# These commands use GNU ABI by default on Windows:
clang-tool-chain-c hello.c -o hello
clang-tool-chain-cpp hello.cpp -o hello

# Equivalent to explicitly specifying:
clang-tool-chain-c --target=x86_64-w64-mingw32 hello.c -o hello
```

**Why GNU ABI is default:**
1. **Cross-platform consistency** - Same ABI on Linux/macOS/Windows
2. **C++11 strict mode support** - MSVC headers require C++14 features even in C++11 mode
3. **Embedded/Arduino compatibility** - Matches GCC toolchain behavior
4. **Modern C++ standard library** - Uses LLVM's libc++ (same as macOS/Linux)

This matches the approach of [zig cc](https://ziglang.org/learn/overview/#cross-compiling-is-a-first-class-use-case) and other modern cross-platform toolchains.

### MSVC ABI (Windows-Specific Projects)

For Windows-native projects that need MSVC compatibility:

```bash
# Use MSVC variants for Windows-specific development:
clang-tool-chain-c-msvc main.c -o program.exe
clang-tool-chain-cpp-msvc main.cpp -o program.exe

# Or explicitly specify MSVC target with default commands:
clang-tool-chain-c --target=x86_64-pc-windows-msvc main.c -o program.exe
```

**Use MSVC ABI when:**
- Linking with MSVC-compiled DLLs (with C++ APIs)
- Using Windows SDK features not in MinGW
- Requiring Visual Studio debugger integration
- Building COM/WinRT/Windows Runtime components

### Comparison Table

| Feature | GNU ABI (Default) | MSVC ABI (Opt-in) |
|---------|------------------|------------------|
| **C++ Standard Library** | libc++ (LLVM) | MSVC STL |
| **C++ ABI** | Itanium (like GCC) | Microsoft |
| **Cross-platform consistency** | ✅ Yes | ❌ Windows-only |
| **C++11 strict mode** | ✅ Works | ❌ Requires C++14+ |
| **Link with MSVC libs** | ❌ C++ ABI mismatch | ✅ Compatible |
| **Arduino/embedded** | ✅ Compatible | ❌ Different ABI |
| **Download size** | ~100 MB | ~50 MB |
| **Requires Visual Studio** | ❌ No | ⚠️ Recommended |

### Advanced: Manual Target Selection

You can override the target for any compilation:

```bash
# Force GNU target (default on Windows anyway):
clang-tool-chain-c --target=x86_64-w64-mingw32 main.c

# Force MSVC target:
clang-tool-chain-c --target=x86_64-pc-windows-msvc main.c

# Cross-compile for Linux from Windows:
clang-tool-chain-c --target=x86_64-unknown-linux-gnu main.c

# Cross-compile for macOS from Windows:
clang-tool-chain-c --target=arm64-apple-darwin main.c
```

**Note:** Cross-compilation requires appropriate sysroots (not included by default).

---

## 🔧 How It Works

### Architecture Overview

`clang-tool-chain` uses a sophisticated three-layer architecture:

```
┌─────────────────────────────────────────────────────────────┐
│                    CLI Layer (cli.py)                        │
│  Commands: info, version, list-tools, path, package-version  │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│                 Wrapper Layer (wrapper.py)                   │
│  • Platform Detection (win/linux/darwin)                     │
│  • Architecture Normalization (x86_64/arm64)                 │
│  • Binary Resolution (.exe handling, tool alternatives)      │
│  • Process Execution (os.execv on Unix, subprocess on Win)   │
│  • macOS SDK Auto-Detection (xcrun integration)              │
└─────────────────────────────────────────────────────────────┘
                              ↓
┌─────────────────────────────────────────────────────────────┐
│              Downloader Layer (downloader.py)                │
│  • Fetch root manifest from GitHub                          │
│  • Fetch platform-specific manifest                         │
│  • Download .tar.zst archive with progress                  │
│  • Verify SHA256 checksum                                   │
│  • Extract with pyzstd decompression                        │
│  • File locking (prevents concurrent downloads)             │
│  • Atomic installation with 'done.txt' marker               │
└─────────────────────────────────────────────────────────────┘
```

### Manifest-Based Distribution System

The package uses a **two-tier manifest system** for version management:

1. **Root Manifest** (`downloads-bins/assets/clang/manifest.json`) - Indexes all platforms and architectures
2. **Platform Manifests** (`downloads-bins/assets/clang/{platform}/{arch}/manifest.json`) - Contains version info, download URLs, and SHA256 checksums

**On first use:**
```
User runs: clang-tool-chain-c hello.c -o hello
    ↓
Check: ~/.clang-tool-chain/{platform}/{arch}/done.txt exists?
    ↓ (No)
Acquire lock: ~/.clang-tool-chain/{platform}-{arch}.lock
    ↓
Fetch: Root manifest → Platform manifest
    ↓
Download: .tar.zst archive to temp directory
    ↓
Verify: SHA256 checksum
    ↓
Extract: Using pyzstd + tarfile (with safety filters)
    ↓
Mark complete: Write done.txt
    ↓
Release lock → Execute tool
```

### Platform Detection

Automatic platform and architecture detection:

| System | Platform | Architecture | Install Path |
|--------|----------|--------------|--------------|
| Windows 10+ | `win` | `x86_64` | `~/.clang-tool-chain/clang/win/x86_64/` |
| Linux | `linux` | `x86_64` | `~/.clang-tool-chain/clang/linux/x86_64/` |
| Linux | `linux` | `arm64` | `~/.clang-tool-chain/clang/linux/arm64/` |
| macOS | `darwin` | `x86_64` | `~/.clang-tool-chain/clang/darwin/x86_64/` |
| macOS | `darwin` | `arm64` | `~/.clang-tool-chain/clang/darwin/arm64/` |

### Binary Resolution

The wrapper automatically handles platform differences:
- **Windows**: Adds `.exe` extension, uses `lld-link` instead of `lld`
- **Unix**: Uses `lld` or `ld.lld`, handles `chmod +x` permissions
- **macOS**: Automatically detects and injects SDK path via `xcrun`
- **Alternative Names**: Supports tool aliases (e.g., `clang` → `clang-cl` on Windows)

---

## 🔧 Additional Utilities

### clang-tool-chain-test

Run diagnostic tests to verify your installation:

```bash
# Run 7 diagnostic tests
clang-tool-chain-test

# Or via main CLI:
clang-tool-chain test
```

**Tests performed:**
1. Platform detection
2. Toolchain installation verification
3. clang binary resolution
4. clang++ binary resolution
5. clang version check
6. C compilation test
7. C++ compilation test

This command is especially useful for debugging installation issues in GitHub Actions or other CI/CD environments.

### clang-tool-chain-fetch

Manual download utility for pre-fetching binaries:

```bash
# Fetch binaries for current platform
clang-tool-chain-fetch

# Check what would be downloaded
clang-tool-chain-fetch --dry-run
```

### clang-tool-chain-paths

Get installation paths in JSON format (useful for scripting):

```bash
# Get all paths
clang-tool-chain-paths

# Example output:
# {
#   "install_dir": "/home/user/.clang-tool-chain/clang/linux/x86_64",
#   "bin_dir": "/home/user/.clang-tool-chain/clang/linux/x86_64/bin",
#   "clang": "/home/user/.clang-tool-chain/clang/linux/x86_64/bin/clang"
# }
```

```bash
# Use in scripts
BIN_DIR=$(clang-tool-chain-paths | python -c "import sys,json; print(json.load(sys.stdin)['bin_dir'])")
echo "Binaries located at: $BIN_DIR"
```

---

## 🔬 Advanced Topics

### Manual Installation (Without Auto-Download)

If you need to manually install binaries (e.g., for offline environments):

1. **Download archive:**
   ```bash
   wget https://raw.githubusercontent.com/zackees/clang-tool-chain-bins/main/assets/clang/win/x86_64/llvm-21.1.5-win-x86_64.tar.zst
   ```

2. **Extract to installation directory:**
   ```bash
   # Create installation directory
   mkdir -p ~/.clang-tool-chain/clang/win/x86_64

   # Extract archive
   python -m clang_tool_chain.downloads.expand_archive \
       llvm-21.1.5-win-x86_64.tar.zst \
       ~/.clang-tool-chain/clang/win/x86_64

   # Mark as complete
   touch ~/.clang-tool-chain/clang/win/x86_64/done.txt
   ```

3. **Verify installation:**
   ```bash
   clang-tool-chain info
   ```

### Offline Mode

After initial download, `clang-tool-chain` works completely offline:

```bash
# First use (requires internet)
clang-tool-chain-c hello.c -o hello  # Downloads binaries

# Subsequent uses (offline)
clang-tool-chain-c world.c -o world  # Uses cached binaries
```

**For fully offline environments:**
1. Pre-download binaries on a machine with internet
2. Package `~/.clang-tool-chain/` directory
3. Extract to target machines
4. Ensure `done.txt` exists in platform directory

### Version Pinning

Pin specific LLVM versions in `requirements.txt`:

```txt
# requirements.txt
clang-tool-chain==1.0.1  # Pins package version (currently uses LLVM 21.1.5/19.1.6)
```

**Future:** The package will support multiple LLVM versions via manifest updates.

### Concurrent Build Safety

The downloader uses **file locking** (`fasteners.InterProcessLock`) to prevent race conditions:

```python
# Multiple processes can safely call this simultaneously
clang-tool-chain-c hello.c -o hello  # Process 1
clang-tool-chain-c world.c -o world  # Process 2
```

**What happens:**
1. Process 1 acquires lock `~/.clang-tool-chain/win-x86_64.lock`
2. Process 2 waits for lock
3. Process 1 downloads and installs binaries
4. Process 1 writes `done.txt` and releases lock
5. Process 2 acquires lock, sees `done.txt`, skips download
6. Both processes compile successfully

**Perfect for:**
- Parallel CI/CD builds
- Multi-core test runners
- Concurrent development environments

---

## ❓ FAQ

### What happens on first use?

On first use, `clang-tool-chain` automatically:
1. Detects your platform and architecture
2. Fetches the manifest for your platform
3. Downloads the appropriate archive (~52-91 MB)
4. Verifies the SHA256 checksum
5. Extracts to `~/.clang-tool-chain/clang/{platform}/{arch}/`
6. Executes your command

**Total time:** ~10-60 seconds depending on internet speed.

### Can I use clang-tool-chain offline?

Yes! After the initial download, `clang-tool-chain` works completely offline. The binaries are cached in `~/.clang-tool-chain/`.

### How do I update to a new LLVM version?

Currently, the LLVM version is tied to the package version. To update:
```bash
pip install --upgrade clang-tool-chain
```

Future versions will support multiple LLVM versions via manifest updates.

### Is it safe to delete `~/.clang-tool-chain/`?

Yes! Deleting this directory just removes the cached binaries. They will re-download automatically on next use.

### Can I use multiple LLVM versions simultaneously?

Not currently. Each `clang-tool-chain` package version maps to specific LLVM versions (see Platform Support Matrix). Use virtual environments to isolate different package versions:

```bash
# Environment 1: LLVM 21.1.5
python -m venv env1
source env1/bin/activate
pip install clang-tool-chain==1.0.1

# Environment 2: Future LLVM version
python -m venv env2
source env2/bin/activate
pip install clang-tool-chain==1.1.0  # (hypothetical future version)
```

### How does checksum verification work?

Every archive download is verified against SHA256 checksums stored in the platform manifests. If the checksum doesn't match, the download is rejected and an error is raised. This protects against:
- Corrupted downloads
- Man-in-the-middle attacks
- File tampering

### Why does macOS use LLVM 19.1.6 instead of 21.1.5?

LLVM 21.1.5 pre-built binaries for macOS were not available at the time of initial release. We're working on building and distributing LLVM 21.1.5 for macOS. Track progress in the repository issues.

### Can I contribute new platforms or architectures?

Yes! See the [Maintainer Tools](#-maintainer-tools) section for how to create optimized archives. Pull requests welcome!

### Does this work in Docker containers?

Absolutely! See the [CI/CD Integration](#-cicd-integration) section for Docker examples. The automatic download works seamlessly in containers.

### How much disk space do I need?

- **Download:** ~52-91 MB (archive)
- **Installed:** ~200-350 MB (extracted binaries)
- **Total:** ~252-441 MB per platform

The archive is deleted after extraction, so you only need space for the installed binaries.

### Can I use this with CMake?

Yes! Set the compiler in your `CMakeLists.txt` or via environment variables:

```bash
# Option 1: Environment variables
export CC=clang-tool-chain-c
export CXX=clang-tool-chain-cpp
cmake -B build

# Option 2: CMake command line
cmake -B build \
    -DCMAKE_C_COMPILER=clang-tool-chain-c \
    -DCMAKE_CXX_COMPILER=clang-tool-chain-cpp
```

### What about Windows paths with spaces?

All paths are handled correctly, including those with spaces. The wrappers quote paths appropriately.

### Do I need to install Xcode on macOS?

No! You only need the **Xcode Command Line Tools**, which is much smaller:

```bash
xcode-select --install
```

This provides the SDK headers needed for compilation without installing the full Xcode IDE.

---

## 🔍 Troubleshooting

### Binaries Not Found

**Error:** `Clang binaries are not installed`

**Solution:**
```bash
# Check installation status
clang-tool-chain info

# Try manual fetch
clang-tool-chain-fetch

# Verify installation directory exists
ls ~/.clang-tool-chain/
```

### Platform Not Supported

**Error:** `Unsupported platform`

**Solution:** Ensure you're on a supported platform:
- Windows 10+ (x64)
- Linux x64 or ARM64 (glibc 2.27+)
- macOS 11+ (x64 or ARM64)

32-bit systems are **not supported**.

### Download Fails

**Error:** `Failed to download archive` or `Checksum verification failed`

**Solutions:**
1. **Check internet connection**
2. **Retry the command** (temporary network issue)
3. **Check GitHub raw content access:**
   ```bash
   curl -I https://raw.githubusercontent.com/zackees/clang-tool-chain-bins/main/assets/clang/manifest.json
   ```
4. **Clear partial downloads:**
   ```bash
   rm -rf ~/.clang-tool-chain/
   ```

### Tool Execution Fails

**Error:** `Permission denied` (Linux/macOS)

**Solution:**
```bash
# Ensure execute permissions
chmod +x ~/.clang-tool-chain/clang/*/bin/*

# Or reinstall
rm -rf ~/.clang-tool-chain/
clang-tool-chain-c --version  # Re-downloads with correct permissions
```

### macOS: stdio.h or iostream Not Found

**Error:** `fatal error: 'stdio.h' file not found` or `'iostream' file not found`

**Cause:** Xcode Command Line Tools not installed or SDK not detected.

**Solution:**
```bash
# Install Xcode Command Line Tools
xcode-select --install

# Verify SDK is detected
xcrun --show-sdk-path

# Should output something like:
# /Library/Developer/CommandLineTools/SDKs/MacOSX.sdk

# Try compilation again
clang-tool-chain-c hello.c -o hello
```

**Advanced troubleshooting:**
```bash
# Manually specify SDK path
clang-tool-chain-c -isysroot $(xcrun --show-sdk-path) hello.c -o hello

# Or set SDKROOT environment variable
export SDKROOT=$(xcrun --show-sdk-path)
clang-tool-chain-c hello.c -o hello
```

### Slow First-Time Download

**Observation:** First compilation takes 30-60 seconds

**This is normal!** The toolchain is downloading. Subsequent compilations are instant. To pre-download:

```bash
# Pre-fetch binaries before your build
clang-tool-chain-fetch

# Or just run any command
clang-tool-chain-c --version
```

### Import Errors

**Error:** `ModuleNotFoundError: No module named 'clang_tool_chain'`

**Solutions:**
1. **Ensure package is installed:**
   ```bash
   pip install clang-tool-chain
   ```

2. **Check Python environment:**
   ```bash
   which python  # Verify correct Python interpreter
   pip list | grep clang-tool-chain
   ```

3. **Reinstall:**
   ```bash
   pip uninstall clang-tool-chain
   pip install clang-tool-chain
   ```

### Custom Installation Path Not Working

**Error:** Binaries install to default location despite `CLANG_TOOL_CHAIN_DOWNLOAD_PATH`

**Solution:** Ensure the environment variable is set **before** running the command:

```bash
# Linux/macOS
export CLANG_TOOL_CHAIN_DOWNLOAD_PATH=/custom/path
clang-tool-chain-c hello.c

# Windows (CMD)
set CLANG_TOOL_CHAIN_DOWNLOAD_PATH=C:\custom\path
clang-tool-chain-c hello.c

# Windows (PowerShell)
$env:CLANG_TOOL_CHAIN_DOWNLOAD_PATH="C:\custom\path"
clang-tool-chain-c hello.c
```

---

## 🔒 Security

Security is a top priority for this project.

### Checksum Verification

- **Automatic:** SHA256 checksums are verified during download (enabled by default)
- **Manifest-Based:** Checksums stored in version-controlled manifests
- **Protection:** Detects corrupted downloads, MITM attacks, and file tampering
- **Transparency:** All checksums visible in `downloads-bins/assets/clang/{platform}/{arch}/manifest.json`

### Safe Extraction

- **Python 3.12+ Tarfile Safety:** Uses `filter="data"` to prevent path traversal attacks
- **Temporary Directory:** Extraction happens in temp directory, then moved atomically
- **Validation:** Verifies archive integrity before extraction

### Download Security

Binaries are served from GitHub raw content (`raw.githubusercontent.com`):
- ✅ **Checksum Verified:** SHA256 validation on every download
- ✅ **Version Locked:** Manifests are version-controlled in the repository
- ⚠️ **Trust Model:** You're trusting this package maintainer + GitHub infrastructure
- 🔒 **HTTPS Only:** All downloads use encrypted connections

**For maximum security:**
```bash
# Option 1: Manual verification
clang-tool-chain-fetch --dry-run  # Shows download URLs
# Verify checksums in downloads-bins/assets/clang/<platform>/<arch>/manifest.json

# Option 2: Offline installation
# Download archive, verify checksum independently, then extract manually
```

### Reporting Security Issues

For security vulnerabilities, please see our [Security Policy](SECURITY.md) for responsible disclosure instructions.

**Do NOT** report security issues in public GitHub issues.

---

## 👨‍💻 Development

### Development Setup

```bash
# Clone repository
git clone https://github.com/zackees/clang-tool-chain.git
cd clang-tool-chain

# Install dependencies (using uv - recommended)
./install

# Or manually:
uv venv --python 3.11
source .venv/bin/activate  # Windows: .venv\Scripts\activate
uv pip install -e ".[dev]"
pre-commit install
```

### Running Tests

```bash
# Run all tests with coverage (parallel execution)
./test

# Or manually with pytest:
uv run pytest                    # Run with coverage reporting
uv run pytest -n auto            # Run in parallel
uv run pytest tests/test_cli.py  # Run specific test file
uv run pytest -m "not slow"      # Skip slow tests

# Run single test
uv run pytest tests/test_cli.py::MainTester::test_imports -v
```

### Code Quality

```bash
# Run all linters and formatters
./lint

# Individual tools:
uv run ruff check --fix src tests  # Lint with auto-fix
uv run black src tests             # Format code
uv run isort --profile black src tests  # Sort imports
uv run pyright src tests           # Type checking
uv run mypy src tests              # Alternative type checking
```

### Pre-commit Hooks

```bash
# Install pre-commit hooks
pre-commit install

# Run all pre-commit checks manually
pre-commit run --all-files

# Update hook versions
pre-commit autoupdate
```

### Building and Publishing

```bash
# Build the package
uv run python -m build

# Check the built package
twine check dist/*

# Upload to PyPI (maintainers only)
./upload_package.sh
```

---

## 🛠️ Maintainer Tools

<details>
<summary><b>Click to expand maintainer documentation</b> (for package maintainers only)</summary>

### Archive Creation Pipeline

The `clang-tool-chain-fetch-archive` command automates the complete packaging process:

```bash
# Create optimized archive for Windows x86_64
clang-tool-chain-fetch-archive --platform win --arch x86_64

# Create archive for Linux x86_64
clang-tool-chain-fetch-archive --platform linux --arch x86_64

# Create archive for macOS ARM64 (Apple Silicon)
clang-tool-chain-fetch-archive --platform darwin --arch arm64

# Use existing extracted binaries (skip download)
clang-tool-chain-fetch-archive \
    --platform win --arch x86_64 \
    --source-dir ./assets/win
```

**What it does:**

1. ✅ Downloads LLVM 21.1.5 from official GitHub releases (~400-900 MB)
2. ✅ Extracts the archive
3. ✅ Strips unnecessary files (docs, examples, static libs)
4. ✅ Deduplicates identical binaries (~571 MB savings via MD5 hash detection)
5. ✅ Creates hard-linked structure (reduces size without data loss)
6. ✅ Compresses with **zstd level 22** (94.3% reduction!)
7. ✅ Generates checksums (SHA256, MD5)
8. ✅ Names archive: `llvm-{version}-{platform}-{arch}.tar.zst`
9. ✅ Places in `downloads-bins/assets/clang/{platform}/{arch}/`
10. ✅ Updates platform manifest with URLs and checksums

**Result:** 51.53 MB archive (from 902 MB original) for Windows x86_64!

### Individual Maintainer Scripts

Available as Python modules in `clang_tool_chain.downloads`:

#### download_binaries.py
Download LLVM releases from GitHub:

```bash
python -m clang_tool_chain.downloads.download_binaries \
    --platform win --arch x86_64 --version 21.1.5

# Download for current platform only
python -m clang_tool_chain.downloads.download_binaries --current-only

# Skip checksum verification (not recommended)
python -m clang_tool_chain.downloads.download_binaries --current-only --no-verify
```

#### strip_binaries.py
Optimize binary size by removing unnecessary files:

```bash
python -m clang_tool_chain.downloads.strip_binaries \
    work/clang+llvm-21.1.5-x86_64-pc-windows-msvc \
    downloads-bins/assets/clang/win/x86_64 \
    --platform win
```

**Removes:**
- Documentation (`share/doc`, `share/man`)
- Headers and examples
- Static libraries (`*.a`, `*.lib`)
- CMake files
- Debug symbols (using `llvm-strip`)

**Keeps:**
- 14 essential binaries
- Runtime libraries (`*.so`, `*.dll`, `*.dylib`)
- License files

**Size reduction:** ~3.5 GB → ~200-400 MB per platform

#### deduplicate_binaries.py
Find duplicate binaries by MD5 hash:

```bash
python -m clang_tool_chain.downloads.deduplicate_binaries \
    work/clang+llvm-21.1.5-x86_64-pc-windows-msvc/bin
```

**Output:**
```
Duplicate groups found: 45
Total duplicates: 158 files
Potential space savings: 571.23 MB

Duplicate group #1 (MD5: a1b2c3d4...):
  - clang.exe (12.5 MB)
  - clang++.exe (12.5 MB)
  - clang-cl.exe (12.5 MB)
```

#### create_hardlink_archive.py
Create hard-linked TAR archives (preserves hard links during extraction):

```bash
python -m clang_tool_chain.downloads.create_hardlink_archive \
    input/win \
    output/llvm-21.1.5-win-x86_64.tar.zst \
    --compression-level 22
```

**Benefits:**
- Preserves hard links (deduplication survives extraction)
- Ultra-high compression (zstd level 22)
- Maintains file permissions and metadata

#### expand_archive.py
Extract `.tar.zst` archives:

```bash
python -m clang_tool_chain.downloads.expand_archive \
    llvm-21.1.5-win-x86_64.tar.zst \
    output/win
```

**Features:**
- Handles zstd compression
- Preserves hard links
- Shows extraction progress
- Validates archive integrity

#### test_compression.py
Compare compression methods and levels:

```bash
python -m clang_tool_chain.downloads.test_compression \
    input/win \
    --methods zstd gzip xz \
    --levels 1 9 22
```

**Output:**
```
Testing compression methods...

zstd level 1:  Size: 156 MB, Time: 2.3s
zstd level 9:  Size: 78 MB,  Time: 8.7s
zstd level 22: Size: 51 MB,  Time: 45.2s ⭐ BEST RATIO

gzip level 9:  Size: 124 MB, Time: 15.6s
xz level 9:    Size: 89 MB,  Time: 67.3s
```

### Compression Statistics

**Windows x86_64 (LLVM 21.1.5):**
- Original: 902 MB
- After stripping: 200 MB
- After deduplication (hard links): 200 MB (same size, but ~571 MB savings on disk)
- After zstd level 22: **51.53 MB** (94.3% reduction from original!)

**Linux x86_64 (LLVM 21.1.5):**
- Original: ~850 MB
- After optimization: **88 MB archive**

**macOS ARM64 (LLVM 19.1.6):**
- Original: ~750 MB
- After optimization: **71 MB archive**

### Updating Manifests

After creating archives, update the manifest files:

1. **Generate SHA256 checksum:**
   ```bash
   sha256sum downloads-bins/assets/clang/win/x86_64/llvm-21.1.5-win-x86_64.tar.zst
   ```

2. **Update platform manifest** (`downloads-bins/assets/clang/win/x86_64/manifest.json`):
   ```json
   {
     "latest": "21.1.5",
     "21.1.5": {
       "href": "https://raw.githubusercontent.com/zackees/clang-tool-chain-bins/main/assets/clang/win/x86_64/llvm-21.1.5-win-x86_64.tar.zst",
       "sha256": "3c21e45edeee591fe8ead5427d25b62ddb26c409575b41db03d6777c77bba44f"
     }
   }
   ```

3. **Commit and push to downloads-bins submodule:**
   ```bash
   cd downloads-bins
   git add assets/clang/
   git commit -m "chore: add LLVM 21.1.5 for Windows x86_64"
   git push
   cd ..
   git add downloads-bins
   git commit -m "chore: update submodule to latest binaries"
   git push
   ```

</details>

---

## 📄 License

This package is distributed under the **Apache License 2.0**. See [LICENSE](LICENSE) for details.

The bundled LLVM/Clang binaries are licensed under the **Apache License 2.0 with LLVM Exception**. See [LLVM License](https://llvm.org/LICENSE.txt) for details.

---

## 🙏 Acknowledgments

- **[LLVM Project](https://llvm.org/)** - For the excellent Clang/LLVM toolchain
- **[GitHub LLVM Releases](https://github.com/llvm/llvm-project/releases)** - For providing pre-built binaries
- **[Zstandard (zstd)](https://facebook.github.io/zstd/)** - For incredible compression performance
- **[pyzstd](https://github.com/animalize/pyzstd)** - For Python zstd bindings
- **[fasteners](https://github.com/harlowja/fasteners)** - For cross-platform file locking

---

## 📊 Version History

### 1.0.1 (2025-11-09)
- ✅ Automatic macOS SDK detection via xcrun
- ✅ Improved error messages and troubleshooting
- ✅ Enhanced documentation with platform-specific guidance

### 1.0.0 (2025-11-07) - Initial Release
- ✅ Core wrapper infrastructure for 22 wrapper commands
- ✅ Automatic download and installation system
- ✅ Manifest-based distribution with SHA256 verification
- ✅ Binary optimization pipeline (stripping, deduplication, compression)
- ✅ CLI management commands (`info`, `version`, `list-tools`, `path`)
- ✅ Cross-platform support (Windows x64, macOS x64/ARM64, Linux x64/ARM64)
- ✅ File locking for concurrent-safe downloads
- ✅ Ultra-compressed archives (zstd level 22, 94.3% size reduction)
- ✅ LLVM 21.1.5 for Windows/Linux, 19.1.6 for macOS
- ✅ Comprehensive test suite with CI/CD integration

---

## 🚀 Getting Started

Ready to compile? Install and run:

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

That's all you need! The toolchain downloads automatically. Happy compiling! 🎉

---

**Repository:** [github.com/zackees/clang-tool-chain](https://github.com/zackees/clang-tool-chain)
**Issues:** [github.com/zackees/clang-tool-chain/issues](https://github.com/zackees/clang-tool-chain/issues)
**PyPI:** [pypi.org/project/clang-tool-chain/](https://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
