Catcrafts/Crafter.Build
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

README update

Browse source
This commit is contained in:
Jorijn van der Graaf 2025-11-03 17:00:23 +01:00
commit f8fc3836dd
2 changed files with 142 additions and 67 deletions
Download patch file Download diff file Expand all files Collapse all files

189
README.md
View file

@ -1,117 +1,172 @@
# About
# Crafter.Build
This is a simple and easy to use C++ build system for Linux designed for use with C++20 modules in mind, it uses JSON based project files.
A modern, cross-platform C++ build system designed specifically for C++20 modules. Built with simplicity and flexibility in mind.
# Install
## Features
## Prerequisites:
```
- **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
### Build from Source
```bash
git clone https://github.com/Catcrafts/Crafter.Build.git
git clone https://forgejo.catcrafts.net/Catcrafts/Crafter.Build.git
cd Crafter.Build
./build.sh
```
(optionally add to path)
(Optionally add to your PATH for global access)
# How to use
## Getting Started
## Quickstart
### Quickstart Guide
create a ``project.json`` in an empty folder, open it in your preferred text editor.
Create a basic project file, with a base configuration and debug and release configuration
```JSON
1. Create a `project.json` file in your project directory:
```json
{
"name": "hello-world",
"configurations": [
{
"name": "base",
"standard": "c++26",
"source_files": ["main"],
"module_files": [],
"build_dir": "./build",
"output_dir": "./bin"
"name": "executable",
"implementations": ["main"],
},
{
"name": "debug",
"extends": ["base"],
"optimization_level": "0"
}
{
"name": "release",
"extends": ["base"],
"optimization_level": "3"
}
"name": "executable-debug",
"extends": ["executable"],
"debug": true
},
]
}
```
Save and close the file, create a ``main.cpp``
2. Create `main.cpp`:
```cpp
#include <print>
int main() {
std::println("Hello World!");
std::println("Hello World!");
}
```
Save and close, then run ``crafter-build -c debug``. Now you can run the ``hello-world`` executable that has appeared in the ``bin`` folder
## CLI arguments
3. Build and run:
```bash
crafter-build build debug -r
```
``--help`` Displays a help message.
## Command Line Interface
``-c`` The name of the configuration to build.
```bash
# Build a specific configuration
crafter-build build [configuration]
``-p`` The path to the project file, defaults to ``project.json``.
# Run a specific test
crafter-build test [test]
``-o`` Overrides the output folder.
# Run all tests
crafter-build test
``-r`` Runs the executable after building.
# Display help information
crafter-build --help
## configuration properties
``name`` Name of the configuration.
# Specify project file path (defaults to project.json)
-p /path/to/project.json
``standard`` C++ standard that this configuration uses, please refer to the [relevant clang documentation](https://clang.llvm.org/cxx_status.html), defaults to ``c++26``.
# Run executable after building
-r
```
``source_files`` All source files of the project ``.cpp`` extension is assumed.
## Test Configuration
``module_files`` All C++ 20 module files of the project ``.cppm`` extension is assumed.
Tests are defined in the `tests` array of your project file. A typical test configuration depends on your main project:
``additional_files`` Files that will be copied to the output_dir.
``build_dir`` The directory where intermediate files are stored.
``output_dir`` The directory where the output files will be placed.
``type`` The type of the project: ``executable``, ``library``, ``shared-library``, defaults to ``executable``.
``extends`` An array of configuration names that this configuration extends, later elements in the array take priority over previous ones.
``optimization_level`` Please refer to the [relevant clang documentation](https://clang.llvm.org/docs/CommandGuide/clang.html#code-generation-options), defaults to ``0``.
``dependencies`` An object array of the dependencies of this project, example:
```json
"dependencies": [
"tests": [
{
"path":"/home/Crafter.Build/project.json",
"configuration":"debug-lib",
"commit":"af7eb61c3d92ab18f6aa6c139ac7211a908a24ee"
}
{
"path":"https://github.com/Catcrafts/Crafter.Build.git",
"configuration":"debug-lib",
"branch":"master"
"name": "should-compile",
"implementations": ["tests/ShouldCompile"],
"dependencies": [
{
"path": "./project.json",
"configuration": "lib-shared"
}
]
}
]
```
This will now link the library of Crafter.Build in the configuration you use this in. ``commit`` and ``branch`` are optional parameters, if omitted the latest commit on the default branch is used.
``target`` Clang triplet this configuration uses, please refer to the [relevant clang documentation](https://clang.llvm.org/docs/CrossCompilation.html#target-triple).
### Writing Test Files
Note: the WASI SDK needs to be installed to compile to webassmbly, and ``$WASI_SDK_PATH`` needs to be set, please refer to the [wasi-sdk installation guide](https://github.com/WebAssembly/wasi-sdk?tab=readme-ov-file#install).
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.