diff --git a/docs/README-cmake.md b/docs/README-cmake.md index 0adec32da..2fd950b27 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: - ```sh 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 -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](https://cmake.org/cmake/help/latest/module/FetchContent.html). +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__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 + +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) +```