startgit

Static page generator for git repositories

git clone git://git.dimitrijedobrota.com/startgit.git

HACKING.md (5028B)

0 # Hacking 1 2 Here is some wisdom to help you build and test this project as a developer and 3 potential contributor. 4 5 If you plan to contribute, please read the [CONTRIBUTING](CONTRIBUTING.md) 6 guide. 7 8 ## Developer mode 9 10 Build system targets that are only useful for developers of this project are 11 hidden if the `startgit_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. 15 16 Developer mode is always set to on in CI workflows. 17 18 ### Presets 19 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. 24 25 You have a few options to pass `startgit_DEVELOPER_MODE` to the configure 26 command, but this project prefers to use presets. 27 28 As a developer, you should create a `CMakeUserPresets.json` file at the root of 29 the project: 30 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 ``` 68 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. 73 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. 77 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`. 88 89 ### Configure, build and test 90 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: 94 95 ```sh 96 cmake --preset=dev 97 cmake --build --preset=dev 98 ctest --preset=dev 99 ``` 100 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. 104 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. 109 110 ### Developer mode targets 111 112 These are targets you may invoke using the build command from above, with an 113 additional `-t <target>` flag: 114 115 #### `coverage` 116 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. 124 125 #### `docs` 126 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`). 130 131 #### `format-check` and `format-fix` 132 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. 136 137 #### `run-exe` 138 139 Runs the executable target `startgit_exe`. 140 141 #### `spell-check` and `spell-fix` 142 143 These targets run the codespell tool on the codebase to check errors and to fix 144 them respectively. Customization available using the `SPELL_COMMAND` cache 145 variable. 146 147 [1]: https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html 148 [2]: https://cmake.org/download/