Welcome to Clang Build’s documentation!¶

Clang Build is a C++ build tool written in Python using the clang compiler. The code is open source and available on GitHub. Clang Build is a system that tries its best to make the compile configuration process less of a pain. The design goals to achive this were:

Cross platform
- One compiler (clang)
- One build system (written in Python)
Always hide as much complexity as possible
- Simple projects should be simple
- Build process for reasonable project structures should still be easy

If you want to know how you can use Clang Build to compile your project, you can have a look at the user’s guide which demonstrates the features of Clang Build in a series of examples. If you want to have a look at how the python code of Clang Build is structured you can have a look at the source code on GitHub or the code documentation in the second section of this documentation.

User’s Guide¶

The User’s Guide should provide you with all the information necessary to build your C++ project with clang-build.

First steps¶

Let’s start with a very simple project. You only have one source file in your project folder and you want to compile it into an executable.

The minimum working example¶

my_project
└── my_app.cpp

All you have to do, to compile this app is go into your project folder and call

clang-build

Your project quickly grows and you decide to put all your headers into an include folder and all your source files into a src folder.

my_project
├── include
|   ├── cool_features.hpp
|   └── math_lib.hpp
└── src
    ├── cool_features.cpp
    └── my_app.cpp

To compile your project, you just go into your project folder and call:

clang-build

The include folder will automatically be added as an include folder to clang. So all files in the include folder or subfolders of the include folder can be included in the source files in the src folder as you would normally do:

// my_app.cpp
#include "math_lib.hpp"
// ...

At the same time, all source files in the src folder and subfolders of the src folder are automatically detected, compiled and linked into one executable.

Switching between debug and release¶

By default Clang Build compiles in Release mode meaning optimizations are turned on. If you want to debug an application, you need to pass extra flags to the compiler. Clang Build does this automatically if you pass it the debug flag:

clang-build --build-type debug

or

clang-build -b debug

Customisations¶

Let’s have a look at some of the ways you can configure your project, if it does not have a default setup such as in the example above.

Custom target name¶

First you might want to customize the name of the executable of your project. To do this you can add a clang-build.toml file to your project.

my_project
├── include
|   ├── cool_features.hpp
|   └── math_lib.hpp
├── src
|   ├── cool_features.cpp
|   └── my_app.cpp
└── clang-build.toml

The toml file looks as follows:

[myexe]
    output_name = "MyNextApp-v1.0"

Here the square brackets define a target. Since only the output_name is given, Clang Build continues to assume that a default project is inside this folder, with the default folder names. This is of course the case in the example above sou you can simply call:

clang-build

and your project get’s compiled.

Custom folder names¶

While it is common to have a folder structure like the one above, maybe for some reason the folders are called differently in your project. While automatic detection now does not work, you can just specify the folder names in your toml-file.

my_project
├── header_files
|   ├── cool_features.hpp
|   └── math_lib.hpp
├── external_header_files
|   ├── collaborator1_interface.hpp
|   └── collaborator2_interface.hpp
├── sauce
|   ├── cool_features.cpp
|   └── my_app.cpp
└── clang-build.toml

The toml file now looks as follows:

[myexe]
    output_name = "MyNextApp-v1.0"
    include_directories = ["header_files", "external_header_files"]
    sources = ["sauce/*.cpp"]

Compiling a library¶

If you want to compile a library instead of an executable, you can simply change the target type in the toml file:

[mylib]
    output_name = "MyNextLibrary-v1.0"
    target_type = "shared library"

[mylib-static]
    output_name = "MyNextLibrary-static-v1.0"
    target_type = "static library"

Multiple targets¶

For a lot of projects you will have more than one target. Maybe a main application, some libraries and some test executables. Let’s have a look at different scenarios of multiple targets in a single project.

Multiple self-developed targets¶

In this first example we have a library and an executable both in the same project. We want to link the library and the exectuable. This is our folder structure.

