From a5545aab363af4be381b3301b50000b4c968532f Mon Sep 17 00:00:00 2001
From: Sam Lantinga <[EMAIL REDACTED]>
Date: Fri, 15 May 2026 09:35:19 -0700
Subject: [PATCH] Added initial documentation
---
docs/INTRO-cmake.md | 47 ++++++++++++++++++
docs/INTRO-visualstudio.md | 17 +++++++
docs/INTRO-xcode.md | 16 +++++++
docs/README-migration.md | 6 +++
docs/README-versions.md | 48 +++++++++++++++++++
docs/hello.c | 51 ++++++++++++++++++++
docs/release_checklist.md | 97 ++++++++++++++++++++++++++++++++++++++
7 files changed, 282 insertions(+)
create mode 100644 docs/INTRO-cmake.md
create mode 100644 docs/INTRO-visualstudio.md
create mode 100644 docs/INTRO-xcode.md
create mode 100644 docs/README-migration.md
create mode 100644 docs/README-versions.md
create mode 100644 docs/hello.c
create mode 100644 docs/release_checklist.md
diff --git a/docs/INTRO-cmake.md b/docs/INTRO-cmake.md
new file mode 100644
index 0000000..51b8940
--- /dev/null
+++ b/docs/INTRO-cmake.md
@@ -0,0 +1,47 @@
+
+# Introduction to SDL_net with CMake
+
+The easiest way to use SDL_net is to include it along with SDL as subprojects 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)
+
+# This assumes the SDL_net source is available in vendored/SDL_net
+add_subdirectory(vendored/SDL_net 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_net::SDL3_net SDL3::SDL3)
+```
+
+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:
+```sh
+cd build
+./hello
+```
diff --git a/docs/INTRO-visualstudio.md b/docs/INTRO-visualstudio.md
new file mode 100644
index 0000000..af6389b
--- /dev/null
+++ b/docs/INTRO-visualstudio.md
@@ -0,0 +1,17 @@
+
+# Introduction to SDL_net with Visual Studio
+
+The easiest way to use SDL_net is to include it along with SDL as subprojects in your project.
+
+We'll start by creating a simple project to build and run [hello.c](hello.c)
+
+- 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 the SDL VisualC/SDL directory and add SDL.vcxproj
+- Right click the solution, select add an existing project, navigate to the SDL_net VisualC directory and add SDL_net.vcxproj
+- Select your SDL_net project and go to Project -> Add Reference and select SDL3
+- Select your SDL_net project and go to Project -> Properties, set the filter at the top to "All Configurations" and "All Platforms", select VC++ Directories and modify the default SDL path in "Include Directories" to point to your SDL include directories
+- Select your main project and go to Project -> Add Reference and select SDL3 and SDL3_net
+- 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 and SDL_net include directories to "Include Directories"
+- Build and run!
+
diff --git a/docs/INTRO-xcode.md b/docs/INTRO-xcode.md
new file mode 100644
index 0000000..c120d91
--- /dev/null
+++ b/docs/INTRO-xcode.md
@@ -0,0 +1,16 @@
+
+# Introduction to SDL_net with Xcode
+
+The easiest way to use SDL_net is to include it along with SDL as subprojects in your project.
+
+We'll start by creating a simple project to build and run [hello.c](hello.c)
+
+- Create a new project in Xcode, using the App template and selecting Objective C as the language
+- Remove the .h and .m files that were automatically added to the project
+- Remove the main storyboard that was automatically added to the project
+- On iOS projects, select the project, select the main target, select the Info tab, look for "Custom iOS Target Properties", and remove "Main storyboard base file name" and "Application Scene Manifest"
+- Right click the project and select "Add Files to [project]", navigate to the SDL_net docs directory and add the file hello.c
+- Right click the project and select "Add Files to [project]", navigate to the SDL Xcode/SDL directory and add SDL.xcodeproj
+- Right click the project and select "Add Files to [project]", navigate to the SDL_net Xcode directory and add SDL_net.xcodeproj
+- Select the project, select the main target, select the General tab, look for "Frameworks, Libaries, and Embedded Content", and add SDL3.framework and SDL3_net.framework
+- Build and run!
diff --git a/docs/README-migration.md b/docs/README-migration.md
new file mode 100644
index 0000000..00245c5
--- /dev/null
+++ b/docs/README-migration.md
@@ -0,0 +1,6 @@
+
+# Migrating to SDL_net 3.0
+
+This guide provides useful information for migrating applications from SDL_net 2.0 to SDL_net 3.0.
+
+SDLNet_GetError() has been replaced with SDL_GetError().
diff --git a/docs/README-versions.md b/docs/README-versions.md
new file mode 100644
index 0000000..6c2d920
--- /dev/null
+++ b/docs/README-versions.md
@@ -0,0 +1,48 @@
+# Versioning
+
+## Since 3.2.0
+
+SDL follows an "odd/even" versioning policy, similar to GLib, GTK, Flatpak
+and older versions of the Linux kernel:
+
+* If the minor version (second part) and the patch version (third part) is
+ divisible by 2 (for example 3.2.6, 3.4.0), this indicates a version of
+ SDL that is believed to be stable and suitable for production use.
+
+ * In stable releases, the patchlevel or micro version (third part)
+ indicates bugfix releases. Bugfix releases may add small changes
+ to the ABI, so newer patch versions are backwards-compatible but
+ not fully forwards-compatible. For example, programs built against
+ SDL 3.2.0 should work fine with SDL 3.2.8, but programs built against
+ SDL 3.2.8 may not work with 3.2.0.
+
+ * The minor version increases when significant changes are made that
+ require longer development or testing time, e.g. major new functionality,
+ or revamping support for a platform. Newer minor versions are
+ backwards-compatible, but not fully forwards-compatible. For example,
+ programs built against SDL 3.2.x should work fine with SDL 3.4.x,
+ but programs built against SDL 3.4.x may not work with 3.2.x.
+
+* If the minor version (second part) or patch version (third part) is not
+ divisible by 2 (for example 3.2.9, 3.3.x), this indicates a development
+ prerelease of SDL that is not suitable for stable software distributions.
+ Use with caution.
+
+ * The patchlevel or micro version (third part) increases with each prerelease.
+
+ * Prereleases are backwards-compatible with older stable branches.
+ For example, programs built against SDL 3.2.x should work fine with
+ SDL 3.3.x, but programs built against SDL 3.3.x may not work with 3.2.x.
+
+ * Prereleases are not guaranteed to be backwards-compatible with each other.
+ For example, new API or ABI added in 3.3.0 might be removed or changed in
+ 3.3.1. If this would be a problem for you, please do not use prereleases.
+
+ * Only use a prerelease if you can guarantee that you will promptly upgrade
+ to the stable release that follows it. For example, do not use 3.3.x
+ unless you will be able to upgrade to 3.4.0 when it becomes available.
+
+ * Software distributions that have a freeze policy (in particular Linux
+ distributions with a release cycle, such as Debian and Fedora)
+ should only package stable releases, and not prereleases.
+
diff --git a/docs/hello.c b/docs/hello.c
new file mode 100644
index 0000000..f842d0c
--- /dev/null
+++ b/docs/hello.c
@@ -0,0 +1,51 @@
+/*
+ Copyright (C) 1997-2026 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.
+*/
+#define SDL_MAIN_USE_CALLBACKS 1 /* use the callbacks instead of main() */
+#include <SDL3/SDL.h>
+#include <SDL3/SDL_main.h>
+#include <SDL3_net/SDL_net.h>
+
+static SDL_Window *window = NULL;
+static SDL_Renderer *renderer = NULL;
+
+/* This function runs once at startup. */
+SDL_AppResult SDL_AppInit(void **appstate, int argc, char *argv[])
+{
+ /* Create the window */
+ if (!SDL_CreateWindowAndRenderer("Hello World", 800, 600, SDL_WINDOW_FULLSCREEN, &window, &renderer)) {
+ SDL_Log("Couldn't create window and renderer: %s\n", SDL_GetError());
+ return SDL_APP_FAILURE;
+ }
+
+ return SDL_APP_CONTINUE;
+}
+
+/* This function runs when a new event (mouse input, keypresses, etc) occurs. */
+SDL_AppResult SDL_AppEvent(void *appstate, SDL_Event *event)
+{
+ if (event->type == SDL_EVENT_KEY_DOWN ||
+ event->type == SDL_EVENT_QUIT) {
+ return SDL_APP_SUCCESS; /* end the program, reporting success to the OS. */
+ }
+ return SDL_APP_CONTINUE;
+}
+
+/* This function runs once per frame, and is the heart of the program. */
+SDL_AppResult SDL_AppIterate(void *appstate)
+{
+ return SDL_APP_CONTINUE;
+}
+
+/* This function runs once at shutdown. */
+void SDL_AppQuit(void *appstate, SDL_AppResult result)
+{
+}
diff --git a/docs/release_checklist.md b/docs/release_checklist.md
new file mode 100644
index 0000000..fc8c932
--- /dev/null
+++ b/docs/release_checklist.md
@@ -0,0 +1,97 @@
+# Release checklist
+
+* Run `build-scripts/create-release.py -R libsdl-org/SDL_net --ref <branch>` to do
+ a dry run creating the release assets. Verify that the archives are correct.
+
+* Tag the release, e.g. `git tag release-3.8.0; git push --tags`
+
+* Run `build-scripts/create-release.py -R libsdl-org/SDL_net --ref <release-tag>`
+ to have GitHub Actions create release assets. This makes sure the revision
+ string baked into the archives is correct.
+
+## New feature release
+
+* Update `CHANGES.txt`
+
+* Bump version number to 3.EVEN.0 in all these locations:
+
+ * `include/SDL3_net/SDL_net.h`:
+ `SDL_IMAGE_MAJOR_VERSION`, `SDL_IMAGE_MINOR_VERSION`, `SDL_IMAGE_MICRO_VERSION`
+ * `CMakeLists.txt`:
+ `MAJOR_VERSION`, `MINOR_VERSION`, `MICRO_VERSION`
+ * `src/version.rc`:
+ `FILEVERSION`, `PRODUCTVERSION`, `FileVersion`, `ProductVersion`
+ * `VisualC/Version.rc`:
+ `FILEVERSION`, `PRODUCTVERSION`, `FileVersion`, `ProductVersion`
+ * `Xcode/Info-Framework.plist`:
+ `CFBundleShortVersionString`, `CFBundleVersion`
+
+* Bump ABI version information
+
+ * `Xcode/SDL_net.xcodeproj/project.pbxproj`:
+ `DYLIB_CURRENT_VERSION`, `DYLIB_COMPATIBILITY_VERSION`
+ * set first number in `DYLIB_CURRENT_VERSION` to
+ (100 * *minor*) + 1
+ * set second number in `DYLIB_CURRENT_VERSION` to 0
+ * set `DYLIB_COMPATIBILITY_VERSION` to the same value
+
+* Run `./build-scripts/test-versioning.sh` to verify that everything is consistent
+
+* Do the release
+
+## New bugfix release
+
+* Check that no new API/ABI was added
+
+ * If it was, do a new feature release (see above) instead
+
+* Bump version number from 3.Y.Z to 3.Y.(Z+1) (Y is even)
+
+ * Same places as listed above
+
+* Bump ABI version information
+
+ * `Xcode/SDL_net.xcodeproj/project.pbxproj`:
+ `DYLIB_CURRENT_VERSION`, `DYLIB_COMPATIBILITY_VERSION`
+ * set second number in `DYLIB_CURRENT_VERSION` to *patchlevel*
+ * Leave `DYLIB_COMPATIBILITY_VERSION` unchanged
+
+* Run `./build-scripts/test-versioning.sh` to verify that everything is consistent
+
+* Do the release
+
+## After a feature release
+
+* Create a branch like `release-3.6.x`
+
+* Bump version number to 3.ODD.0 for next development branch
+
+ * Same places as listed above
+
+* Bump ABI version information
+
+ * Same places as listed above
+ * Assume that the next feature release will contain new API/ABI
+
+* Run `./build-scripts/test-versioning.sh` to verify that everything is consistent
+
+* Add a new milestone for issues
+
+## New development prerelease
+
+* Bump version number from 3.Y.Z to 3.Y.(Z+1) (Y is odd)
+
+ * Same places as listed above
+
+* Bump ABI version information
+
+ * `Xcode/SDL_net.xcodeproj/project.pbxproj`:
+ `DYLIB_CURRENT_VERSION`, `DYLIB_COMPATIBILITY_VERSION`
+ * set first number in `DYLIB_CURRENT_VERSION` to
+ (100 * *minor*) + *patchlevel* + 1
+ * set second number in `DYLIB_CURRENT_VERSION` to 0
+ * set `DYLIB_COMPATIBILITY_VERSION` to the same value
+
+* Run `./build-scripts/test-versioning.sh` to verify that everything is consistent
+
+* Do the release