crucible

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

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

Credits

• Created & primary development by bravelytyped
• Additional development by Nekir