Skip to content

CONTRIBUTING.md

Latest commit

 

History

History
135 lines (96 loc) · 3.8 KB

CONTRIBUTING.md

File metadata and controls

135 lines (96 loc) · 3.8 KB

Development

Configure and Build the Project Using CMake Presets

The simplest way of configuring and building the project is to use CMake Presets. Appropriate presets for major compilers have been included by default. You can use cmake --list-presets=workflow to see all available presets.

Here is an example of invoking the gcc-debug preset:

cmake --workflow --preset gcc-debug

Generally, there are two kinds of presets, debug and release.

The debug presets are designed to aid development, so they have debuginfo and sanitizers enabled.

Note

The sanitizers that are enabled vary from compiler to compiler. See the toolchain files under (infra/cmake) to determine the exact configuration used for each preset.

The release presets are designed for production use, and consequently have the highest optimization turned on (e.g. O3).

Configure and Build Manually

If the presets are not suitable for your use case, a traditional CMake invocation will provide more configurability.

To configure, build and test the project manually, you can run this set of commands. Note that this requires GoogleTest to be installed.

cmake \
  -B build \
  -S . \
  -DCMAKE_CXX_STANDARD=20 \
  # Your extra arguments here.
cmake --build build
ctest --test-dir build

Important

Beman projects are passive projects, so you need to specify the C++ version via CMAKE_CXX_STANDARD when manually configuring the project.

Dependency Management

vcpkg

The best way to install the project's dependencies is to use the vcpkg workflow.

To do so, make sure vcpkg is installed and VCPKG_ROOT is defined in your environment, then specify -DCMAKE_TOOLCHAIN_FILE="$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake". Vcpkg will handle the project's dependencies, including GoogleTest.

Example commands:

cmake \
  -B build \
  -S . \
  -DCMAKE_CXX_STANDARD=20 \
  -DCMAKE_TOOLCHAIN_FILE="$VCPKG_ROOT/scripts/buildsystems/vcpkg.cmake"
cmake --build build
ctest --test-dir build

The file ./vcpkg.json configures the list of dependencies that will be configured by vcpkg.

FetchContent

Instead of installing the project's dependencies via a package manager, you can optionally configure beman.iterator_interface to fetch them automatically via CMake FetchContent.

To do so, specify -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=./infra/cmake/use-fetch-content.cmake. This will bring in GoogleTest automatically along with any other dependency the project may require.

Example commands:

cmake \
  -B build \
  -S . \
  -DCMAKE_CXX_STANDARD=20 \
  -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=./infra/cmake/use-fetch-content.cmake
cmake --build build
ctest --test-dir build

The file ./lockfile.json configures the list of dependencies and versions that will be acquired by FetchContent.

Project-specific configure arguments

Project-specific options are prefixed with BEMAN_ITERATOR_INTERFACE. You can see the list of available options with:

cmake -LH -S . -B build | grep "BEMAN_ITERATOR_INTERFACE" -C 2
Some project-specific configure arguments

BEMAN_ITERATOR_INTERFACE_BUILD_TESTS

Enable building tests and test infrastructure. Default: ON. Values: { ON, OFF }.

BEMAN_ITERATOR_INTERFACE_BUILD_EXAMPLES

Enable building examples. Default: ON. Values: { ON, OFF }.

BEMAN_ITERATOR_INTERFACE_INSTALL_CONFIG_FILE_PACKAGE

Enable installing the CMake config file package. Default: ON. Values: { ON, OFF }.

This is required so that users of beman.iterator_interface can use find_package(beman.iterator_interface) to locate the library.