my_project
├── shared_headers
|   └── header1.hpp
├── my_executable
|   ├── include
|   |   ├── header1.hpp
|   |   └── header2.hpp
|   └── src
|       ├── src1.cpp
|       └── src2.hpp
├── my_lib
|   ├── include
|   |   └── header3.hpp
|   └── src
|       └── src3.hpp
└── clang-build.toml

The following toml file will create and link the targets:

[additional_includes]
    directory = "shared_headers"
    target_type = "header only"

[my_library]
    directory = "my_lib"
    target_type = "shared library"
    dependencies = ["shared_headers"]

[app]
    directory    = "my_executable"
    dependencies = ["my_lib", "shared_headers"]

As you can see we defined the shared headers as another target. Because there is no “additional_includes” in Clang Build currently, this has the advantage, that we do not have to list the default folders as include folders, too.

Note

Header files of dependencies are automatically also available for include, no extra configuration required!

External GitHub target¶

Maybe you have a dependency on an external library on GitHub like Eigen. In this case we can use Clang Build’s feature to automatically download the library for you. If this is your folder structure:

my_project
├── include
|   ├── cool_features.hpp
|   └── math_lib.hpp
├── src
|   ├── cool_features.cpp
|   └── my_app.cpp
└── clang-build.toml

and this is your toml file:

[myexe]
    dependencies = ["Eigen"]

[Eigen]
    target_type = "header only"
    url         = "https://gitlab.com/libeigen/eigen.git"
[Eigen.flags]
    compile  = ["-Wno-deprecated-declarations"]
    compileRelease = ["-DEIGEN_NO_DEBUG"]

Then you already have your project support Eigen. As soon as you run clang-build, it will download (or use the cached version if you rebuild) Eigen and make it available for including its headers.

Multiple projects¶

In order to manage larger project structures and nested dependencies, subprojects can be used.

Requirements¶

Project Naming

When one or more subprojects are specified, the root project has to be named, as targets are then grouped and identified by project.
If a subproject is not given a name, it is required to be external and that the corresponding config file specifies a name

Build Paths

If there is only a single project, the build paths will be the same as if only targets had been specified. Otherwise, every project will get its own folder build/projectname and targets will get their own folders under this folder.

Example configuration file¶

A simple example of a main project consuming a second one, which is located in a subdirectory:

name = "mainproject"

[myexe]
output_name  = "runLib"
dependencies = ["mysubproject.mylib"]
directory    = "myexe"


[[subproject]]
name = "mysubproject"
directory = "mylib"

Multiple subprojects in the same file¶

A second simple example:

name = "mainproject"

[myexe]
output_name  = "runLib"
dependencies = ["mysubproject.mylib"]
directory    = "myexe"


[[subproject]]
name = "mysubproject"

[subproject.mylib]
target_type  = "static library"

Inheritance¶

General¶

Targets can inherit include directories and flags from their direct, as well as transitive, dependencies. The classification of dependencies as “private” or “public” determines their visibility to transitively dependent targets. Private dependencies are intended as internal to a target and public dependencies are part of a targets interface.

Which include directories and flags are visible to dependent targets is in turn determined by an additional classification into “private”/”public” and “private”/ “public”/”interface”, respectively.

As one should carefully choose, which of these to expose to ones users, “private” is the default and “public” and “interface” are made explicit in the corresponding keywords. Note, the distinction from “public” becomes important when your dependency-graph grows to more than two layers, as you want to be able to tell what your top-level targets can include and what gets linked. Additionally, if everything was public, no two targets in the entire dependency- graph would be allowed to depend on different versions of the same library.

The specific inheritance rules are determined by the combination of the classification of dependenies and the classification of include directories and flags. They are described in detail below.

Include directories¶

`include_directories`

A list of private include directories, i.e. accessible only to the target itself.

Exceptions: for header-only libraries, they are treated as public.

