Crafter.Build/README.md

# 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
```bash
lld
clang
git
lldb
onetbb
glslang
vulkan-devel
```

### Build from Source
```bash
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:
```json
{
    "name": "hello-world",
    "configurations": [
        {
            "name": "executable",
            "implementations": ["main"],
        },
        {
            "name": "executable-debug",
            "extends": ["executable"],
            "debug": true
        },
    ]
}
```

2. Create `main.cpp`:
```cpp
#include <print>
int main() {
    std::println("Hello World!");
}
```

3. Build and run:
```bash
crafter-build build debug -r
```

## Command Line Interface

```bash
# 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:

```json
"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:
```cpp
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
- **build_dir**: Directory for intermediate build files  (default: `build`)
- **output_dir**: Directory for final output files (default: `bin`)
- **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
```json
"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.