From 41a96c813336a933c21bdf7352d7f26115bfe3f8 Mon Sep 17 00:00:00 2001
From: Anonymous Maarten <[EMAIL REDACTED]>
Date: Fri, 28 Jul 2023 00:41:26 +0200
Subject: [PATCH] doc: document building of SDL tests with CMake
---
docs/README-cmake.md | 24 ++++++++++++++++++++++++
1 file changed, 24 insertions(+)
diff --git a/docs/README-cmake.md b/docs/README-cmake.md
index 098f35d2d6a6..41796ab64b4a 100644
--- a/docs/README-cmake.md
+++ b/docs/README-cmake.md
@@ -35,6 +35,14 @@ cmake --install ~/build --prefix /usr/local # '--install' requires CMake
This will install SDL to /usr/local.
+### Building SDL tests
+
+You can build the SDL test programs by adding `-DSDL_TESTS=ON` to the first cmake command above:
+```sh
+cmake -S ~/sdl -B ~/build -DSDL_TEST=ON -DSDL_TESTS=ON
+```
+and then building normally. In this example, the test programs will be built and can be run from `~/build/tests/`.
+
## Including SDL in your project
SDL can be included in your project in 2 major ways:
@@ -197,6 +205,22 @@ To use, set the following CMake variables when running CMake's configuration sta
cmake ~/sdl -DCMAKE_TOOLCHAIN_FILE=~/sdl/build-scripts/cmake-toolchain-qnx-aarch64le.cmake -DSDL_X11=0
```
+## SDL-specific CMake options
+
+SDL can be customized through (platform-specific) CMake options.
+The following table shows generic options that are available for most platforms.
+At the end of SDL CMake configuration, a table shows all CMake options along with its detected value.
+
+| CMake option | Valid values | Description |
+|-------------------------------|--------------|-----------------------------------------------------------------------------------------------------|
+| `-DSDL_SHARED=` | `ON`/`OFF` | Build SDL shared library (not all platforms support this) (`libSDL3.so`/`libSDL3.dylib`/`SDL3.dll`) |
+| `-DSDL_STATIC=` | `ON`/`OFF` | Build SDL static library (`libSDL3.a`/`SDL3-static.lib`) |
+| `-DSDL_TEST=` | `ON`/`OFF` | Build SDL test library (`libSDL3_test.a`/`SDL3_test.lib`) |
+| `-DSDL_TESTS=` | `ON`/`OFF` | Build SDL test programs (**requires `-DSDL_TEST=ON`**) |
+| `-DSDL_DISABLE_INSTALL=` | `ON`/`OFF` | Don't create a SDL install target |
+| `-DSDL_DISABLE_INSTALL_DOCS=` | `ON`/`OFF` | Don't install the SDL documentation |
+| `-DSDL_INSTALL_TESTS=` | `ON`/`OFF` | Install the SDL test programs |
+
## Help, it doesn't work!
Below, a SDL3 CMake project can be found that builds 99.9% of time (assuming you have internet connectivity).