Clang-build

Linux and OSX test: Windows test:

Motivation:

Meta build systems are inherently the wrong way to go, either the build system or the compiler should be platform-agnostic.
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 second programming language to be able to build C++
With Clang, finally a properly cross-platform compiler exists
With Python we have a language we can use consistently across platforms

Goals:

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

Related resources:

Usage

In order to run clang-build one should only need to have Python and Clang installed. If you have admin rights, pip install, otherwise just drop-in the clang-build.py script, e.g. curl -O https://raw.githubusercontent.com/GPMueller/clang-build-test/master/clang-build.py

clang-build to build the current directory
clang-build -d"path/to/dir" to build a different directory (alternatively --directory)
clang-build -V to print the called clang commands (alternatively --verbose)

The given directory will be searched for a clang-build.toml file, which you can use to configure your build targets, if necessary. If the build file cannot be found, clang-build will try to create an executable from your project, searching the root and some default folders for sources and headers.

Note: until this is a package on pypi, you need to call python clang-build.py instead of just clang-build...

General Ideas

What should be trivial

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

build a hello world program (i.e anything with single main and without non-std dependencies)
build a reasonable MWE with local dependencies (potentially folder structure with e.g. src, include/MWE and include/thirdparty)
include stdlib
include anything that can be found by sane default search
using command line arguments:
- specify root/source folder
- set build type from (last used should be cached/remembered)
- set build verbosity

Sane defaults and default behaviour:

platform-independence
build into a "build/" directory, not into toplevel
for multiple targets build into "build/target"
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. github)
- header-only should be trivial
- for a regular (not too complicated) library 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 steps)
- 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"
scripting custom behaviour per target (e.g. generating a version header file before compiling)

What should be possible

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

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

# Top-level brackets indicate a target
[hello]
# Note: the following sources settings could be left out.
# .hpp and .cpp files will be searched for in include and src by default
[hello.sources]
file_extensions = [".hpp", ".cpp"]
include_directories = ["include"]
source_directories = ["src"]
# Some properties
[hello.properties]
cpp_version = 17
output_name = "runHello" # name should not contain pre- or suffixes such as lib, .exe, .so

Two targets with linking

# Build a library
[mylib]
target_type = "sharedlibrary"
[mylib.sources]
include_directories = ["mylib/include"]
source_directories = ["mylib/src"]

# Build an executable and link the library
[myexe]
output_name = "runExe"
target_type = "executable"
[myexe.sources]
include_directories = ["myexe/include"]
source_directories = ["myexe/src"]

[myexe.link]
dependencies = ["mylib"]

[myexe.flags]
link = ["-DMYLIB_SOME_DEFINE"]

A package used by a target

mypackage/clang-build.toml

# Build a library
[mylib]
target_type = "library"
[mylib.sources]
include_directories = ["mylib/include"]
source_directories = ["mylib/src"]

myexe/clang-build.toml

# Include an external package/target (i.e. not from this toml file)
[somelib]
external = true
path = "/path/to/sources"

# Build an executable and link the library
[myexe]
[myexe.sources]
include_directories = ["include"]
source_directories = ["src"]

[myexe.link]
dependencies = ["somelib"]

Packages from server

# Build a library
[mylib]
external = true
url = "https://github.com/trick-17/mylib"
version = 1.1 # will try to git checkout [v]1.1[.*]

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

Calling custom scripts

# Build an executable
[myexe]
[myexe.scripts]
before_compile = "generateVersionHeader.py"
before_link    = "something.py"
after_build    = "else.py"

Defaults

General

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>

Target properties

target and its properties are public by default. The property private = true can be used to set a target to be only visible in the local .toml.

Include Paths

Note: only those paths should be added to the build flags, which the build system finds contain needed files.

Linux

.
./include
/usr/local
/opt
$PATH
/include

OSX

.
./include
/usr/local
/opt
$PATH
/include

Windows

.
./include
%PATH%

External targets

Search paths

The build system should search these paths for folders with names corresponding to the external targets. For paths which were manually specified, the build system should search more deeply to try and find a clang-build.toml and in turn search that for the corresponding target names.

Local:

./
./<target_name>

git server:

<url>
<url>/<target_name>

adityac8 / clang-build