1## Minimum build requirements 2 3 - C/C++ compiler with support for C++17 4 - SDL >= 2.0.5 5 - Opusfile 6 - Meson >= 0.54.2, or Visual Studio Community Edition 2019 or 2022 7 - OS that is mostly POSIX-compliant or up-to-date Windows system 8 9All other dependencies are optional and can be disabled while configuring the 10build (in `meson setup` step). 11 12## OS-specific instructions 13 14Instructions in this article assume you're using Linux or BSD but will work 15on any modern system. Documentation for programmers using other systems: 16[Windows], [macOS], [Haiku]. 17 18[Windows]: docs/build-windows.md 19[macOS]: docs/build-macos.md 20[Haiku]: docs/build-haiku.md 21 22## Make a build with the built-in debugger 23 24On Linux, BSD, macOS, or MSYS2: install the `ncurses` development library 25with headers included (as opposed to the bare library), and then: 26 27``` shell 28# setup the default debugger 29meson setup -Dbuildtype=release -Denable_debugger=normal build/debugger 30# -or- setup the heavy debugger 31meson setup -Dbuildtype=release -Denable_debugger=heavy build/debugger 32# build 33ninja -C build/debugger 34``` 35 36If using Visual Studio, install `pdcurses` using vcpkg and change 37the `C_DEBUG` and optionally the `C_HEAVY_DEBUG` lines inside 38`src/platform/visualc/config.h`. 39 40Default debugger: 41 42``` c++ 43#define C_DEBUG 1 44#define C_HEAVY_DEBUG 0 45``` 46 47Heavy debugger: 48 49``` c++ 50#define C_DEBUG 1 51#define C_HEAVY_DEBUG 1 52``` 53 54Then perform a release build. 55 56 57## Meson build snippets 58 59### Make a debug build 60 61Install dependencies listed in [README.md](README.md). Although `ccache` is 62optional, we recommend installing it because Meson will use it to greatly speed 63up builds. 64 65Build steps: 66 67``` shell 68meson setup build 69ninja -C build 70``` 71Directory `build` will contain all compiled files. 72 73### Other build types 74 75Meson supports several build types, appropriate for various situations: 76`release` for creating optimized release binaries, `debug` (default) for 77for development or `plain` for packaging. 78 79``` shell 80meson setup -Dbuildtype=release build 81``` 82 83For those interested in performing many different build types, separate 84build/ directories (or subdirectories) can be used. This allows builds to 85be organized by type as well as allows easy side-by-side comparison of 86builds. 87 88One thing to note: If you use the VSCode editor with the clangd plugin, 89this plugin assumes Meson setup's "compile_commands.json" output file 90always resides in the hardcoded build/ directory. To work-around this bug, 91feel free to symlink this file from your active build directory into 92the hardcoded build/ location. 93 94Detailed documentation: [Meson: Core options][meson-core] 95 96[meson-core]: https://mesonbuild.com/Builtin-options.html#core-options 97 98### Disabling unwanted dependencies 99 100The majority of dependencies are optional and can be disabled during build. 101 102For example, to compile without OpenGL dependency try: 103 104``` shell 105meson setup -Duse_opengl=false build 106ninja -C build 107``` 108 109### List Meson's setup options 110 111Run `meson configure` to see the full list of Meson setup options as well 112as project-specific options. Or, see the file 113[`meson_options.txt`](meson_options.txt) for only the project-specific 114options. 115 116To query the options set in an existing build directory, simply append 117the build directory to the above command. For example: 118 119``` shell 120meson configure build 121``` 122 123Options can be passed to the `meson setup` command using `-Doption=value` 124notation or using comma-separated notation (ie: `-Doption=value1,value2,value3`) 125when the option supports multiple values. 126 127 128### Run unit tests 129 130Prerequisites: 131 132``` shell 133# Fedora 134sudo dnf install gtest-devel 135``` 136``` shell 137# Debian, Ubuntu 138sudo apt install libgtest-dev 139``` 140If `gtest` is not available/installed on the OS, Meson will download it 141automatically. 142 143Build and run tests: 144 145``` shell 146meson setup build 147meson test -C build 148``` 149 150### Run unit tests (with user-supplied gtest sources) 151 152*Appropriate during packaging or when user is behind a proxy or without 153internet access.* 154 155Place files described in `subprojects/gtest.wrap` file in 156`subprojects/packagecache/` directory, and then: 157 158``` shell 159meson setup --wrap-mode=nodownload build 160meson test -C build 161``` 162 163### Build test coverage report 164 165Prerequisites: 166 167``` shell 168# Fedora 169sudo dnf install gcovr lcov 170``` 171 172Run tests and generate report: 173 174``` shell 175meson setup -Db_coverage=true build 176meson test -C build 177ninja -C build coverage-html 178``` 179 180Open the report with your browser: 181 182``` shell 183firefox build/meson-logs/coveragereport/index.html" 184``` 185 186### Static analysis report 187 188Prerequisites: 189 190``` shell 191# Fedora 192sudo dnf install clang-analyzer 193``` 194``` shell 195# Debian, Ubuntu 196sudo apt install clang-tools 197``` 198 199Build and generate report: 200 201``` shell 202meson setup build 203ninja -C build scan-build 204``` 205