Default, if none are specified: the target directory and “include”, if they exist.

`public_include_directories`

A list of public include directories, which are accessible to the target itself and any dependent target.

A target forwards its public dependencies’ public include directories, i.e. it adds them to its own public_include_directories. The public include directories of a targets private dependencies are added to its (private) include_directories.

Default, if none are specified: “include”, if it exists.

Note that this mechanism allows public_include_directories to be forwarded far up the dependency graph. You may want to keep them minimal and follow best practices for your folder structure, in order to avoid confusion in larger projects.

Example:

[mylib]
    include_directories        = ["src/mylib/include", "src/mylib/detail/include"]
    public_include_directories = ["src/mylib/include"]

Flags¶

The following sections of a target configuration can each contain compile and link lists of flags.

`flags`

Private flags which are only applied to the target itself.

Exceptions: for header-only libraries, they are treated as public.

`public_flags`

Public flags are applied to the target itself, as well as any dependent targets.

A target forwards its public dependencies’ public flags, i.e. it adds them to its own public_flags. The public flags of a targets private dependencies are added to its (private) flags.

Note that this mechanism allows public_flags to be forwarded far up the dependency graph, so it is recommended to be mindful of the flags added here. For example, don’t put force your users to adopt your warning settings by putting flags like -Werror here.

`interface_flags`

Interface flags are not applied to the target itself, but instead to the next transitively dependent shared library or executable.

Executables and shared libraries will apply the interface flags of their private and public dependencies to themselves (i.e. add them to their own private flags). They will not be forwared (added to their own interface_flags or public_flags).

Header-only and static libraries will not apply their private or public dependencies’ interface flags to themselves, but will forward them (i.e. they will add them to their own interface_flags).

An example use-case is a static library A, which depends on a dynamic library B. As B cannot be linked into A, it needs to be linked to the next shared library or executable which depends directly or transitively on A.

Example:

[mylib]
    target_type     = "static library"
    [mylib.flags]
        compile = ["-Wno-unused-parameter"]
    [mylib.public_flags]
        compile = ["-DMYLIB_NO_EXCEPTIONS"]
    [mylib.interface_flags]
        link = ["-lpthread"]

Dependencies¶

Example:

In the following example, “src/C/include” will be available to app as it is forwarded by A, while “src/B/include” will not be available because B is a private dependency of A.

[app]
    dependencies = ["A"]

[A]
    target_type         = "static library"
    dependencies        = ["B"]
    public_dependencies = ["C"]

[B]
    target_type                = "shared library"
    public_include_directories = ["src/B/include"]

[C]
    target_type                = "shared library"
    public_include_directories = ["src/C/include"]

Platform dependence¶

Per-Platform Target Configuration¶

The following lists and sections of the target configuration can be specified individually per platform:

include_directories and public_include_directories
sources
flags

Available platforms are osx, linux and windows. The corresponding platform-specific lists are merged with the general lists, meaning that they are not overridden.

Example¶

[mylib]
    target_type = "static library"
    public_include_directories = ["include"]
    sources = ["src/common.c"]

    [mylib.public_flags]
        compile = ["-DMYLIB_VERSION_MAJOR=2", "-DMYLIB_VERSION_MINOR=1", "-DMYLIB_VERSION_PATCH=2"]

    [mylib.osx]
        include_directories = ["include/osx"]
        sources = ["src/osx/cocoa.m", "src/osx/handle.cpp"]

        [mylib.osx.flags]
            compile = ["-DMYLIB_OSX"]
        [mylib.osx.interface_flags]
            link = ["-framework", "Cocoa"]

    [mylib.windows]
        include_directories = ["include/win"]
        sources = ["src/win/win32.cpp", "src/win/handle.cpp"]

        [mylib.windows.flags]
            compile = ["-DMYLIB_WINDOWS", "-D_CRT_SECURE_NO_WARNINGS"]
            link = ["-luser32.lib"]

Bundling¶

