crucible

Crucible

Crucible is a cross-platform, all-in-one framework for building C++ software, mainly targeted at multimedia applications, video games, and scientific computing.

Capabilities

Crucible is broken into a handful of separate libraries, each having a specific function:

• 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.

Dependencies

To build Crucible, you will need the following tools:

• A C++ compiler that can handle C++20 (Clang, GCC, and MSVC have build presets)
• 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 regularly built and tested on the following operating systems and hardware:

• macOS 13.1 Ventura on Apple M1
• Windows 10 on AMD Ryzen 9 3900X
• Ubuntu 22.04 LTS on AMD Ryzen 9 3900X

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 presets

Crucible provides a handful of"known good" preset configurations for different compilers and build scenarios. This is done by passing the --preset=NAME option to CMake, or configuring a specific preset in your IDE.

There are two broad sets of presets: development and release. development presets produce a developer-friendly build, with sanitizers enabled and minimum optimization to play nice with debuggers. release presets produce a release-ready build, with sanitizers disabled and maximum optimizations to ensure the best performance. Debug symbols are still generated in order to generate useful crash reports.

Each class of preset is defined for each of the compilers that Crucible is regularly built with. There is a decent chance they will work with similar compilers.

These are the currently available build presets:

• development:clang
• development:gcc
• development:msvc
• release:clang
• release:gcc
• release:msvc

While the build system is designed so that using no specific preset should build something that works, it's recommended to always specify a build preset so that you know exactly what you can expect from Crucible at runtime.

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 & developed by bravelytyped