1. rcrnstn/raytracer
  2. BUILDING.md
Browse code

Add project

Robert Cranston authored on 22/10/2023 23:56:32
Showing 1 changed files
BUILDING.md
History View file @ 3ab45a7
1 1 
new file mode 100644
... ... 
@@ -0,0 +1,94 @@
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 
+To build in parallel with native build tools that do not do this by default
53 
+(such as [GNU Make][]), pass `--parallel` followed by the number of concurrent
54 
+processes to use, e.g. `$(`[`nproc`][]`)`.
55 
+
56 
+[`cmake --build`]: https://cmake.org/cmake/help/v3.14/manual/cmake.1.html#build-a-project
57 
+[GNU Make]: https://www.gnu.org/software/make/
58 
+[`nproc`]: https://www.gnu.org/software/coreutils/manual/html_node/nproc-invocation.html
59 
+
60 
+## Test
61 
+
62 
+To run tests, use [`ctest`][]:
63 
+
64 
+```sh
65 
+(cd _build && ctest)
66 
+```
67 
+
68 
+To show output from failing tests, pass `--output-on-failure`. To show output
69 
+from all tests, pass `--verbose`.
70 
+
71 
+[`ctest`]: https://cmake.org/cmake/help/v3.14/manual/ctest.1.html
72 
+
73 
+## Package
74 
+
75 
+To package, use [`cpack`][]:
76 
+
77 
+```sh
78 
+(cd _build && cpack)
79 
+```
80 
+
81 
+[`cpack`]: https://cmake.org/cmake/help/v3.14/manual/cpack.1.html
82 
+
83 
+## Install
84 
+
85 
+To install onto the current system, use [`cmake --install`][]:
86 
+
87 
+```sh
88 
+cmake --install _build
89 
+```
90 
+
91 
+To set the prefix, pass e.g. `-D`[`CMAKE_INSTALL_PREFIX`][]`="$HOME/.local"`.
92 
+
93 
+[`cmake --install`]: https://cmake.org/cmake/help/v3.14/manual/cmake.1.html#install-a-project
94 
+[`CMAKE_INSTALL_PREFIX`]: https://cmake.org/cmake/help/v3.14/variable/CMAKE_INSTALL_PREFIX.html