From 191b9d5021a1d44e2a233fe1e4df89340fa65a4c Mon Sep 17 00:00:00 2001
From: Sam Lantinga <[EMAIL REDACTED]>
Date: Mon, 13 Jan 2025 12:15:33 -0800
Subject: [PATCH] Added INTRO-cmake.md
---
docs/INTRO-cmake.md | 48 +++++++++++++++++++++++++++++++++++++
docs/hello.c | 58 +++++++++++++++++++++++++++++++++++++++++++++
2 files changed, 106 insertions(+)
create mode 100644 docs/INTRO-cmake.md
create mode 100644 docs/hello.c
diff --git a/docs/INTRO-cmake.md b/docs/INTRO-cmake.md
new file mode 100644
index 0000000000000..074f61fe9d33e
--- /dev/null
+++ b/docs/INTRO-cmake.md
@@ -0,0 +1,48 @@
+
+# Introduction to SDL with CMake
+
+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
+```cmake
+cmake_minimum_required(VERSION 3.16)
+project(hello)
+
+# set the output directory for built objects.
+# This makes sure that the dynamic library goes into the build directory automatically.
+set(CMAKE_RUNTIME_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/$<CONFIGURATION>")
+set(CMAKE_LIBRARY_OUTPUT_DIRECTORY "${CMAKE_BINARY_DIR}/$<CONFIGURATION>")
+
+# This assumes the SDL source is available in vendored/SDL
+add_subdirectory(vendored/SDL EXCLUDE_FROM_ALL)
+
+# Create your game executable target as usual
+add_executable(hello WIN32 hello.c)
+
+# Link to the actual SDL3 library.
+target_link_libraries(hello PRIVATE SDL3::SDL3)
+```
+
+Build:
+```sh
+cmake .
+cmake --build .
+```
+
+Run:
+- On Windows the executable is in the Debug directory:
+```sh
+./Debug/hello
+```
+- On other platforms the executable is in the current directory:
+```sh
+./hello
+```
+
+A more complete example is available at:
+
+https://github.com/Ravbug/sdl3-sample
+
+Additional information and troubleshooting is available in [README-cmake.md](README-cmake.md)
diff --git a/docs/hello.c b/docs/hello.c
new file mode 100644
index 0000000000000..1962dd80d574e
--- /dev/null
+++ b/docs/hello.c
@@ -0,0 +1,58 @@
+/*
+ Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org>
+
+ This software is provided 'as-is', without any express or implied
+ warranty. In no event will the authors be held liable for any damages
+ arising from the use of this software.
+
+ Permission is granted to anyone to use this software for any purpose,
+ including commercial applications, and to alter it and redistribute it
+ freely.
+*/
+#include <SDL3/SDL.h>
+#include <SDL3/SDL_main.h>
+
+int main(int argc, char *argv[])
+{
+ SDL_Window *window = NULL;
+ SDL_Renderer *renderer = NULL;
+ const char *message = "Hello World!";
+ int w = 0, h = 0;
+ float x, y;
+ bool done = false;
+
+ /* Create the window */
+ if (!SDL_CreateWindowAndRenderer("Hello World", 0, 0, SDL_WINDOW_FULLSCREEN, &window, &renderer)) {
+ SDL_Log("Couldn't create window and renderer: %s\n", SDL_GetError());
+ return 1;
+ }
+
+ while (!done) {
+ SDL_Event event;
+
+ /* Handle events */
+ while (SDL_PollEvent(&event)) {
+ if (event.type == SDL_EVENT_KEY_DOWN ||
+ event.type == SDL_EVENT_MOUSE_BUTTON_DOWN ||
+ event.type == SDL_EVENT_QUIT) {
+ done = true;
+ }
+ }
+
+ /* Center the message */
+ SDL_GetWindowSize(window, &w, &h);
+ x = (float)(w - SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE * SDL_strlen(message)) / 2;
+ y = (float)(h - SDL_DEBUG_TEXT_FONT_CHARACTER_SIZE) / 2;
+
+ /* Draw the message */
+ SDL_SetRenderDrawColor(renderer, 0, 0, 0, 255);
+ SDL_RenderClear(renderer);
+ SDL_SetRenderDrawColor(renderer, 255, 255, 255, 255);
+ SDL_RenderDebugText(renderer, x, y, message);
+ SDL_RenderPresent(renderer);
+ }
+ SDL_Quit();
+
+ return 0;
+}
+