Browse Source

Expand CMake documentation a bit (#5961)

* cmake: remove duplicate check_required_components macro

* Expand docs/README-cmake.md a bit

* cmake: path needs `/` infix
Anonymous Maarten 3 years ago
parent
commit
53141a56b4
2 changed files with 108 additions and 39 deletions
  1. 107 28
      docs/README-cmake.md
  2. 1 11
      sdl2-config.cmake.in

+ 107 - 28
docs/README-cmake.md

@@ -1,40 +1,102 @@
-CMake
-================================================================================
+# CMake
+
 (www.cmake.org)
 (www.cmake.org)
 
 
 SDL's build system was traditionally based on autotools. Over time, this
 SDL's build system was traditionally based on autotools. Over time, this
 approach has suffered from several issues across the different supported 
 approach has suffered from several issues across the different supported 
 platforms.
 platforms.
-To solve these problems, a new build system based on CMake is under development.
-It works in parallel to the legacy system, so users can experiment with it
-without complication.
-While still experimental, the build system should be usable on the following
-platforms:
+To solve these problems, a new build system based on CMake was introduced.
+It is developed in parallel to the legacy autotools build system, so users 
+can experiment with it without complication.
+
+The CMake build system is supported on the following platforms:
 
 
 * FreeBSD
 * FreeBSD
 * Linux
 * Linux
-* VS.NET 2010
+* Microsoft Visual C
 * MinGW and Msys
 * MinGW and Msys
 * macOS, iOS, and tvOS, with support for XCode
 * macOS, iOS, and tvOS, with support for XCode
+* Android
+* Emscripten
+* RiscOS
+* Playstation Vita
+
+## Building SDL
+
+Assuming the source for SDL is located at `~/sdl`
+```sh
+cd ~
+mkdir build
+cd build
+cmake ~/sdl
+cmake --build .
+```
+
+This will build the static and dynamic versions of SDL in the `~/build` directory.
+Installation can be done using:
+
+```sh
+cmake --install .        # '--install' requires CMake 3.15, or newer
+```
+
+## Including SDL in your project
+
+SDL can be included in your project in 2 major ways:
+- using a system SDL library, provided by your (*nix) distribution or a package manager
+- using a vendored SDL library: this is SDL copied or symlinked in a subfolder.
+
+The following CMake script supports both, depending on the value of `MYGAME_VENDORED`.
 
 
+```cmake
+cmake_minimum_required(VERSION 3.0)
+project(mygame)
 
 
-================================================================================
-Usage
-================================================================================
+# Create an option to switch between a system sdl library and a vendored sdl library
+option(MYGAME_VENDORED "Use vendored libraries" OFF)
 
 
-Assuming the source for SDL is located at ~/sdl
+if(MYGAME_VENDORED)
+    add_subdirectory(vendored/sdl EXCLUDE_FROM_ALL)
+else()
+    # 1. Look for a SDL2 package, 2. look for the SDL2 component and 3. fail if none can be found
+    find_package(SDL2 REQUIRED CONFIG REQUIRED COMPONENTS SDL2)
+    
+    # 1. Look for a SDL2 package, 2. Look for the SDL2maincomponent and 3. DO NOT fail when SDL2main is not available 
+    find_package(SDL2 REQUIRED CONFIG COMPONENTS SDL2main)
+endif()
 
 
-    cd ~
-    mkdir build
-    cd build
-    cmake ../sdl
+# Create your game executable target as usual 
+add_executable(mygame WIN32 mygame.c)
 
 
-This will build the static and dynamic versions of SDL in the ~/build directory.
+# SDL2::SDL2main may or may not be available. It is e.g. required by Windows GUI applications  
+if(TARGET SDL2::SDL2main)
+    # It has an implicit dependency on SDL2 functions, so it MUST be added before SDL2::SDL2 (or SDL2::SDL2-static)
+    target_link_libraries(mygame PRIVATE SDL2::SDL2main)
+endif()
 
 
+# Link to the actual SDL2 library. SDL2::SDL2 is the shared SDL library, SDL2::SDL2-static is the static SDL libarary.
+target_link_libraries(mygame PRIVATE SDL2::SDL2)
+```
 
 
-================================================================================
-Usage, iOS/tvOS
-================================================================================
+### A system SDL library
+
+For CMake to find SDL, it must be installed in [a default location CMake is looking for](https://cmake.org/cmake/help/latest/command/find_package.html#config-mode-search-procedure).
+
+The following components are available, to be used as an argument of `find_package`.
+
+| Component name | Description                                                                                |
+|----------------|--------------------------------------------------------------------------------------------|
+| SDL2           | The SDL2 shared library, available through the `SDL2::SDL2` target [^SDL_TARGET_EXCEPTION] |
+| SDL2-static    | The SDL2 static library, available through the `SDL2::SDL2-static` target                  |
+| SDL2main       | The SDL2main static library, available through the `SDL2::SDL2main` target                 |
+| SDL2test       | The SDL2test static library, available through the `SDL2::SDL2test` target                 |
+
+### Using a vendored SDL
+
+This only requires a copy of SDL in a subdirectory.
+
+## CMake configuration options for platforms
+
+### iOS/tvOS
 
 
 CMake 3.14+ natively includes support for iOS and tvOS.  SDL binaries may be built
 CMake 3.14+ natively includes support for iOS and tvOS.  SDL binaries may be built
 using Xcode or Make, possibly among other build-systems.
 using Xcode or Make, possibly among other build-systems.
@@ -53,32 +115,49 @@ To use, set the following CMake variables when running CMake's configuration sta
 - `CMAKE_OSX_ARCHITECTURES=<semicolon-separated list of CPU architectures>` (example: "arm64;armv7s;x86_64")
 - `CMAKE_OSX_ARCHITECTURES=<semicolon-separated list of CPU architectures>` (example: "arm64;armv7s;x86_64")
 
 
 
 
-### Examples (for iOS/tvOS):
+#### Examples
 
 
 - for iOS-Simulator, using the latest, installed SDK:
 - for iOS-Simulator, using the latest, installed SDK:
 
 
-    `cmake ~/sdl -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphonesimulator -DCMAKE_OSX_ARCHITECTURES=x86_64`
+    ```bash
+    cmake ~/sdl -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphonesimulator -DCMAKE_OSX_ARCHITECTURES=x86_64
+    ```
 
 
 - for iOS-Device, using the latest, installed SDK, 64-bit only
 - for iOS-Device, using the latest, installed SDK, 64-bit only
 
 
-    `cmake ~/sdl -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphoneos -DCMAKE_OSX_ARCHITECTURES=arm64`
+    ```bash
+    cmake ~/sdl -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphoneos -DCMAKE_OSX_ARCHITECTURES=arm64
+    ```
 
 
 - for iOS-Device, using the latest, installed SDK, mixed 32/64 bit
 - for iOS-Device, using the latest, installed SDK, mixed 32/64 bit
 
 
-    `cmake ~/sdl -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphoneos -DCMAKE_OSX_ARCHITECTURES="arm64;armv7s"`
+    ```cmake
+    cmake ~/sdl -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphoneos -DCMAKE_OSX_ARCHITECTURES="arm64;armv7s"
+    ```
 
 
 - for iOS-Device, using a specific SDK revision (iOS 12.4, in this example):
 - for iOS-Device, using a specific SDK revision (iOS 12.4, in this example):
 
 
-    `cmake ~/sdl -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphoneos12.4 -DCMAKE_OSX_ARCHITECTURES=arm64`
+    ```cmake
+    cmake ~/sdl -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphoneos12.4 -DCMAKE_OSX_ARCHITECTURES=arm64
+    ```
 
 
 - for iOS-Simulator, using the latest, installed SDK, and building SDL test apps (as .app bundles):
 - for iOS-Simulator, using the latest, installed SDK, and building SDL test apps (as .app bundles):
 
 
-    `cmake ~/sdl -DSDL_TESTS=1 -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphonesimulator -DCMAKE_OSX_ARCHITECTURES=x86_64`
+    ```cmake
+    cmake ~/sdl -DSDL_TESTS=1 -DCMAKE_SYSTEM_NAME=iOS -DCMAKE_OSX_SYSROOT=iphonesimulator -DCMAKE_OSX_ARCHITECTURES=x86_64
+    ```
 
 
 - for tvOS-Simulator, using the latest, installed SDK:
 - for tvOS-Simulator, using the latest, installed SDK:
 
 
-    `cmake ~/sdl -DCMAKE_SYSTEM_NAME=tvOS -DCMAKE_OSX_SYSROOT=appletvsimulator -DCMAKE_OSX_ARCHITECTURES=x86_64`
+    ```cmake
+    cmake ~/sdl -DCMAKE_SYSTEM_NAME=tvOS -DCMAKE_OSX_SYSROOT=appletvsimulator -DCMAKE_OSX_ARCHITECTURES=x86_64
+    ```
 
 
 - for tvOS-Device, using the latest, installed SDK:
 - for tvOS-Device, using the latest, installed SDK:
 
 
-    `cmake ~/sdl -DCMAKE_SYSTEM_NAME=tvOS -DCMAKE_OSX_SYSROOT=appletvos -DCMAKE_OSX_ARCHITECTURES=arm64`
+    ```cmake
+    cmake ~/sdl -DCMAKE_SYSTEM_NAME=tvOS -DCMAKE_OSX_SYSROOT=appletvos -DCMAKE_OSX_ARCHITECTURES=arm64`
+    ```
+
+
+[^SDL_TARGET_EXCEPTION]: `SDL2::SDL2` can be an ALIAS to a static `SDL2::SDL2-static` target for multiple reasons.

+ 1 - 11
sdl2-config.cmake.in

@@ -14,18 +14,8 @@ macro(set_and_check _var _file)
     endif()
     endif()
 endmacro()
 endmacro()
 
 
-# Copied from `configure_package_config_file`
-macro(check_required_components _NAME)
-    foreach(comp ${${_NAME}_FIND_COMPONENTS})
-        if(NOT ${_NAME}_${comp}_FOUND)
-            if(${_NAME}_FIND_REQUIRED_${comp})
-                set(${_NAME}_FOUND FALSE)
-            endif()
-        endif()
-    endforeach()
-endmacro()
-
 get_filename_component(prefix "${CMAKE_CURRENT_LIST_DIR}/@cmake_prefix_relpath@" ABSOLUTE)
 get_filename_component(prefix "${CMAKE_CURRENT_LIST_DIR}/@cmake_prefix_relpath@" ABSOLUTE)
+
 set(exec_prefix "@exec_prefix@")
 set(exec_prefix "@exec_prefix@")
 set(bindir "@bindir@")
 set(bindir "@bindir@")
 set(libdir "@libdir@")
 set(libdir "@libdir@")