From 26df6899356afcbea628e85be79d3063ccdc4c71 Mon Sep 17 00:00:00 2001
From: Anonymous Maarten <[EMAIL REDACTED]>
Date: Fri, 16 Jun 2023 14:21:33 +0200
Subject: [PATCH] docs: expand CMake documentation + add minimal CMake project
for reporting issues
---
docs/README-cmake.md | 143 +++++++++++++++++++++++++++++++++++++++----
1 file changed, 130 insertions(+), 13 deletions(-)
diff --git a/docs/README-cmake.md b/docs/README-cmake.md
index 0adec32dace1..2fd950b27a61 100644
--- a/docs/README-cmake.md
+++ b/docs/README-cmake.md
@@ -1,6 +1,6 @@
# CMake
-(www.cmake.org)
+[www.cmake.org](https://www.cmake.org/)
The CMake build system is supported on the following platforms:
@@ -11,23 +11,24 @@ The CMake build system is supported on the following platforms:
* macOS, iOS, and tvOS, with support for XCode
* Android
* Emscripten
-* RiscOS
+* FreeBSD
+* Haiku
+* Nintendo 3DS
* Playstation 2
* Playstation Vita
-* Nintendo 3DS
* QNX 7.x/8.x
+* RiscOS
## Building SDL
-Assuming the source for SDL is located at `~/sdl`.
+Assuming the source tree of SDL is located at `~/sdl`,
+this will configure and build SDL in the `~/build` directory:
```sh
cmake -S ~/sdl -B ~/build
cmake --build ~/build
-This will build SDL in the ~/build directory.
Installation can be done using:
cmake --install ~/build --prefix /usr/local # '--install' requires CMake 3.15, or newer
@@ -43,23 +44,26 @@ SDL can be included in your project in 2 major ways:
The following CMake script supports both, depending on the value of MYGAME_VENDORED.
-cmake_minimum_required(VERSION 3.0)
+cmake_minimum_required(VERSION 3.5)
project(mygame)
-# Create an option to switch between a system sdl library and a vendored sdl library
+# Create an option to switch between a system sdl library and a vendored SDL library
option(MYGAME_VENDORED "Use vendored libraries" OFF)
if(MYGAME_VENDORED)
- add_subdirectory(vendored/sdl EXCLUDE_FROM_ALL)
+ # This assumes you have added SDL as a submodule in vendored/SDL
+ add_subdirectory(vendored/SDL EXCLUDE_FROM_ALL)
else()
- # 1. Look for a SDL3 package, 2. look for the SDL3 component and 3. fail if none can be found
- find_package(SDL3 REQUIRED CONFIG REQUIRED COMPONENTS SDL3)
+ # 1. Look for a SDL3 package,
+ # 2. look for the SDL3-shared component, and
+ # 3. fail if the shared component cannot be found.
+ find_package(SDL3 REQUIRED CONFIG REQUIRED COMPONENTS SDL3-shared)
endif()
# Create your game executable target as usual
add_executable(mygame WIN32 mygame.c)
-# Link to the actual SDL3 library. SDL3::SDL3 is the shared SDL library, SDL3::SDL3-static is the static SDL libarary.
+# Link to the actual SDL3 library.
target_link_libraries(mygame PRIVATE SDL3::SDL3)
@@ -80,7 +84,9 @@ The following components are available, to be used as an argument of `find_packa
Using a vendored SDL
-This only requires a copy of SDL in a subdirectory.
+This only requires a copy of SDL in a subdirectory + add_subdirectory.
+Alternatively, use FetchContent.
+Depending on the configuration, the same targets as a system SDL package are available.
CMake configuration options
@@ -97,6 +103,11 @@ To build it, run:
cmake --build . --config Release
+### Shared or static
+
+By default, only a shared SDL library is built and installed.
+The options `-DSDL_SHARED=` and `-DSDL_STATIC=` accept boolean values to change this.
+
### Pass custom compile options to the compiler
- Use [`CMAKE_<LANG>_FLAGS`](https://cmake.org/cmake/help/latest/variable/CMAKE_LANG_FLAGS.html) to pass extra
@@ -185,3 +196,109 @@ To use, set the following CMake variables when running CMake's configuration sta
```cmake
cmake ~/sdl -DCMAKE_TOOLCHAIN_FILE=~/sdl/build-scripts/cmake-toolchain-qnx-aarch64le.cmake -DSDL_X11=0
```
+
+## Help, it doesn't work!
+
+Below, a SDL3 CMake project can be found that builds 99.9% of time (assuming you have internet connectivity).
+When you have a problem with building or using SDL, please modify it until it reproduces your issue.
+
+```cmake
+cmake_minimum_required(VERSION 3.16)
+project(sdl_issue)
+
+# !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+# !!!!!! !!!!!!
+# !!!!!! This CMake script is not using "CMake best practices". !!!!!!
+# !!!!!! Don't use it in your project. !!!!!!
+# !!!!!! !!!!!!
+# !!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
+
+# 1. Try system SDL3 package first
+find_package(SDL3 QUIET)
+if(SDL3_FOUND)
+ message(STATUS "Using SDL3 via find_package")
+endif()
+
+# 2. Try using a vendored SDL library
+if(NOT SDL3_FOUND AND EXISTS "${CMAKE_CURRENT_LIST_DIR}/SDL/CMakeLists.txt")
+ add_subdirectory(SDL)
+ message(STATUS "Using SDL3 via add_subdirectory")
+ set(SDL3_FOUND TRUE)
+endif()
+
+# 3. Download SDL, and use that.
+if(NOT SDL3_FOUND)
+ include(FetchContent)
+ set(SDL_SHARED TRUE CACHE BOOL "Build a SDL shared library (if available)")
+ set(SDL_STATIC TRUE CACHE BOOL "Build a SDL static library (if available)")
+ FetchContent_Declare(
+ SDL
+ GIT_REPOSITORY https://github.com/libsdl-org/SDL.git
+ GIT_TAG main # Replace this with a particular git tag or git hash
+ GIT_SHALLOW TRUE
+ GIT_PROGRESS TRUE
+ )
+ message(STATUS "Using SDL3 via FetchContent")
+ FetchContent_MakeAvailable(SDL)
+ set_property(DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/_deps/sdl-src" PROPERTY EXCLUDE_FROM_ALL TRUE)
+endif()
+
+file(WRITE main.c [===========================================[
+/**
+ * Modify this source such that it reproduces your problem.
+ */
+
+/* START of source modifications */
+
+#include <SDL3/SDL.h>
+
+int main(int argc, char *argv[]) {
+ if (SDL_Init(SDL_INIT_EVERYTHING) < 0) {
+ SDL_Log("SDL_Init failed (%s)", SDL_GetError());
+ return 1;
+ }
+
+ SDL_Window *window = NULL;
+ SDL_Renderer *renderer = NULL;
+
+ if (SDL_CreateWindowAndRenderer(640, 480, 0, &window, &renderer) < 0) {
+ SDL_Log("SDL_CreateWindowAndRenderer failed (%s)", SDL_GetError());
+ SDL_Quit();
+ return 1;
+ }
+ SDL_SetWindowTitle(window, "SDL issue");
+
+ while (1) {
+ int finished = 0;
+ SDL_Event event;
+ while (SDL_PollEvent(&event)) {
+ if (event.type == SDL_EVENT_QUIT) {
+ finished = 1;
+ break;
+ }
+ }
+ if (finished) {
+ break;
+ }
+
+ SDL_SetRenderDrawColor(renderer, 80, 80, 80, SDL_ALPHA_OPAQUE);
+ SDL_RenderClear(renderer);
+ SDL_RenderPresent(renderer);
+ }
+
+ SDL_DestroyRenderer(renderer);
+ SDL_DestroyWindow(window);
+
+ SDL_Quit();
+}
+
+/* END of source modifications */
+
+]===========================================])
+
+add_executable(sdl_issue main.c)
+
+target_link_libraries(sdl_issue PRIVATE SDL3::SDL3)
+# target_link_libraries(sdl_issue PRIVATE SDL3::SDL3-shared)
+# target_link_libraries(sdl_issue PRIVATE SDL3::SDL3-static)
+```