171 lines
No EOL
4 KiB
Markdown
171 lines
No EOL
4 KiB
Markdown
# 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
|
|
wasi-compiler-rt
|
|
```
|
|
|
|
### 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
|
|
- **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. |