A common task for software developers is to make their projects more accessible to non-developers, for example by creating binary releases.

clang-build carries the following opinion: non-system packages should work on their own, i.e. they should bring their own dependencies with them. This means that a redistributable bundle can simply be a zip archive.

Build-folder binary bundle¶

You can use the –bundle flag to tell clang-build to gather all dependencies of executable and shared library targets next to them into their respective build folders. They should then be usable on their own, i.e. without manually gathering additional binaries.

For example, the binary build folders on Linux may then look as follows:

build
├── myexe/default/bin
|   ├── myexe
|   ├── libA.so
|   └── libB.so
├── libA/default/bin
|   ├── libA.so
|   └── libB.so
└── libB/default/bin
    └── libB.so

On Linux and OSX, the -rpath flag is automatically used to cause those targets to search for dependencies in their own directory.

Regardless of whether you use Linux, OSX or Windows, you can then run your executables without having to make sure that the right dependencies are found.

Redistributable bundle¶

This feature is still experimental and not fully implemented

A redistributable bundle is what someone would need to run an executable or use a library. A main purpose is to create a bundle which will make it easy for someone to create e.g. a system package or an installer out of it.

Each target gathers from itself and its dependencies, depending on its type:

For an executable
- the executable
- shared library dependencies
- runtime files (config, resource, shaders, …)
For a shared library
- the shared library
- shared library dependencies
- own header files and those of dependencies
- usage instructions (compiler/linker flags)
For a static library
- the static library
- shared library dependencies
- own header files and those of dependencies
- usage instructions (compiler/linker flags)
For a header only library
- own header files and those of dependencies
- usage instructions (compiler/linker flags)

On OSX, this will be a .app folder. On Linux and Windows, this will be a regular folder with a structure

build/myexe/default/redistributable
├── README.md
├── bin
|   ├── myexe
|   ├── libA.so
|   └── libB.so
└── res
    ├── config.toml
    └── img
        ├── logo.icns
        └── background.png

build/libA/default/redistributable
├── instructions.toml
├── README.md
├── bin
|   ├── libA.so
|   └── libB.so
└── include
    ├── libA
    |   └── libA.hpp
    └── libB
        └── libB.hpp

Adding projects with custom behaviour¶

Instead of configuring a project using a “clang-build.toml”, you can also use a “clang-build.py” script. This allows you, for example, to generate a version-header based on git tags or to (de-)activate features or targets depending on environment variables.

Script requirements¶

The “clang-build.py” script, is required to define the following function:

import clang_build

def get_project(directory, environment, parent=None) -> clang_build.project.Project:
    project = clang_build.project.Project("projectname", {}, directory, environment, parent=parent)
    #...
    return project

Creating a project¶

You can default-initialize a project without targets or let clang-build create the project for you, from a folder or from a configuration dict.

from clang_build.project import Project

def get_project(directory, environment, parent=None) -> Project:
    # Empty project:
    project = Project("projectname", {}, directory, environment, parent=parent)
    # Use defaults to initialize from a folder:
    project = Project.from_directory(directory, environment, parent=parent)
    # Use a dictionary:
    project = Project.from_config({}, directory, environment, parent=parent)

Creating targets¶

A target always belongs to a project, meaning you need to create a project first. Then,

def get_project(directory, environment, parent=None) -> clang_build.project.Project:
    project = #...
    target = clang_build.target.TargetDescription("targetname", {}, project)
    project.add_targets([target])
    return project

Manipulating sources¶

Both projects and targets may fetch external sources, if a url is provided. The source fetching process can be customised by overriding their get_sources functions.

class CustomSources(clang_build.target.TargetDescription):
    def get_sources(self):
        # The base class `get_sources` checks if a `url` was specified in
        # the config, in which case it will download the sources
        super().get_sources()
        # Write some sources
        # ...

Note, when generating sources you should use the properties of TargetDescription to place them in the right folder.

