Crucible
Crucible is a cross-platform, all-in-one framework for building high-performance C++ programs with
multimedia components, such as video games, creative tools, and scientific models.
Components
Crucible is broken into a handful of separate libraries, each having a specific function:
crucible-boot is a small static library that abstracts the various platform-specific entry
points into a single function, and also sets up some quality-of-life state like a crash handler
and UTF-8 command-line arguments.crucible-core contains fundamental building blocks that the rest of the framework requires to
function. This includes things like data structures, memory management, filesystem access, error
handling, and debugging tools.crucible-test is a unit testing system, both for use by applications and for testing Crucible
itself. Test cases are written in standard C++, and there is an auto-registration system to
minimize boilerplate.
There are also a handful of executables:
crucible-identify prints detailed information about Crucible itself, such as the toolchain used
to build it and the platform it was compiled for.
Building
These instructions show how to build Crucible on the command line. To build using an IDE, consult
your IDE's documentation about CMake projects.
Dependencies
To build this version of Crucible, you will need CMake, a supported build system, and a supported
compiler. The CMake version must be at least 3.23.
The supported build systems are those supported by CMake. Common choices are Make, Ninja, and
Visual Studio. For the full list, see cmake-generators.
The supported compilers are:
- Clang (or AppleClang) >= 14.0
- GCC >= 11.0
- MSVC >= 19.33
Other compilers or older versions of the supported compilers may or may not work with no or minimal
code changes, but are not supported.
Supported targets
Crucible is regularly built and tested on various recent versions of macOS, Ubuntu, and Windows in
a few different hardware configurations. Similar systems should either work out of the box or
require minimal source modification.
Configuring the build system
Before building, CMake needs to scan the system to determine what compilers are available, what
operating system the build will target, etc. This process will generate a set of build scripts that
constitute the actual build system.
While it is possible to configure the build by hand, it is recommended to use a build preset unless
you have a specific reason not to. There are three build presets currently available: development
(for debug builds), development:nosanitizers for debug builds without sanitizer support, and
release (for optimized builds).
To configure a build using the release preset, assuming the Crucible repository has been cloned
to ~/Repositories/crucible and you want the build directory to be at ~/Builds/crucible/release,
run the following command:
cmake --preset=release -S ~/Repositories/crucible -B ~/Builds/crucible/release
Running the build system
Once the build system has been generated, you can execute it to build Crucible. The easiest way to
do this is to let CMake do it for you with the following command (again assuming that your build
tree is at ~/Builds/crucible/release):
cmake --build ~/Builds/crucible/release
Running the test suite
Crucible has a comprehensive test suite that is integrated with the build system through the CTest
framework that comes with CMake. The best way to run the test suite is with the following command
(using the ~/Builds/crucible/release directory from the previous examples again):
ctest --test-dir=~/Builds/crucible/release --output-on-failure
Credits
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
# Crucible
Crucible is a cross-platform, all-in-one framework for building high-performance C++ programs with
multimedia components, such as video games, creative tools, and scientific models.
## Components
Crucible is broken into a handful of separate libraries, each having a specific function:
* `crucible-boot` is a small static library that abstracts the various platform-specific entry
points into a single function, and also sets up some quality-of-life state like a crash handler
and UTF-8 command-line arguments.
* `crucible-core` contains fundamental building blocks that the rest of the framework requires to
function. This includes things like data structures, memory management, filesystem access, error
handling, and debugging tools.
* `crucible-test` is a unit testing system, both for use by applications and for testing Crucible
itself. Test cases are written in standard C++, and there is an auto-registration system to
minimize boilerplate.
There are also a handful of executables:
* `crucible-identify` prints detailed information about Crucible itself, such as the toolchain used
to build it and the platform it was compiled for.
## Building
These instructions show how to build Crucible on the command line. To build using an IDE, consult
your IDE's documentation about CMake projects.
### Dependencies
To build this version of Crucible, you will need CMake, a supported build system, and a supported
compiler. The CMake version must be at least 3.23.
The supported build systems are those supported by CMake. Common choices are Make, Ninja, and
Visual Studio. For the full list, see [cmake-generators].
The supported compilers are:
* Clang (or AppleClang) >= 14.0
* GCC >= 11.0
* MSVC >= 19.33
Other compilers or older versions of the supported compilers may or may not work with no or minimal
code changes, but are not supported.
### Supported targets
Crucible is regularly built and tested on various recent versions of macOS, Ubuntu, and Windows in
a few different hardware configurations. Similar systems should either work out of the box or
require minimal source modification.
### Configuring the build system
Before building, CMake needs to scan the system to determine what compilers are available, what
operating system the build will target, etc. This process will generate a set of build scripts that
constitute the actual build system.
While it is possible to configure the build by hand, it is recommended to use a build preset unless
you have a specific reason not to. There are three build presets currently available: `development`
(for debug builds), `development:nosanitizers` for debug builds without sanitizer support, and
`release` (for optimized builds).
To configure a build using the `release` preset, assuming the Crucible repository has been cloned
to `~/Repositories/crucible` and you want the build directory to be at `~/Builds/crucible/release`,
run the following command:
```bash
cmake --preset=release -S ~/Repositories/crucible -B ~/Builds/crucible/release
```
### Running the build system
Once the build system has been generated, you can execute it to build Crucible. The easiest way to
do this is to let CMake do it for you with the following command (again assuming that your build
tree is at `~/Builds/crucible/release`):
```bash
cmake --build ~/Builds/crucible/release
```
### Running the test suite
Crucible has a comprehensive test suite that is integrated with the build system through the CTest
framework that comes with CMake. The best way to run the test suite is with the following command
(using the `~/Builds/crucible/release` directory from the previous examples again):
```bash
ctest --test-dir=~/Builds/crucible/release --output-on-failure
```
## Credits
* Written by Ysaie
[cmake-generators]: https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html