stamen

Stamen - static menu generator
git clone git://git.dimitrijedobrota.com/stamen.git
Log | Files | Refs | README | LICENSE

HACKING.md (5908B)


      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 `stamen_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 `stamen_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", "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 ### Configure, build and test
     91 
     92 If you followed the above instructions, then you can configure, build and test
     93 the project respectively with the following commands from the project root on
     94 any operating system with any build system:
     95 
     96 ```sh
     97 cmake --preset=dev
     98 cmake --build --preset=dev
     99 ctest --preset=dev
    100 ```
    101 
    102 If you are using a compatible editor (e.g. VSCode) or IDE (e.g. CLion, VS), you
    103 will also be able to select the above created user presets for automatic
    104 integration.
    105 
    106 Please note that both the build and test commands accept a `-j` flag to specify
    107 the number of jobs to use, which should ideally be specified to the number of
    108 threads your CPU has. You may also want to add that to your preset using the
    109 `jobs` property, see the [presets documentation][1] for more details.
    110 
    111 ### Developer mode targets
    112 
    113 These are targets you may invoke using the build command from above, with an
    114 additional `-t <target>` flag:
    115 
    116 #### `coverage`
    117 
    118 Available if `ENABLE_COVERAGE` is enabled. This target processes the output of
    119 the previously run tests when built with coverage configuration. The commands
    120 this target runs can be found in the `COVERAGE_TRACE_COMMAND` and
    121 `COVERAGE_HTML_COMMAND` cache variables. The trace command produces an info
    122 file by default, which can be submitted to services with CI integration. The
    123 HTML command uses the trace command's output to generate an HTML document to
    124 `<binary-dir>/coverage_html` by default.
    125 
    126 #### `docs`
    127 
    128 Available if `BUILD_MCSS_DOCS` is enabled. Builds to documentation using
    129 Doxygen and m.css. The output will go to `<binary-dir>/docs` by default
    130 (customizable using `DOXYGEN_OUTPUT_DIRECTORY`).
    131 
    132 #### `format-check` and `format-fix`
    133 
    134 These targets run the clang-format tool on the codebase to check errors and to
    135 fix them respectively. Customization available using the `FORMAT_PATTERNS` and
    136 `FORMAT_COMMAND` cache variables.
    137 
    138 #### `spell-check` and `spell-fix`
    139 
    140 These targets run the codespell tool on the codebase to check errors and to fix
    141 them respectively. Customization available using the `SPELL_COMMAND` cache
    142 variable.
    143 
    144 ## Running tests on Windows with `BUILD_SHARED_LIBS=ON`
    145 
    146 If you are building a shared library on Windows, you must add the path to the
    147 DLL file to `PATH` when you want to run tests. One way you could do that is by
    148 using PowerShell and writing a script for it, e.g. `env.ps1` at the project
    149 root:
    150 
    151 ```powershell
    152 $oldPrompt = (Get-Command prompt).ScriptBlock
    153 
    154 function prompt() { "(Debug) $(& $oldPrompt)" }
    155 
    156 $VsInstallPath = & "${env:ProgramFiles(x86)}\Microsoft Visual Studio\Installer\vswhere.exe" -Property InstallationPath
    157 $Env:Path += ";$VsInstallPath\Common7\IDE;$Pwd\build\dev\Debug"
    158 ```
    159 
    160 Then you can source this script by running `. env.ps1`. This particular
    161 example will only work for Debug builds.
    162 
    163 ### Passing `PATH` to editors
    164 
    165 Make sure you launch your editor of choice from the console with the above
    166 script sourced. Look for `(Debug)` in the prompt to confirm, then run e.g.
    167 `code .` for VScode or `devenv .` for Visual Studio.
    168 
    169 [1]: https://cmake.org/cmake/help/latest/manual/cmake-presets.7.html
    170 [2]: https://cmake.org/download/