Defaults¶

General¶

By default:

all relative paths in a toml are interpreted as relative to that toml file
if only one target is built from source, it is built into build/<build_type>
if more than one target is built from source, they are built into build/<target_name>/<build_type>
an external target’s sources will be copied/downloaded into build/<target_name>/external_sources
targets for which sources are found will be built as executable
targets for which no sources are found will be header-only

Search Paths¶

Include directories

Default system directories for #include-searches are given by Clang.

clang-build’s include directories will be added to the search paths and will be searched for header files for a target. In your project file, you can add an include_directories array to specify a target’s header directories, where by default clang-build will try the target’s root directory and an “include” subdirectory.

Source directories

clang-build’s source directories will be searched for source files for a target. In your project file, you can add a sources array of patterns to specify a target’s sources, where by default clang-build will try the target’s root directory and a “src” subdirectory.

Build Type and Flags¶

For “.cpp” files, the newest available C++ standard will be used by automatically adding e.g. -std=c++17.

The default build type contains the flags, which are used in all build configurations, i.e. the minimum set of flags which clang-build enforces.

default:	contains -Wall -Wextra -Wpedantic -Werror
release:	adds -O3 -DNDEBUG
relwithdebinfo:	adds -O3 -g3 -DNDEBUG
debug:	adds -O0 -g3 -DDEBUG
coverage:	adds debug flags and –coverage -fno-inline

By activating all warnings and turning them into errors, the default flags ensure that unrecommended code needs to be explicitly allowed by the author.

Build Directories¶

build
├── myproject
|   ├── targetname
|   |   ├── external_sources
|   |   ├── release
|   |   |   ├── obj
|   |   |   ├── dep
|   |   |   ├── bin
|   |   |   ├── lib
|   |   |   └── include
|   |   ├── debug
|   |   | └── ...
|   |   ├── default
|   |   | └── ...
|   |   └── ...
|   └── othertargetname
|       └── ...
└── mysubproject
    └── ...

Note:

If there is only one project, the target build folders will be placed directly into “build”. Analogously, if there is only one target, the “release”, “debug”, etc. directories will be placed directly into “build”.

Toolchains¶

clang-build also allows you to use a different toolchain than llvm-clang. For this, you need to create a Python-file which you pass to clang-build as clang-build … –toolchain=/path/to/your_toolchain.py and which defines the following function

import clang_build

def get_toolchain(environment) -> clang_build.toolchain.Toolchain:
    toolchain = clang_build.toolchain.Toolchain()
    #...
    return toolchain

The important part is the signature. Instead of using the default toolchain provided by clang-build, you should derive from it or define a new one from scratch.

The toolchain needs to provide

the build platform (on which clang-build is being run), e.g.
- windows
- osx
- linux
the host platform (on which the build results may be run), e.g.
- windows
- osx
- linux
- web / browser
the host architecture (on which to run the built binaries), e.g.
- x86
- GPU
- web / wasm
a list of supported C-dialect languages, e.g.
- C
- C++
- CUDA-C
- CUDA-C++
- OpenCL
- Objective-C
- Objective-C++
default compile and link flags for all target types (executable, …) for all build types (debug, …) for the available languages for the given combination of build and host platform

Real world examples¶

To showcase how clang-build can be used to build real-world projects, we provide examples of some widely known ones.

GLFW¶

This is a configuration to build GLFW with the OpenGL backend. It has not yet been tested on Linux and building the Vulkan backend has not yet been attempted.

name = "glfw"
url = "https://github.com/glfw/glfw"

