Crucible
Crucible is an all-in-one framework for building cross-platform applications.
Dependencies
To build Crucible, you will need the following tools:
- A C++ compiler that can handle C++20 (Clang, GCC, and MSVC are all good choices)
- A build tool like Ninja or Make, or an IDE that includes one
- CMake version 3.19 or newer, or an IDE that includes it
- A reasonably modern version of Git
Additionally, some test scripts require Python 3. The build will still work if no Python
interpreter is found on the system; the tests will simply be skipped.
Supported targets
Crucible is officially supported on the following targets:
- macOS Monterey on aarch64
- Windows 10 on amd64
- Ubuntu 22.04 LTS on amd64
Similar systems should either work out of the box or require minimal modification.
Building
There are two ways to build Crucible: using CMake on the command line, or using an IDE with CMake
support.
CMake on the command line
To build using the command line version of CMake, assuming you have cloned the repository into
~/Repositories/crucible and have created a build directory ~/Builds/crucible, and are currently
in this build directory:
cmake ~/Repositories/crucible
cmake --build .
IDE with CMake support
Open the root CMakeLists.txt file in your IDE's project system. The IDE's build command should
automatically be hooked up to the CMake build system.
Build options
There are a few options you can pass to CMake:
CMAKE_BUILD_TYPE: The build type. Can be Release, RelWithDebInfo, or Debug. The default is
RelWithDebInfo.ENABLE_ASAN, ENABLE_TSAN, and ENABLE_UBSAN: Enable a subset of runtime sanitizers, which
help to detect common problems with unmanaged code like memory leaks, buffer overflows, and
deadlocks. Some sanitizers are mutually exclusive, and any given toolchain won't necessarily
support all sanitizers.
For development, the recommended settings are CMAKE_BUILD_TYPE=Debug and ENABLE_ASAN=ON on MSVC,
and additionally ENABLE_UBSAN=ON on Clang or GCC.
When using CMake on the command line, these options can be set using the -D flag to the cmake
command, e.g. cmake -DCMAKE_BUILD_TYPE=Debug -DENABLE_ASAN=ON ~/Repositories/crucible.
When using an IDE with CMake support, the way to specify CMake flags will vary with the IDE. Check
your IDE's documentation to find the correct place to specify these flags.
Testing
Crucible has a test suite that is integrated with CMake's CTest system. To run all the tests in the
project, use the ctest command on the command line, or find your IDE's CTest interface.
ctest has a few options that change the output:
--verbose causes all tests to always write their output--output-on-failure causes only tests that fail to write their output
If you want to run only one test binary, you have two choices:
- Use the
-R or --tests-regex option to CTest, where you can pass a regular expression pattern
matching the name(s) of the binary(/ies) you want to run
- Run the test binary directly, bypassing CTest entirely
As noted in the dependencies section, some tests are written as Python scripts, and
require Python 3 to run. If no Python interpreter is found on the system, these tests will simply be
skipped.
Credits
- Created & primary development by bravelytyped
- Additional development by Nekir
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
# Crucible
Crucible is an all-in-one framework for building cross-platform applications.
## Dependencies
To build Crucible, you will need the following tools:
* A C++ compiler that can handle C++20 (Clang, GCC, and MSVC are all good choices)
* A build tool like Ninja or Make, or an IDE that includes one
* CMake version 3.19 or newer, or an IDE that includes it
* A reasonably modern version of Git
Additionally, some test scripts require Python 3. The build will still work if no Python
interpreter is found on the system; the tests will simply be skipped.
## Supported targets
Crucible is officially supported on the following targets:
* macOS Monterey on aarch64
* Windows 10 on amd64
* Ubuntu 22.04 LTS on amd64
Similar systems should either work out of the box or require minimal modification.
## Building
There are two ways to build Crucible: using CMake on the command line, or using an IDE with CMake
support.
### CMake on the command line
To build using the command line version of CMake, assuming you have cloned the repository into
`~/Repositories/crucible` and have created a build directory `~/Builds/crucible`, and are currently
in this build directory:
```bash
cmake ~/Repositories/crucible
cmake --build .
```
### IDE with CMake support
Open the root `CMakeLists.txt` file in your IDE's project system. The IDE's build command should
automatically be hooked up to the CMake build system.
### Build options
There are a few options you can pass to CMake:
* `CMAKE_BUILD_TYPE`: The build type. Can be `Release`, `RelWithDebInfo`, or `Debug`. The default is
`RelWithDebInfo`.
* `ENABLE_ASAN`, `ENABLE_TSAN`, and `ENABLE_UBSAN`: Enable a subset of runtime sanitizers, which
help to detect common problems with unmanaged code like memory leaks, buffer overflows, and
deadlocks. Some sanitizers are mutually exclusive, and any given toolchain won't necessarily
support all sanitizers.
For development, the recommended settings are `CMAKE_BUILD_TYPE=Debug` and `ENABLE_ASAN=ON` on MSVC,
and additionally `ENABLE_UBSAN=ON` on Clang or GCC.
When using CMake on the command line, these options can be set using the `-D` flag to the `cmake`
command, e.g. `cmake -DCMAKE_BUILD_TYPE=Debug -DENABLE_ASAN=ON ~/Repositories/crucible`.
When using an IDE with CMake support, the way to specify CMake flags will vary with the IDE. Check
your IDE's documentation to find the correct place to specify these flags.
## Testing
Crucible has a test suite that is integrated with CMake's CTest system. To run all the tests in the
project, use the `ctest` command on the command line, or find your IDE's CTest interface.
`ctest` has a few options that change the output:
* `--verbose` causes all tests to always write their output
* `--output-on-failure` causes only tests that fail to write their output
If you want to run only one test binary, you have two choices:
* Use the `-R` or `--tests-regex` option to CTest, where you can pass a regular expression pattern
matching the name(s) of the binary(/ies) you want to run
* Run the test binary directly, bypassing CTest entirely
As noted in the [dependencies](#dependencies) section, some tests are written as Python scripts, and
require Python 3 to run. If no Python interpreter is found on the system, these tests will simply be
skipped.
## Credits
* Created & primary development by bravelytyped
* Additional development by Nekir