Crafter.Build

A modern, cross-platform C++ build system designed specifically for C++20 modules. Built with simplicity and flexibility in mind.

Features

• C++20 Modules Support: Native support for modern C++ module systems
• JSON-based Configuration: Easy-to-read project configuration files
• Multi-Configuration Builds: Debug and Release builds with customizable settings
• Dependency Management: Easy integration with external projects
• Testing Framework: Built-in test execution capabilities

Installation

Prerequisites

lld
clang
git
lldb
onetbb
glslang
vulkan-devel
wasi-compiler-rt

Build from Source

git clone https://forgejo.catcrafts.net/Catcrafts/Crafter.Build.git
cd Crafter.Build
./build.sh

(Optionally add to your PATH for global access)

Getting Started

Quickstart Guide

1. Create a project.json file in your project directory:

{
    "name": "hello-world",
    "configurations": [
        {
            "name": "executable",
            "implementations": ["main"],
        },
        {
            "name": "executable-debug",
            "extends": ["executable"],
            "debug": true
        },
    ]
}

2. Create main.cpp:

#include <print>
int main() {
    std::println("Hello World!");
}

3. Build and run:

crafter-build build debug -r

Command Line Interface

# Build a specific configuration
crafter-build build [configuration]

# Run a specific test
crafter-build test [test]

# Run all tests
crafter-build test

# Display help information
crafter-build --help

# Specify project file path (defaults to project.json)
-p /path/to/project.json

# Run executable after building
-r

Test Configuration

Tests are defined in the tests array of your project file. A typical test configuration depends on your main project:

"tests": [
    {
        "name": "should-compile",
        "implementations": ["tests/ShouldCompile"],
        "dependencies": [
            {
                "path": "./project.json",
                "configuration": "lib-shared"
            }
        ]
    }
]

Writing Test Files

Test files must follow a specific format:

• Export a C-compatible function named RunTest()
• The RunTest() function must return nullptr if the test passes, or a pointer to an error message string if it fails

Example test implementation:

import std;
using namespace std;

extern "C" {
    string* RunTest() {
        // Perform your test logic here
        int expected = 42;
        int actual = 5 * 8 + 2; // Should equal 42
        
        if (actual != expected) {
            return new string("Test failed: expected " + to_string(expected) + ", but got " + to_string(actual));
        }
        
        // Return nullptr to indicate success
        return nullptr;
    }
}

Configuration Properties

Basic Properties

• name: Name of the configuration
• standard: C++ standard (default: c++26)
• interfaces: C++20 module files (.cppm extension)
• implementations: Source files (.cpp extension)
• additional_files: Files copied to output directory
• type: Project type (executable, library, shared-library, default: executable)
• extends: Array of configuration names to extend, later entries overwrite previous ones
• debug: Boolean enabling debug mode (default: false)

Dependencies

Both local and git dependencies are supported:

For git dependencies branch and commit are mutually exclusive, if neither is supplied the latest commit on the default branch is chosen

"dependencies": [
    {
        "path": "/home/Crafter.Build/project.json",
        "configuration": "debug-lib",
    },
    {
        "path": "https://github.com/Catcrafts/Crafter.Build.git",
        "configuration": "debug-lib",
        "branch": "master",
        "commit": "af7eb61c3d92ab18f6aa6c139ac7211a908a24ee"
    }
]

License

This project is licensed under the LGPL v3 License - see the LICENSE file for details.