From 41a96c813336a933c21bdf7352d7f26115bfe3f8 Mon Sep 17 00:00:00 2001
From: Anonymous Maarten <anonymous.maarten@gmail.com>
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 098f35d2d6..41796ab64b 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).