[glfw]
    target_type = "static library"
    include_directories = ["include", "src", "deps"]
    sources = ["src/context.c", "src/init.c", "src/input.c", "src/monitor.c", "src/vulkan.c", "src/window.c",
                "deps/glad.c", "deps/getopt.c", "deps/tinycthread.c"]

    [glfw.osx]
        sources = ["src/cocoa_init.m", "src/cocoa_joystick.m", "src/cocoa_monitor.m", "src/cocoa_window.m",
                    "src/cocoa_time.c", "src/posix_thread.c", "src/nsgl_context.m", "src/egl_context.c",
                    "src/osmesa_context.c"]
        [glfw.osx.flags]
            compile = ["-D_GLFW_COCOA",
                        "-Wdeclaration-after-statement", "-Wno-extra-semi",
                        "-Wno-sign-compare", "-Wno-unused-parameter", "-Wno-missing-field-initializers",
                        "-Wno-pedantic"]
        [glfw.osx.interface_flags]
            link = ["-framework", "Cocoa",
                    "-framework", "IOKit",
                    "-framework", "CoreFoundation",
                    "-framework", "CoreVideo"]

    [glfw.windows]
        sources = ["src/win32_init.c", "src/win32_joystick.c", "src/win32_monitor.c", "src/win32_time.c", "src/win32_thread.c",
                    "src/win32_window.c", "src/wgl_context.c", "src/egl_context.c", "src/osmesa_context.c"]
        [glfw.windows.flags]
            compile = ["-D_GLFW_WIN32", "-D_CRT_SECURE_NO_WARNINGS",
                    "-Wno-unused-parameter", "-Wno-missing-field-initializers", "-Wno-pedantic"]
        [glfw.windows.interface_flags]
            link = ["-luser32.lib", "-lshell32.lib", "-lgdi32.lib"]

    [glfw.tests]
        single_executable = false
        sources_exclude = ["vulkan.c", "windows.c", "glfwinfo.c", "triangle-vulkan.c"]
        dependencies = ["glad", "tinycthread"]
        [glfw.tests.flags]
            compile = ["-Wno-unused-parameter", "-Wno-sign-compare", "-Wno-missing-field-initializers"]

    [glfw.examples]
        dependencies = ["glad"]
        [glfw.examples.flags]
            compile = ["-Wno-unused-parameter"]
        [glfw.examples.windows.flags]
            compile = ["-Wno-deprecated-declarations"]

[glad]
    target_type = "static library"
    public_include_directories = ["deps"]
    sources = ["deps/glad_gl.c"]
    [glad.tests]
        sources_exclude = ["*"]
    [glad.examples]
        sources_exclude = ["*"]

[getopt]
    target_type = "static library"
    public_include_directories = ["deps"]
    sources = ["deps/getopt.c"]
    [getopt.tests]
        sources_exclude = ["*"]
    [getopt.examples]
        sources_exclude = ["*"]

[tinycthread]
    target_type = "static library"
    public_include_directories = ["deps"]
    sources = ["deps/tinycthread.c"]
    [tinycthread.flags]
        compile = ["-Wno-unused-parameter"]
    [tinycthread.windows.flags]
        compile = ["-Wno-deprecated-declarations"]
    [tinycthread.tests]
        sources_exclude = ["*"]
    [tinycthread.examples]
        sources_exclude = ["*"]

lz4¶

The lz4 library, for now without examples or tests.

[lz4]
    url = "https://github.com/lz4/lz4"
    directory = "lib"
    target_type = "shared library"

codeplea/genann¶

url = "git@github.com:codeplea/genann.git"
name = "genann"

[genann]
    target_type = "static library"
    sources = ["genann.c.c"]

[example1]
    sources = ["example1.c"]
    dependencies = ["genann"]

[example2]
    sources = ["example2.c"]
    dependencies = ["genann"]

[example3]
    sources = ["example3.c"]
    dependencies = ["genann"]

[example4]
    sources = ["example4.c"]
    dependencies = ["genann"]

[test]
    sources = ["test.c"]
    dependencies = ["genann"]

nikoreun/tinygrad¶

name = "tinygrad"
url = "git@github.com:nikoreun/tinygrad.git"

[tinygrad]
    target_type = "static library"
    public_dependencies = ["Eigen"]

