Robert Cranston authored on 14/10/2022 19:47:51
| 1 | 1 |
new file mode 100644 |
| ... | ... |
@@ -0,0 +1,88 @@ |
| 1 |
+# Building |
|
| 2 |
+ |
|
| 3 |
+This project supports [CMake][] and uses [`cmake-common`][]. There are several |
|
| 4 |
+ways to use it in other CMake-based projects: |
|
| 5 |
+ |
|
| 6 |
+- With [`find_package`][]: ([Package][] and) [install][] it on the system. |
|
| 7 |
+ |
|
| 8 |
+- With [`add_subdirectory`][]: Bundle it. |
|
| 9 |
+ |
|
| 10 |
+- With [`FetchContent`][]: Download it as part of the CMake configure step. |
|
| 11 |
+ |
|
| 12 |
+- With [`cmake-common`][]: Use any of the above methods through a simplified |
|
| 13 |
+ interface. |
|
| 14 |
+ |
|
| 15 |
+As usual, use [`add_dependencies`][] or [`target_link_libraries`][] (or |
|
| 16 |
+`cmake-common`'s `DEPENDENCIES_*`) to declare the dependency. |
|
| 17 |
+ |
|
| 18 |
+[CMake]: https://cmake.org |
|
| 19 |
+[`cmake-common`]: https://git.rcrnstn.net/rcrnstn/cmake-common |
|
| 20 |
+[`FetchContent`]: https://cmake.org/cmake/help/v3.14/module/FetchContent.html |
|
| 21 |
+[`add_subdirectory`]: https://cmake.org/cmake/help/v3.14/command/add_subdirectory.html |
|
| 22 |
+[`find_package`]: https://cmake.org/cmake/help/v3.14/command/find_package.html |
|
| 23 |
+[Package]: #Package |
|
| 24 |
+[Install]: #Install |
|
| 25 |
+[`add_dependencies`]: https://cmake.org/cmake/help/v3.14/command/add_dependencies.html |
|
| 26 |
+[`target_link_libraries`]: https://cmake.org/cmake/help/v3.14/command/target_link_libraries.html |
|
| 27 |
+ |
|
| 28 |
+## Configure and generate |
|
| 29 |
+ |
|
| 30 |
+To configure and generate a build tree, use `cmake`: |
|
| 31 |
+ |
|
| 32 |
+```sh |
|
| 33 |
+cmake -B _build |
|
| 34 |
+``` |
|
| 35 |
+ |
|
| 36 |
+To set the build type, pass e.g. `-D`[`CMAKE_BUILD_TYPE`][]`=Release`. |
|
| 37 |
+ |
|
| 38 |
+To disable building tests, pass `-D`[`BUILD_TESTING`][]`=OFF`. |
|
| 39 |
+ |
|
| 40 |
+[`cmake`]: https://cmake.org/cmake/help/v3.14/manual/cmake.1.html#generate-a-project-buildsystem |
|
| 41 |
+[`CMAKE_BUILD_TYPE`]: https://cmake.org/cmake/help/v3.14/variable/CMAKE_BUILD_TYPE.html |
|
| 42 |
+[`BUILD_TESTING`]: https://cmake.org/cmake/help/v3.14/module/CTest.html |
|
| 43 |
+ |
|
| 44 |
+## Build |
|
| 45 |
+ |
|
| 46 |
+To build, use [`cmake --build`][]: |
|
| 47 |
+ |
|
| 48 |
+```sh |
|
| 49 |
+cmake --build _build |
|
| 50 |
+``` |
|
| 51 |
+ |
|
| 52 |
+[`cmake --build`]: https://cmake.org/cmake/help/v3.14/manual/cmake.1.html#build-a-project |
|
| 53 |
+ |
|
| 54 |
+## Test |
|
| 55 |
+ |
|
| 56 |
+To run tests, use [`ctest`][]: |
|
| 57 |
+ |
|
| 58 |
+```sh |
|
| 59 |
+(cd _build && ctest) |
|
| 60 |
+``` |
|
| 61 |
+ |
|
| 62 |
+To show output from failing tests, pass `--output-on-failure`. To show output |
|
| 63 |
+from all tests, pass `--verbose`. |
|
| 64 |
+ |
|
| 65 |
+[`ctest`]: https://cmake.org/cmake/help/v3.14/manual/ctest.1.html |
|
| 66 |
+ |
|
| 67 |
+## Package |
|
| 68 |
+ |
|
| 69 |
+To package, use [`cpack`][]: |
|
| 70 |
+ |
|
| 71 |
+```sh |
|
| 72 |
+(cd _build && cpack) |
|
| 73 |
+``` |
|
| 74 |
+ |
|
| 75 |
+[`cpack`]: https://cmake.org/cmake/help/v3.14/manual/cpack.1.html |
|
| 76 |
+ |
|
| 77 |
+## Install |
|
| 78 |
+ |
|
| 79 |
+To install onto the current system, use [`cmake --install`][]: |
|
| 80 |
+ |
|
| 81 |
+```sh |
|
| 82 |
+cmake --install _build |
|
| 83 |
+``` |
|
| 84 |
+ |
|
| 85 |
+To set the prefix, pass e.g. `-D`[`CMAKE_INSTALL_PREFIX`][]`="$HOME/.local"`. |
|
| 86 |
+ |
|
| 87 |
+[`cmake --install`]: https://cmake.org/cmake/help/v3.14/manual/cmake.1.html#install-a-project |
|
| 88 |
+[`CMAKE_INSTALL_PREFIX`]: https://cmake.org/cmake/help/v3.14/variable/CMAKE_INSTALL_PREFIX.html |
git.rcrnstn.net