displayLayout and Rendering TUI library |
| git clone git://git.dimitrijedobrota.com/display.git |
| Log | Files | Refs | README | LICENSE | HACKING | CONTRIBUTING | CODE_OF_CONDUCT | BUILDING |
HACKING.md (5910B)
0 # Hacking
2 Here is some wisdom to help you build and test this project as a developer and
3 potential contributor.
5 If you plan to contribute, please read the [CONTRIBUTING](CONTRIBUTING.md)
6 guide.
8 ## Developer mode
10 Build system targets that are only useful for developers of this project are
11 hidden if the `display_DEVELOPER_MODE` option is disabled. Enabling this
12 option makes tests and other developer targets and options available. Not
13 enabling this option means that you are a consumer of this project and thus you
14 have no need for these targets and options.
16 Developer mode is always set to on in CI workflows.
18 ### Presets
20 This project makes use of [presets][1] to simplify the process of configuring
21 the project. As a developer, you are recommended to always have the [latest
22 CMake version][2] installed to make use of the latest Quality-of-Life
23 additions.
25 You have a few options to pass `display_DEVELOPER_MODE` to the configure
26 command, but this project prefers to use presets.
28 As a developer, you should create a `CMakeUserPresets.json` file at the root of
29 the project:
31 ```json
32 {
33 "version": 2,
34 "cmakeMinimumRequired": {
35 "major": 3,
36 "minor": 14,
37 "patch": 0
38 },
39 "configurePresets": [
40 {
41 "name": "dev",
42 "binaryDir": "${sourceDir}/build/dev",
43 "inherits": ["dev-mode", "ci-<os>"],
44 "cacheVariables": {
45 "CMAKE_BUILD_TYPE": "Debug"
46 }
47 }
48 ],
49 "buildPresets": [
50 {
51 "name": "dev",
52 "configurePreset": "dev",
53 "configuration": "Debug"
54 }
55 ],
56 "testPresets": [
57 {
58 "name": "dev",
59 "configurePreset": "dev",
60 "configuration": "Debug",
61 "output": {
62 "outputOnFailure": true
63 }
64 }
65 ]
66 }
67 ```
69 You should replace `<os>` in your newly created presets file with the name of
70 the operating system you have, which may be `win64`, `linux` or `darwin`. You
71 can see what these correspond to in the
72 [`CMakePresets.json`](CMakePresets.json) file.
74 `CMakeUserPresets.json` is also the perfect place in which you can put all
75 sorts of things that you would otherwise want to pass to the configure command
76 in the terminal.
78 > **Note**
79 > Some editors are pretty greedy with how they open projects with presets.
80 > Some just randomly pick a preset and start configuring without your consent,
81 > which can be confusing. Make sure that your editor configures when you
82 > actually want it to, for example in CLion you have to make sure only the
83 > `dev-dev preset` has `Enable profile` ticked in
84 > `File > Settings... > Build, Execution, Deployment > CMake` and in Visual
85 > Studio you have to set the option `Never run configure step automatically`
86 > in `Tools > Options > CMake` **prior to opening the project**, after which
87 > you can manually configure using `Project > Configure Cache`.
89 ### Configure, build and test
91 If you followed the above instructions, then you can configure, build and test
92 the project respectively with the following commands from the project root on
93 any operating system with any build system:
95 ```sh
96 cmake --preset=dev
97 cmake --build --preset=dev
98 ctest --preset=dev
99 ```
101 If you are using a compatible editor (e.g. VSCode) or IDE (e.g. CLion, VS), you
102 will also be able to select the above created user presets for automatic
103 integration.
105 Please note that both the build and test commands accept a `-j` flag to specify
106 the number of jobs to use, which should ideally be specified to the number of
107 threads your CPU has. You may also want to add that to your preset using the
108 `jobs` property, see the [presets documentation][1] for more details.
110 ### Developer mode targets
112 These are targets you may invoke using the build command from above, with an
113 additional `-t <target>` flag:
115 #### `coverage`
117 Available if `ENABLE_COVERAGE` is enabled. This target processes the output of
118 the previously run tests when built with coverage configuration. The commands
119 this target runs can be found in the `COVERAGE_TRACE_COMMAND` and
120 `COVERAGE_HTML_COMMAND` cache variables. The trace command produces an info
121 file by default, which can be submitted to services with CI integration. The
122 HTML command uses the trace command's output to generate an HTML document to
123 `<binary-dir>/coverage_html` by default.
125 #### `docs`
127 Available if `BUILD_MCSS_DOCS` is enabled. Builds to documentation using
128 Doxygen and m.css. The output will go to `<binary-dir>/docs` by default
129 (customizable using `DOXYGEN_OUTPUT_DIRECTORY`).
131 #### `format-check` and `format-fix`
133 These targets run the clang-format tool on the codebase to check errors and to
134 fix them respectively. Customization available using the `FORMAT_PATTERNS` and
135 `FORMAT_COMMAND` cache variables.
137 #### `spell-check` and `spell-fix`
139 These targets run the codespell tool on the codebase to check errors and to fix
140 them respectively. Customization available using the `SPELL_COMMAND` cache
141 variable.
143 ## Running tests on Windows with `BUILD_SHARED_LIBS=ON`
145 If you are building a shared library on Windows, you must add the path to the
146 DLL file to `PATH` when you want to run tests. One way you could do that is by
147 using PowerShell and writing a script for it, e.g. `env.ps1` at the project
148 root:
150 ```powershell
151 $oldPrompt = (Get-Command prompt).ScriptBlock
153 function prompt() { "(Debug) $(& $oldPrompt)" }
155 $VsInstallPath = & "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe" -Property InstallationPath
156 $Env:Path += ";$VsInstallPath\Common7\IDE;$Pwd\build\dev\Debug"
157 ```
159 Then you can source this script by running `. env.ps1`. This particular
160 example will only work for Debug builds.
162 ### Passing `PATH` to editors
164 Make sure you launch your editor of choice from the console with the above
165 script sourced. Look for `(Debug)` in the prompt to confirm, then run e.g.
166 `code .` for VScode or `devenv .` for Visual Studio.
168 [1]: https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html
169 [2]: https://cmake.org/download/