[example-autoencoder]
    sources = ["examples/test_autoencoder.cpp"]
    dependencies = ["tinygrad"]

[example-logistic-regression]
    sources = ["examples/test_logistic_regression.cpp"]
    dependencies = ["tinygrad"]

[example-neural-network]
    sources = ["examples/test_neural_network.cpp"]
    dependencies = ["tinygrad"]

[Eigen]
    url = "https://gitlab.com/libeigen/eigen.git"
    target_type = "header only"
    [Eigen.flags]
        compile = ["-DEIGEN_HAS_STD_RESULT_OF=0", "-Wno-deprecated-declarations", "-Wno-shadow"]
        compile_release = ["-DEIGEN_NO_DEBUG"]

boost/filesystem¶

This example contains what you need in order to build boost/filesystem, but for now without examples or tests. It requires a few other boost-libraries, most of which are header-only.

name = "boost"

[filesystem]
    target_type = "static library"
    url = "https://github.com/boostorg/filesystem"
    version = "boost-1.65.0"
    dependencies = ["detail"]
    public_dependencies = ["assert", "config", "core", "io", "iterator", "functional", "mpl", "predef", "range", "smart_ptr", "static_assert", "system", "throw_exception", "type_traits"]
    [filesystem.flags]
        compile = ["-Wno-parentheses-equality", "-Wno-unused-parameter", "-Wno-nested-anon-types", "-Wno-vla-extension", "-Wno-pedantic"]

[system]
    target_type = "static library"
    url = "https://github.com/boostorg/system"
    version = "boost-1.65.0"
    dependencies = ["core", "winapi", "config", "predef", "assert"]
    [system.public_flags]
        compile = ['-DBOOST_NO_CXX11_HDR_SYSTEM_ERROR', '-Wno-deprecated-declarations', '-Wno-language-extension-token']

[winapi]
    url = "https://github.com/boostorg/winapi"
    version = "boost-1.65.0"

[config]
    url = "https://github.com/boostorg/config"
    version = "boost-1.65.0"

[core]
    url = "https://github.com/boostorg/core"
    version = "boost-1.65.0"

[smart_ptr]
    url = "https://github.com/boostorg/smart_ptr"
    version = "boost-1.65.0"

[preprocessor]
    url = "https://github.com/boostorg/preprocessor"
    version = "boost-1.65.0"

[mpl]
    url = "https://github.com/boostorg/mpl"
    version = "boost-1.65.0"
    dependencies = ["preprocessor"]

[io]
    url = "https://github.com/boostorg/io"
    version = "boost-1.65.0"

[detail]
    url = "https://github.com/boostorg/detail"
    version = "boost-1.65.0"

[functional]
    url = "https://github.com/boostorg/functional"
    version = "boost-1.65.0"

[throw_exception]
    url = "https://github.com/boostorg/throw_exception"
    version = "boost-1.65.0"

[iterator]
    url = "https://github.com/boostorg/iterator"
    version = "boost-1.65.0"
    dependencies = ["detail"]

[predef]
    url = "https://github.com/boostorg/predef"
    version = "boost-1.65.0"

[range]
    url = "https://github.com/boostorg/range"
    version = "boost-1.65.0"

[assert]
    url = "https://github.com/boostorg/assert"
    version = "boost-1.65.0"

[static_assert] # has sources which should not be included
    target_type = "header only"
    url = "https://github.com/boostorg/static_assert"
    version = "boost-1.65.0"

[utility] # has sources which should not be included
    target_type = "header only"
    url = "https://github.com/boostorg/utility"
    version = "boost-1.65.0"

[type_traits]
    url = "https://github.com/boostorg/type_traits"
    version = "boost-1.65.0"

eidheim/tiny-process-library¶

url = "git@gitlab.com:eidheim/tiny-process-library.git"
name = "tiny-process"

