SDL: Added MinGW Intro readme, touched up CMake and Visual Studio readmes. (#12485) (03a4e)

SDLPushPostBot · March 7, 2025, 12:26am

From 03a4eea0efc19e23fa152025be9ffb940248e6f0 Mon Sep 17 00:00:00 2001
From: "Joshua T. Fisher" <[EMAIL REDACTED]>
Date: Thu, 6 Mar 2025 16:24:16 -0800
Subject: [PATCH] Added MinGW Intro readme, touched up CMake and Visual Studio
 readmes. (#12485)

(cherry picked from commit 04b4577b58b4fdd5966caf6b01446cc16b0f83ab)
---
 docs/INTRO-cmake.md        | 23 +++++----
 docs/INTRO-mingw.md        | 95 ++++++++++++++++++++++++++++++++++++++
 docs/INTRO-visualstudio.md |  8 ++--
 3 files changed, 115 insertions(+), 11 deletions(-)
 create mode 100644 docs/INTRO-mingw.md

diff --git a/docs/INTRO-cmake.md b/docs/INTRO-cmake.md
index e6ccace390d84..05990e4c561cf 100644
--- a/docs/INTRO-cmake.md
+++ b/docs/INTRO-cmake.md
@@ -5,7 +5,12 @@ The easiest way to use SDL is to include it as a subproject in your project.
 
 We'll start by creating a simple project to build and run [hello.c](hello.c)
 
-Create the file CMakeLists.txt
+# Get a copy of the SDL source:
+```sh
+git clone https://github.com/libsdl-org/SDL.git vendored/SDL
+```
+
+# Create the file CMakeLists.txt
 ```cmake
 cmake_minimum_required(VERSION 3.16)
 project(hello)
@@ -25,21 +30,23 @@ add_executable(hello WIN32 hello.c)
 target_link_libraries(hello PRIVATE SDL3::SDL3)

-Build:
+# Configure and Build:

cmake -S . -B build
cmake --build build

-Run:
– On Windows the executable is in the build Debug directory:
+# Run:
+The executable should be in the build directory:
+

-cd build/Debug
+cd build
./hello
-``` 
-- On other platforms the executable is in the build directory:
+```
+
+If there wasn't an executable there despite the above Build section running successfully, it's likely because you're following this guide using the Visual Studio toolchain, it should instead be in the `build/Debug` directory:
```sh
-cd build
+cd build/Debug
./hello

diff --git a/docs/INTRO-mingw.md b/docs/INTRO-mingw.md
new file mode 100644
index 0000000000000…27cd2c9d2ed3f
— /dev/null
+++ b/docs/INTRO-mingw.md
@@ -0,0 +1,95 @@
+# Introduction to SDL with MinGW
+
+Without getting deep into the history, MinGW is a long running project that aims to bring gcc to Windows. That said, there’s many distributions, versions, and forks floating around. We recommend installing MSYS2, as it’s the easiest way to get a modern toolchain with a package manager to help with dependency management. This would allow you to follow the MSYS2 section below.
+
+Otherwise you’ll want to follow the “Other Distributions” section below.
+
+We’ll start by creating a simple project to build and run hello.c.
+
+# MSYS2
+
+Open the MSYS2 UCRT64 prompt and then ensure you’ve installed the following packages. This will get you working toolchain, CMake, Ninja, and of course SDL3.
+
+sh +pacman -S mingw-w64-ucrt-x86_64-gcc mingw-w64-ucrt-x86_64-ninja mingw-w64-ucrt-x86_64-cmake mingw-w64-ucrt-x86_64-sdl3 +
+
+## Create the file CMakeLists.txt
+```cmake
+project(sdl_test C CXX)
+cmake_minimum_required(VERSION 3.26)
+
+find_package(SDL3 REQUIRED)
+
+add_executable(sdl_test)
+
+target_sources(sdl_test
+PRIVATE

hello.c
+)

+target_link_libraries(sdl_test SDL3::SDL3)
+ + +## Configure and Build: +sh
+cmake -S . -B build
+cmake --build build
+ + +## Run: + +The executable is in the `build` directory: +sh
+cd build
+./hello
+ + +# Other Distributions + +Things can get quite complicated with other distributions of MinGW. If you can't follow [the cmake intro](INTRO-cmake.md), perhaps due to issues getting cmake to understand your toolchain, this section should work. + +## Acquire SDL + +Download the `SDL3-devel-<version>-mingw.zip` asset from [the latest release.](https://github.com/libsdl-org/SDL/releases/latest) Then extract it inside your project folder such that the output of `ls SDL3-<version>` looks like `INSTALL.md LICENSE.txt Makefile README.md cmake i686-w64-mingw32 x86_64-w64-mingw32`. + +## Know your Target Architecture + +It is not uncommon for folks to not realize their distribution is targeting 32bit Windows despite things like the name of the toolchain, or the fact that they're running on a 64bit system. We'll ensure we know up front what we need: + +Create a file named `arch.c` with the following contents: +c
+#include <stddef.h>
+#include <stdio.h>
+int main() {

#if defined(x86_64) || defined(_M_X64) || defined(i386) || defined(i386) || defined(__i386) || defined(_M_IX86)
```
   size_t ptr_size = sizeof(int*);
```

   if (4 == ptr_size) puts("i686-w64-mingw32");

   else if (8 == ptr_size) puts("x86_64-w64-mingw32");

```
   else puts("Unknown Architecture");
```
#else
```
   puts("Unknown Architecture");
```
#endif
return 0;
+}
+```

+Then run
+
+sh +gcc arch.c +./a.exe +
+
+This should print out which library directory we’ll need to use when compiling, keep this value in mind, you’ll need to use it when compiling in the next section as <arch>. If you get “Unknown Architecture” please report a bug.
+
+
+## Build and Run
+
+Now we should have everything needed to compile and run our program. You’ll need to ensure to replace <version> with the version of the release of SDL3 you downloaded, as well as use the <arch> we learned in the previous section.
+
+sh +gcc hello.c -o hello.exe -I SDL3-<version>/<arch>/include -L SDL3-<version>/<arch>/lib -lSDL3 -mwindows +cp SDL3-<version>/<arch>/bin/SDL3.dll SDL3.dll +./hello.exe +
diff --git a/docs/INTRO-visualstudio.md b/docs/INTRO-visualstudio.md
index 2cc6100cb8b5a…4017f79eebd02 100644
— a/docs/INTRO-visualstudio.md
+++ b/docs/INTRO-visualstudio.md
@@ -5,10 +5,12 @@ The easiest way to use SDL is to include it as a subproject in your project.

We’ll start by creating a simple project to build and run hello.c

± Get a copy of the SDL source, you can clone the repo, or download the “Source Code” asset from the latest release.

- If you’ve downloaded a release, make sure to extract the contents somewhere you can find it.

Create a new project in Visual Studio, using the C++ Empty Project template
Add hello.c to the Source Files
– Right click the solution, select add an existing project, navigate to VisualC/SDL and add SDL.vcxproj
– Select your main project and go to Project → Add Reference and select SDL3
– Select your main project and go to Project → Properties, set the filter at the top to “All Configurations” and “All Platforms”, select VC++ Directories and add the SDL include directory to “Include Directories”
± Right click the solution, select add an existing project, navigate to VisualC/SDL from within the source you cloned or downloaded above and add SDL.vcxproj
± Select your main project and go to Project → Add → Reference and select SDL3
± Select your main project and go to Project → Properties, set the filter at the top to “All Configurations” and “All Platforms”, select C/C++ → General and add the SDL include directory to “Additional Include Directories”
Build and run!