From 191b9d5021a1d44e2a233fe1e4df89340fa65a4c Mon Sep 17 00:00:00 2001
From: Sam Lantinga <slouken@libsdl.org>
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 000000000..074f61fe9
--- /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 000000000..1962dd80d
--- /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;
+}
+