SDL ported to the Zig build system

This is a port of SDL to the Zig build system, packaged for the Zig package manager. This repo was forked from Carl Åstholm's original SDL port. It adds support for cross-compiling to macOS, updates to the newest SDL3 version, and downloads the tarballs instead of forking the SDL repository.

Usage

Requires Zig 0.15.2 or 0.16.0-dev (master).

zig fetch --save git+https://codeberg.org/brodo/SDL.git

Then add the following to your build.zig:

```zig
const sdl_dep = b.dependency("sdl", .{
 .target = target,
 .optimize = optimize,
 //.preferred_linkage = .static,
 //.strip = null,
 //.sanitize_c = null,
 //.pic = null,
 //.lto = null,
 //.emscripten_pthreads = false,
});
const sdl_lib = sdl_dep.artifact("SDL3");
const sdl_test_lib = sdl_dep.artifact("SDL3_test");

Examples

Example projects using this SDL package:

• castholm/zig-examples/breakout
• castholm/zig-examples/snake
• castholm/zig-examples/opengl-hexagon

Supported targets

Legend:

• ✅ Supported
• 可 Supported, but requires external SDKs
• ❌ Not supported

Windows

Building for x86_64-windows-gnu from any host system works out of the box.

Building for msvc targets requires Microsoft Visual C++ and the Windows 11 SDK to be installed on the host Windows system.

aarch64 Windows support is experimental and not yet actively tested.

Linux

Building for x86_64-linux-gnu/musl from any host system works out of the box.

The SDL_linux_deps package provides supplementary headers and source files required for compiling for Linux.

aarch64 Linux support is experimental and not yet actively tested.

macOS

Cross-compiling for macOS from Windows or Linux host systems is prohibited by the Xcode and Apple SDKs Agreement. It is however theoretically possible with this package.

Emscripten (web)

Before you proceed, please understand that Emscripten is an advanced target and that building an SDL app for the Web requires significantly more effort compared to Windows, Linux or macOS:

• You will need to compile your app into an object file or a static library instead of an executable.
• If you use libc headers (e.g. by translating C code to Zig), you will need to add the include directory inside the Emscripten sysroot to your header search paths.
• To build the final HTML/JS/Wasm artifacts, you will need to invoke emcc using run steps.
• You will likely need to do a lot of your own research and try out different combinations of emcc options to get satisfactory results. Make sure you read the official Emscripten documentation as well as SDL's Emscripten README.

In addition, note that Emscripten 4.0.4 or later will provide its own official port of SDL3 if you pass -sUSE_SDL=3 to emcc. Depending on your use case you might not even need this package at all.

Refer to the example projects for examples on how to set up your build.zig for building for the Web.

Building for wasm32-emscripten requires an Emscripten development environment to be set up on the host system. It is strongly recommended that you use the Emscripten SDK for installing and managing Emscripten.

When building for Emscripten, you need to provide a path to the Emscripten sysroot via --sysroot:

zig build -Dtarget=wasm32-emscripten --sysroot "$(em-config CACHE)/sysroot"

Depending on the state of your Emscripten cache, you might need to run embuilder build sysroot to ensure that the Emscripten sysroot is built before you run zig build.

To build with pthreads support, specify .emscripten_pthreads = true.

License

REUSE status

This repository is REUSE-compliant. The effective SPDX license expression for the repository as a whole is:

(BSD-3-Clause OR GPL-3.0 OR HIDAPI) AND Apache-2.0 AND BSD-3-Clause AND CC0-1.0 AND HIDAPI AND HPND-sell-variant AND MIT AND SunPro AND Unlicense AND Zlib

(This is identical to the upstream SDL repository, just expressed in more explicit terms.)

Copyright notices and license texts have been reproduced in LICENSE.txt, for your convenience.