diff --git a/docs/INTRO-cmake.md b/docs/INTRO-cmake.md index e6ccace39..05990e4c5 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,24 +30,26 @@ add_executable(hello WIN32 hello.c) target_link_libraries(hello PRIVATE SDL3::SDL3) ``` -Build: +# Configure and Build: ```sh cmake -S . -B build cmake --build build ``` -Run: -- On Windows the executable is in the build Debug directory: -```sh -cd build/Debug -./hello -``` -- On other platforms the executable is in the build directory: +# Run: +The executable should be in the `build` directory: + ```sh cd build ./hello ``` +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/Debug +./hello +``` + A more complete example is available at: https://github.com/Ravbug/sdl3-sample diff --git a/docs/INTRO-mingw.md b/docs/INTRO-mingw.md new file mode 100644 index 000000000..27cd2c9d2 --- /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](https://www.msys2.org/), 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](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--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-` 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 +#include +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 ``. If you get "Unknown Architecture" please [report a bug](https://github.com/libsdl-org/SDL/issues). + + +## Build and Run + +Now we should have everything needed to compile and run our program. You'll need to ensure to replace `` with the version of the release of SDL3 you downloaded, as well as use the `` we learned in the previous section. + +```sh +gcc hello.c -o hello.exe -I SDL3-//include -L SDL3-//lib -lSDL3 -mwindows +cp SDL3-//bin/SDL3.dll SDL3.dll +./hello.exe +``` diff --git a/docs/INTRO-visualstudio.md b/docs/INTRO-visualstudio.md index 2cc6100cb..4017f79ee 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](hello.c) +- Get a copy of the SDL source, you can clone the repo, or download the "Source Code" asset from [the latest release.](https://github.com/libsdl-org/SDL/releases/latest) + - 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!