|
| 1 | +# Development |
| 2 | + |
| 3 | +## Configure and Build the Project Using CMake Presets |
| 4 | + |
| 5 | +The simplest way of configuring and building the project is to use [CMake |
| 6 | +Presets](https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html). Appropriate |
| 7 | +presets for major compilers have been included by default. You can use `cmake |
| 8 | +--list-presets=workflow` to see all available presets. |
| 9 | + |
| 10 | +Here is an example of invoking the `gcc-debug` preset: |
| 11 | + |
| 12 | +```shell |
| 13 | +cmake --workflow --preset gcc-debug |
| 14 | +``` |
| 15 | + |
| 16 | +Generally, there are two kinds of presets, `debug` and `release`. |
| 17 | + |
| 18 | +The `debug` presets are designed to aid development, so they have debuginfo and sanitizers |
| 19 | +enabled. |
| 20 | + |
| 21 | +> [!NOTE] |
| 22 | +> |
| 23 | +> The sanitizers that are enabled vary from compiler to compiler. See the toolchain files |
| 24 | +> under ([`infra/cmake`](infra/cmake/)) to determine the exact configuration used for each |
| 25 | +> preset. |
| 26 | +
|
| 27 | +The `release` presets are designed for production use, and |
| 28 | +consequently have the highest optimization turned on (e.g. `O3`). |
| 29 | + |
| 30 | +## Configure and Build Manually |
| 31 | + |
| 32 | +If the presets are not suitable for your use case, a traditional CMake invocation will |
| 33 | +provide more configurability. |
| 34 | + |
| 35 | +To configure, build and test the project manually, you can run this set of commands. Note |
| 36 | +that this requires GoogleTest to be installed. |
| 37 | + |
| 38 | +```bash |
| 39 | +cmake \ |
| 40 | + -B build \ |
| 41 | + -S . \ |
| 42 | + -DCMAKE_CXX_STANDARD=23 \ |
| 43 | + # Your extra arguments here. |
| 44 | +cmake --build build |
| 45 | +ctest --test-dir build |
| 46 | +``` |
| 47 | + |
| 48 | +> [!IMPORTANT] |
| 49 | +> |
| 50 | +> Beman projects are [passive projects]( |
| 51 | +> https://github.com/bemanproject/beman/blob/main/docs/beman_standard.md#cmakepassive_projects), |
| 52 | +> so you need to specify the C++ version via `CMAKE_CXX_STANDARD` when manually |
| 53 | +> configuring the project. |
| 54 | +
|
| 55 | +## Dependency Management |
| 56 | + |
| 57 | +### FetchContent |
| 58 | + |
| 59 | +Instead of installing the project's dependencies via a package manager, you can optionally |
| 60 | +configure beman.transform_view to fetch them automatically via CMake FetchContent. |
| 61 | + |
| 62 | +To do so, specify |
| 63 | +`-DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=./infra/cmake/use-fetch-content.cmake`. This will |
| 64 | +bring in GoogleTest automatically along with any other dependency the project may require. |
| 65 | + |
| 66 | +Example commands: |
| 67 | + |
| 68 | +```shell |
| 69 | +cmake \ |
| 70 | + -B build \ |
| 71 | + -S . \ |
| 72 | + -DCMAKE_CXX_STANDARD=23 \ |
| 73 | + -DCMAKE_PROJECT_TOP_LEVEL_INCLUDES=./infra/cmake/use-fetch-content.cmake |
| 74 | +cmake --build build |
| 75 | +ctest --test-dir build |
| 76 | +``` |
| 77 | + |
| 78 | +The file `./lockfile.json` configures the list of dependencies and versions that will be |
| 79 | +acquired by FetchContent. |
| 80 | + |
| 81 | +## Project-specific configure arguments |
| 82 | + |
| 83 | +Project-specific options are prefixed with `BEMAN_TRANSFORM_VIEW`. |
| 84 | +You can see the list of available options with: |
| 85 | + |
| 86 | +```bash |
| 87 | +cmake -LH -S . -B build | grep "BEMAN_TRANSFORM_VIEW" -C 2 |
| 88 | +``` |
| 89 | + |
| 90 | +<details> |
| 91 | + |
| 92 | +<summary>Some project-specific configure arguments</summary> |
| 93 | + |
| 94 | +### `BEMAN_TRANSFORM_VIEW_BUILD_TESTS` |
| 95 | + |
| 96 | +Enable building tests and test infrastructure. Default: `ON`. |
| 97 | +Values: `{ ON, OFF }`. |
| 98 | + |
| 99 | +### `BEMAN_TRANSFORM_VIEW_BUILD_EXAMPLES` |
| 100 | + |
| 101 | +Enable building examples. Default: `ON`. Values: `{ ON, OFF }`. |
| 102 | + |
| 103 | +### `BEMAN_TRANSFORM_VIEW_INSTALL_CONFIG_FILE_PACKAGE` |
| 104 | + |
| 105 | +Enable installing the CMake config file package. Default: `ON`. |
| 106 | +Values: `{ ON, OFF }`. |
| 107 | + |
| 108 | +This is required so that users of `beman.transform_view` can use |
| 109 | +`find_package(beman.transform_view)` to locate the library. |
| 110 | + |
| 111 | +</details> |
0 commit comments