poafloc

Parser Of Arguments For Lines Of Commands

git clone git://git.dimitrijedobrota.com/poafloc.git

HACKING.md (5549B)

1 # Hacking 2 3 Here is some wisdom to help you build and test this project as a developer and 4 potential contributor. 5 6 If you plan to contribute, please read the [CONTRIBUTING](CONTRIBUTING.md) 7 guide. 8 9 ## Developer mode 10 11 Build system targets that are only useful for developers of this project are 12 hidden if the `poafloc_DEVELOPER_MODE` option is disabled. Enabling this 13 option makes tests and other developer targets and options available. Not 14 enabling this option means that you are a consumer of this project and thus you 15 have no need for these targets and options. 16 17 Developer mode is always set to on in CI workflows. 18 19 ### Presets 20 21 This project makes use of [presets][1] to simplify the process of configuring 22 the project. As a developer, you are recommended to always have the [latest 23 CMake version][2] installed to make use of the latest Quality-of-Life 24 additions. 25 26 You have a few options to pass `poafloc_DEVELOPER_MODE` to the configure 27 command, but this project prefers to use presets. 28 29 As a developer, you should create a `CMakeUserPresets.json` file at the root of 30 the project: 31 32 ```json 33 { 34 "version": 2, 35 "cmakeMinimumRequired": { 36 "major": 3, 37 "minor": 14, 38 "patch": 0 39 }, 40 "configurePresets": [ 41 { 42 "name": "dev", 43 "binaryDir": "${sourceDir}/build/dev", 44 "inherits": ["dev-mode", "vcpkg", "ci-<os>"], 45 "cacheVariables": { 46 "CMAKE_BUILD_TYPE": "Debug" 47 } 48 } 49 ], 50 "buildPresets": [ 51 { 52 "name": "dev", 53 "configurePreset": "dev", 54 "configuration": "Debug" 55 } 56 ], 57 "testPresets": [ 58 { 59 "name": "dev", 60 "configurePreset": "dev", 61 "configuration": "Debug", 62 "output": { 63 "outputOnFailure": true 64 } 65 } 66 ] 67 } 68 ``` 69 70 You should replace `<os>` in your newly created presets file with the name of 71 the operating system you have, which may be `win64`, `linux` or `darwin`. You 72 can see what these correspond to in the 73 [`CMakePresets.json`](CMakePresets.json) file. 74 75 `CMakeUserPresets.json` is also the perfect place in which you can put all 76 sorts of things that you would otherwise want to pass to the configure command 77 in the terminal. 78 79 > **Note** 80 > Some editors are pretty greedy with how they open projects with presets. 81 > Some just randomly pick a preset and start configuring without your consent, 82 > which can be confusing. Make sure that your editor configures when you 83 > actually want it to, for example in CLion you have to make sure only the 84 > `dev-dev preset` has `Enable profile` ticked in 85 > `File > Settings... > Build, Execution, Deployment > CMake` and in Visual 86 > Studio you have to set the option `Never run configure step automatically` 87 > in `Tools > Options > CMake` **prior to opening the project**, after which 88 > you can manually configure using `Project > Configure Cache`. 89 90 ### Dependency manager 91 92 The above preset will make use of the [vcpkg][vcpkg] dependency manager. After 93 installing it, make sure the `VCPKG_ROOT` environment variable is pointing at 94 the directory where the vcpkg executable is. On Windows, you might also want 95 to inherit from the `vcpkg-win64-static` preset, which will make vcpkg install 96 the dependencies as static libraries. This is only necessary if you don't want 97 to setup `PATH` to run tests. 98 99 [vcpkg]: https://github.com/microsoft/vcpkg 100 101 ### Configure, build and test 102 103 If you followed the above instructions, then you can configure, build and test 104 the project respectively with the following commands from the project root on 105 any operating system with any build system: 106 107 ```sh 108 cmake --preset=dev 109 cmake --build --preset=dev 110 ctest --preset=dev 111 ``` 112 113 If you are using a compatible editor (e.g. VSCode) or IDE (e.g. CLion, VS), you 114 will also be able to select the above created user presets for automatic 115 integration. 116 117 Please note that both the build and test commands accept a `-j` flag to specify 118 the number of jobs to use, which should ideally be specified to the number of 119 threads your CPU has. You may also want to add that to your preset using the 120 `jobs` property, see the [presets documentation][1] for more details. 121 122 ### Developer mode targets 123 124 These are targets you may invoke using the build command from above, with an 125 additional `-t <target>` flag: 126 127 #### `coverage` 128 129 Available if `ENABLE_COVERAGE` is enabled. This target processes the output of 130 the previously run tests when built with coverage configuration. The commands 131 this target runs can be found in the `COVERAGE_TRACE_COMMAND` and 132 `COVERAGE_HTML_COMMAND` cache variables. The trace command produces an info 133 file by default, which can be submitted to services with CI integration. The 134 HTML command uses the trace command's output to generate an HTML document to 135 `<binary-dir>/coverage_html` by default. 136 137 #### `docs` 138 139 Available if `BUILD_MCSS_DOCS` is enabled. Builds to documentation using 140 Doxygen and m.css. The output will go to `<binary-dir>/docs` by default 141 (customizable using `DOXYGEN_OUTPUT_DIRECTORY`). 142 143 #### `format-check` and `format-fix` 144 145 These targets run the clang-format tool on the codebase to check errors and to 146 fix them respectively. Customization available using the `FORMAT_PATTERNS` and 147 `FORMAT_COMMAND` cache variables. 148 149 #### `run-examples` 150 151 Runs all the examples created by the `add_example` command. 152 153 #### `spell-check` and `spell-fix` 154 155 These targets run the codespell tool on the codebase to check errors and to fix 156 them respectively. Customization available using the `SPELL_COMMAND` cache 157 variable. 158 159 [1]: https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html 160 [2]: https://cmake.org/download/