Clang-based cross platform build system written in Python



  • Building as much as possible from source eases dependency management and
    ensures stability and reproducibility
  • Meta build systems are inherently the wrong way to go, either the build
    system or the compiler should be platform-agnostic (ideally both).
  • Trying to cover all use-cases is the wrong way to go - there is no need to
    let people do it the wrong way
  • CMake is cumbersome, unnecessarily generic and verbose and people should not
    need a programming/scripting language whose only purpose is to build C++
  • With Clang, finally a properly cross-platform compiler exists


  • One compiler (Clang), one build system (written in Python)
  • Simple projects should be simple to build
  • Build process for reasonable project structures should still be easy
  • Adding third-party dependencies should be manageable

What it's not designed to do:

  • Build anything aside from C language dialects
  • Be able to adapt to any project structure in the world - certain standards are encouraged
  • Work smoothly with or locate pre-built libraries and libraries installed by system package managers


In order to run clang-build, you only need Clang and Python3.
Install via pip install clang-build (add the --user flag if you don't have admin rights).

Running clang-build will try to build the current directory.
The command-line options include

  • -d path/to/dir to build a different directory
  • -p to show a progress bar
  • -V to print some additional info
  • --debug to print the called clang commands

The given directory will be searched for a clang-build.toml file, which you can use to configure
your build targets, if necessary. However, if you only want to build an executable, you will
likely not even need a build file.

clang-build tries to use sane defaults, designed to make most projects very easy to configure
and even complex projects far easier than with common build or meta-build systems.

Real-World Examples

Examples of real-world used and tested projects, which can be easily be integrated
into your project using clang-build:

General Ideas

Note: not all of these are implemented, yet.

What should be trivial

This would be things that require only the invocation of clang-build
and no build file.

  • build any hello world program or other MWE, given a reasonable folder
    structure (i.e anything with a main and without non-std dependencies)
  • include anything that can be found by sane default search
  • using command line arguments:
    • specify root/source and build directories
    • set build type (last used should be cached/remembered)
    • set verbosity

Sane defaults and default behaviour:

  • platform-independence
  • build into a "build/" directory, not into toplevel
  • for multiple targets build each into its own "build/targetname"
  • default search paths for different platforms, including also e.g.
    "./include", "./lib", "./build/lib", "/usr/local/...", ...

What should be easy

This would be things that only require a minimal TOML project file

  • add dependency / external project from source folder or remote (e.g.
  • header-only should be trivial
  • for a library with a good folder structure, it should be easy to
    write a build config
  • create a library from one subfolder, an executable from another and
    link them
  • setting target-specific (note: defaults should be sane!)
    • source file extensions
    • source directories
    • compile and link flags
    • optional version
    • dependencies (which may include non-targets, e.g. configuration
    • properties (required c++ version, definitions/#defines, ...)
  • access to flag "lists" such as flags for
    • coverage
    • cuda
    • openmp
  • set target-specific flags, include folders, etc. which should not be
    propagated to dependency parents as "private"

What should be possible

Steps that would involve more effort from the user, including possibly
some python code

  • a Target configuration step before building (e.g. for more involved
    version numbering)
  • through the configuration step, inclusion of e.g. CMake-project
    should be possible
  • packaging: any target may be packaged, meaning it's dependencies are
    handled and if built, binaries may be bundled
  • external package dependencies
  • binaries on a server
  • source on a server (fallback from binaries)
  • binaries on disk, try to determine version from path and file names
  • source on disk, try to determine version from path and file names

Project File By Example

A single target


  • by default, the root and <targetname> folders, as well as "include" and "src" subdirectories
    will be searched for ".hpp", ".hxx", ".h" and ".cpp", ".cxx" and ".c" files
  • a target without target_type, but with source files will be an executable
  • output_name should not contain pre- or suffixes such as lib, .exe, .so, as they are added automatically
  • if we don't care about the output name, in this case we could skip the project file entirely
# Top-level brackets indicate a target
output_name = "runHello"

Two targets with linking

# Build a library
target_type = "shared library"

# Build an executable and link the library
output_name = "runExe"
target_type = "executable"
dependencies = ["mylib"]

Adding external dependencies


  • external targets will be copied/downloaded into "build/targetname/external_sources"
  • you can specify a subdirectory, if the thirdparty code has an unusual structure
  • further granularity is given by include_directories and sources
  • sources, headers_exclude and sources_exclude expect a list of globbing patterns or files (not folders!)
url = ""
version = 1.1 # will try to `git checkout 1.1`
directory = "sources"           # will point to "build/mylib/external_sources/sources"
include_directories = ["mylib/include"] # will point to "build/mylib/external_sources/sources/mylib/include"
sources = ["mylib/src/*"]     # will list everything inside "build/mylib/external_sources/sources/mylib/src"
# Maybe we need to deactivate annoying warnings coming from the library
compile = ["-Wno-deprecated-declarations", "-Wno-self-assign"]

# Build an executable and link the library
dependencies = ["mylib"]