Clang Build Extension

Overview

clang-build-ext is a setuptools plugin that builds Python C/C++ extensions using the LLVM/Clang compiler toolchain instead of the system default compiler. Either a system-installed LLVM/Clang or the karellen-llvm-clang package can be used.

The plugin provides drop-in replacements for setuptools' build_ext and build_clib commands, along with features such as glob pattern expansion in source lists, Drakon IR bytecode embedding, and thin static library support.

Basic Usage

Add clang-build-ext to your build dependencies in pyproject.toml:

[build-system]
requires = ["setuptools", "clang-build-ext"]
build-backend = "setuptools.build_meta"

Register the custom build commands in setup.py:

from setuptools import setup, Extension
from karellen.clang_build_ext import ClangBuildExt, ClangBuildClib

setup(
    ...,
    ext_modules=[Extension("myext", ["src/*.c"])],
    cmdclass={
        "build_ext": ClangBuildExt,
        "build_clib": ClangBuildClib,
    },
)

Then build with:

python -m build

LLVM Toolchain

The compiler uses the full LLVM toolchain:

Features

Glob Pattern Expansion

Source file lists in both extensions and libraries support shell glob patterns. Patterns are expanded at build time, so you don't need to enumerate every source file in setup.py.

* matches within a single directory, while ** recurses to any depth. Given this tree:

src/module/
├── module.c
├── util/
│   └── util.c
└── codec/
    └── formats/
        └── png.c

Use * when a flat directory is exactly what you want — it will not silently pick up sources added in a subdirectory later:

setup(
    ...,
    ext_modules=[
        Extension("myext", ["src/module/*.c"]),
    ],
    libraries=[
        ("mylib", {"sources": ["src/lib/*.c"]}),
    ],
    cmdclass={
        "build_ext": ClangBuildExt,
        "build_clib": ClangBuildClib,
    },
)

Use ** to pick up an entire source tree regardless of how deeply it is nested:

setup(
    ...,
    ext_modules=[
        Extension("myext", ["src/module/**/*.c"]),
    ],
    libraries=[
        ("mylib", {"sources": ["src/lib/**/*.c"]}),
    ],
    cmdclass={
        "build_ext": ClangBuildExt,
        "build_clib": ClangBuildClib,
    },
)

**/*.c already covers the top level, so pairing it with *.c is unnecessary. Should you list overlapping patterns anyway, each source is compiled once: duplicates are removed, keeping the order in which they were first matched.

Only the sources entry is glob-expanded. Every other build_info key of a build_clib library (macros, include_dirs, cflags, obj_deps) is passed through to setuptools unchanged.

C++ Extensions

Sources that setuptools detects as C++ (.cc, .cpp, .cxx) are compiled with the clang++ driver, and any extension containing one is linked with it too, so no extra configuration is required to mix C and C++ in one project:

setup(
    ...,
    ext_modules=[
        Extension("myext", ["src/module/*.cpp"],
                  include_dirs=["include"],
                  extra_compile_args=["-std=c++20"]),
    ],
    libraries=[
        ("mylib", {"sources": ["src/lib/*.cpp"],
                   "include_dirs": ["include"],
                   "macros": [("MYLIB_BUILD", "1")],
                   "cflags": ["-std=c++20"]}),
    ],
    cmdclass={
        "build_ext": ClangBuildExt,
        "build_clib": ClangBuildClib,
    },
)

Note that clang++ links against libc++ rather than libstdc++. When the toolchain comes from karellen-llvm-clang, libc++.so.1 lives in the package's library directory and is recorded as a plain DT_NEEDED, so the resulting extension needs that directory on the loader path (LD_LIBRARY_PATH, an ld.so.conf entry, or an explicit -Wl,-rpath in extra_link_args) at import time.

Drakon Enhancements

Drakon mode embeds LLVM intermediate representation (IR) bytecode into compiled binaries as custom ELF sections. This enables post-compilation IR analysis and transformation of the final binary.

When enabled, the build:

1. Compiles with --save-temps=obj -fno-discard-value-names to produce .bc (bitcode) files alongside object files
2. Includes .bc files in static libraries created via build_clib
3. After linking, extracts .bc files from all linked objects and static libraries and embeds them into the output binary as .drakon.<name> ELF sections (marked noload,readonly)

Enable via environment variable or setup.cfg:

DRAKON=1 python -m build

# setup.cfg
[build_ext]
drakon = 1

Thin Static Libraries

Thin static libraries store references to object files rather than copies, reducing build artifact size during development.

Enable via environment variable or setup.cfg:

THIN=1 python -m build

# setup.cfg
[build_ext]
thin = 1

Both options can be combined:

DRAKON=1 THIN=1 python -m build

# setup.cfg
[build_ext]
drakon = 1
thin = 1

The build_clib command inherits drakon and thin settings from build_ext automatically.

Setuptools Compatibility

clang-build-ext supports setuptools 68 and newer, and is tested against the versions on either side of each API change that affects it: