SDL 3.0
|
The CMake build system is supported on the following platforms:
Assuming the source tree of SDL is located at ~/sdl
, this will configure and build SDL in the ~/build
directory:
Installation can be done using:
This will install SDL to /usr/local.
You can build the SDL test programs by adding -DSDL_TESTS=ON
to the first cmake command above:
and then building normally. In this example, the test programs will be built and can be run from ~/build/tests/
.
SDL can be included in your project in 2 major ways:
The following CMake script supports both, depending on the value of MYGAME_VENDORED
.
For CMake to find SDL, it must be installed in a default location CMake is looking for.
The following components are available, to be used as an argument of find_package
.
Component name | Description |
---|---|
SDL3-shared | The SDL3 shared library, available through the SDL3::SDL3-shared target |
SDL3-static | The SDL3 static library, available through the SDL3::SDL3-static target |
SDL3_test | The SDL3_test static library, available through the SDL3::SDL3_test target |
SDL3 | The SDL3 library, available through the SDL3::SDL3 target. This is an alias of SDL3::SDL3-shared or SDL3::SDL3-static . This component is always available. |
Headers | The SDL3 headers, available through the SDL3::Headers target. This component is always available. |
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.
By default, CMake provides 4 build types: Debug
, Release
, RelWithDebInfo
and MinSizeRel
. The main difference(s) between these are the optimization options and the generation of debug info. To configure SDL as an optimized Release
library, configure SDL with:
To build it, run:
By default, only a shared SDL library is built and installed. The options -DSDL_SHARED=
and -DSDL_STATIC=
accept boolean values to change this.
CMAKE_<LANG>_FLAGS
to pass extra flags to the compiler.CMAKE_EXE_LINKER_FLAGS
to pass extra option to the linker for executables.CMAKE_SHARED_LINKER_FLAGS
to pass extra options to the linker for shared libraries.build a SDL library optimized for (more) modern x64 microprocessor architectures.
With gcc or clang:
With Visual C:
CMake documentation for cross building for Apple: link
CMake 3.14+ natively includes support for iOS, tvOS and watchOS. visionOS requires CMake 3.28+. SDL binaries may be built using Xcode or Make, possibly among other build-systems.
When using a compatible version of CMake, it should be possible to:
Configure with -DSDL_FRAMEWORK=ON
to build a SDL framework instead of a dylib shared library. Only shared frameworks are supported, no static ones.
Use -DCMAKE_PLATFORM_NAME=<value>
to configure the platform. CMake can target only one platform at a time.
Apple platform | CMAKE_SYSTEM_NAME value |
---|---|
macOS (MacOS X) | Darwin |
iOS | iOS |
tvOS | tvOS |
visionOS | visionOS |
watchOS | watchOS |
A universal binaries, can be built by configuring CMake with -DCMAKE_OSX_ARCHITECTURES=<semicolon-separated list of CPU architectures>
.
For example -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64"
will build binaries that run on both Intel cpus and Apple silicon.
SDL supports following Apple architectures:
Platform | CMAKE_OSX_ARCHITECTURES value |
---|---|
64-bit ARM (Apple Silicon) | arm64 |
x86_64 | x86_64 |
32-bit ARM | armv7s |
CMake documentation: link
Use -DCMAKE_OSX_SYSROOT=<value>
to configure a different platform SDK. The value can be either the name of the SDK, or a full path to the sdk (e.g. /full/path/to/iPhoneOS.sdk
).
SDK | CMAKE_OSX_SYSROOT value |
---|---|
iphone | iphoneos |
iphonesimulator | iphonesimulator |
appleTV | appletvos |
appleTV simulator | appletvsimulator |
visionOS | xr |
visionOS simulator | xrsimulator |
watchOS | watchos |
watchOS simulator | watchsimulator |
Append with a version number to target a specific SDK revision: e.g. iphoneos12.4
, appletvos12.4
.
CMake documentation: link
for macOS, building a dylib and/or static library for x86_64 and arm64:
bash cmake ~/sdl -DSDL_FRAMEWORK=ON -DCMAKE_SYSTEM_NAME=Darwin -DCMAKE_OSX_ARCHITECTURES="x86_64;arm64"
for iOS-Simulator, using the latest, installed SDK:
for iOS-Device, using the latest, installed SDK, 64-bit only
for iOS-Device, using the latest, installed SDK, mixed 32/64 bit
for iOS-Device, using a specific SDK revision (iOS 12.4, in this example):
for iOS-Simulator, using the latest, installed SDK, and building SDL test apps (as .app bundles):
for tvOS-Simulator, using the latest, installed SDK:
for tvOS-Device, using the latest, installed SDK:
for QNX/aarch64, using the latest, installed SDK:
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_LIBRARY= | ON /OFF | Build SDL test library (libSDL3_test.a /SDL3_test.lib ) |
-DSDL_TESTS= | ON /OFF | Build SDL test programs (requires -DSDL_TEST_LIBRARY=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 |
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.