[tiny-process]
    target_type = "static library"
    [tiny-process.windows]
        sources = ["process.cpp", "process_win.cpp"]
    [tiny-process.linux]
        sources = ["process.cpp", "process_unix.cpp"]
    [tiny-process.osx]
        sources = ["process.cpp", "process_unix.cpp"]

[examples]
    sources = ["examples.cpp"]
    dependencies = ["tiny-process"]

[test-io]
    sources = ["tests/io_test.cpp"]
    dependencies = ["tiny-process"]

[test-multithread]
    sources = ["tests/multithread_test.cpp"]
    dependencies = ["tiny-process"]

[test-open-close]
    sources = ["tests/open_close_test.cpp"]
    dependencies = ["tiny-process"]

Configuration file reference¶

This is a reference of the available parameters you can set via the clang_build.toml config file.

Project settings¶

Examples of the project config parameters in use can be found in test/public_dependency.

name (optional)

A name is required if a project has subprojects.

type:	string
default:	“project”

url (optional)

type:	string
default:	“”

version (optional)

This only has an effect if a url was specified.

type:	string
default:	“”

directory (optional)

Note, if a url is specified, this is relative to the source root.

type:	string
default:	“”

subprojects (optional)

type:	list of strings
default:	[]

Target settings¶

Declaration¶

A target can be declared with a name square brackets. If none are specified, the default name is “main”.

General parameters¶

url (optional)

type:	string
default:	“”

version (optional)

This only has an effect if a url was specified.

type:	string
default:	“”

directory (optional)

Note, if a url is specified, this is relative to the source root.

type:	string
default:	“”

target_type (optional)

type:	string
default:	if sources are found “executable”, else “header only”
options:	“executable”, “shared library”, “static library”, “header only”

dependencies (optional)

type:	list of strings
default:	[]

public_dependencies (optional)

type:	list of strings
default:	[]

Source parameters¶

include_directories (optional)

type:	list of strings
default:	[]

public_include_directories (optional)

type:	list of strings
default:	[]

sources (optional)

You can list files and/or glob patterns.

type:	list of strings
default:	if a “src” folder is present, any sources that are found inside, else any sources found in the target directory

sources_exclude (optional)

You can list files and/or glob patterns.

type:	list of strings
default:	[]

Flag parameters¶

Flags can be specified inside one of the following secions

flags
public_flags
interface_flags

or nested into a platform-spcific section

linux
osx
windows

compile (optional)

type:	list of strings
default:	[]

link (optional)

type:	list of strings
default:	[]

Output parameters¶

output_name (optional)

type:	string
default:	“”

output_prefix (optional)

type:	string
default:	“”

output_suffix (optional)

type:	string
default:	“”

Welcome to Clang Build’s documentation!¶

User’s Guide¶

First steps¶

The minimum working example¶

Switching between debug and release¶

Customisations¶

Custom target name¶

Custom folder names¶

Compiling a library¶

Multiple targets¶

Multiple self-developed targets¶

External GitHub target¶

Multiple projects¶

Requirements¶

Example configuration file¶

Multiple subprojects in the same file¶

Inheritance¶

General¶

Include directories¶

Flags¶

Dependencies¶

Platform dependence¶

Per-Platform Target Configuration¶

Example¶

Bundling¶

Build-folder binary bundle¶

Redistributable bundle¶

Adding projects with custom behaviour¶

Script requirements¶

Creating a project¶

Creating targets¶

Manipulating sources¶

Defaults¶

General¶

Search Paths¶

Build Type and Flags¶

Build Directories¶

Toolchains¶

Real world examples¶

GLFW¶

lz4¶

codeplea/genann¶

nikoreun/tinygrad¶

boost/filesystem¶

eidheim/tiny-process-library¶

Configuration file reference¶

Project settings¶

Target settings¶

Declaration¶

General parameters¶

Source parameters¶

Flag parameters¶

Output parameters¶

Code Documentation¶