# sokol: Single-File C Headers for Cross-Platform Graphics and App Lifecycle

> sokol is a collection of STB-style single-file C headers by Andre Weissflog, covering 3D graphics, audio, app lifecycle, and input across Windows, macOS, Linux, iOS, Android, and WebAssembly. Each header handles one concern, and you compose them yourself.

**floooh/sokol** — minimal cross-platform standalone C headers

- Repository: https://github.com/floooh/sokol
- Website: https://floooh.github.io/sokol-html5
- Stars: 10,325 · Forks: 671
- Language: C
- License: Zlib
- Published: 2026-09-21 · Updated: 2026-09-21 · Language: en
- Canonical page: https://hysenlabs.com/projects/floooh-sokol

## What sokol Replaces and Who Reaches for It

sokol targets C and C++ developers who need to ship a native or web-capable application without committing to a large, opinionated framework. The typical user is writing a small game, a graphics demo, a tool with a custom UI, or an emulator where every kilobyte of binary size and every layer of indirection matters. The README describes the project as STB-style cross-platform libraries, which names a specific design contract: each header is self-contained, requires no companion library to link against, and activates its implementation only in the translation unit where you define a preprocessor macro before the include. This pattern comes from the stb library collection by Sean Barrett, which showed that single-header C libraries can cover complex domains without a build system or package manager.

Unlike a game engine, sokol makes no decisions about scene graphs, asset formats, or physics. It provides the platform layer: get a window, receive input, draw into a GPU context, play audio, fetch bytes, measure time. What you put into those primitives is entirely your concern. This makes sokol suitable for engineers who already have a rendering pipeline or want to build one from scratch, and unsuitable for anyone expecting a ready-made rendering architecture.

The README lists several finished products built with sokol, including Solar Storm (a turn-based strategy game built with Odin and sokol, released on Steam) and Spanking Runners (an arcade racing game). These demonstrate the library's fitness for shipped software but do not explain how those projects structured their rendering layers or managed assets.

## The Seven Core Headers and What Each One Owns

sokol divides platform concerns across seven core headers, each independently usable.

sokol_gfx.h is the 3D graphics API wrapper. The README states it targets GL/GLES3/WebGL2, Metal, D3D11, and WebGPU, selecting the backend at compile time through a preprocessor define. It does not expose the underlying API directly: you work with sokol_gfx.h's own resource types (pipelines, buffers, images, passes) and the header translates calls to the active backend. This means you write rendering code once and get a Metal path and a WebGL2 path without scattering conditional compilation through your own source.

sokol_app.h handles the application entry point, window creation, 3D context setup, and input events across platforms. On each platform it maps to the native event model: the Win32 message pump on Windows, the Cocoa run loop on macOS, X11 events on Linux, and the Emscripten main loop for WebAssembly. You supply callbacks for init, frame, and cleanup; the library calls them on the correct thread for the platform.

sokol_audio.h is a minimal audio playback header for streaming short buffers of PCM audio. It does not include a mixer or audio graph. sokol_fetch.h handles asynchronous loading from HTTP or the local filesystem, which is especially important for WebAssembly targets where synchronous file access is not available. sokol_time.h wraps the platform's high-resolution timer into a single consistent API. sokol_args.h parses command-line arguments on native targets and URL query parameters on the web, so the same argument-reading code works in both contexts without conditional compilation. sokol_log.h provides a standard logging callback that the other headers use for diagnostic output; you can replace it with your own handler if the default output does not fit your application's logging infrastructure.

## Integrating sokol: The STB Pattern in Practice

Because each header contains both declarations and implementation, integration requires no separate build step beyond including the file. You copy the header into your project's include path or vendor directory, include it in header form in any translation unit that needs the API, and include it once with the implementation macro defined in a dedicated C or C++ source file. The exact macro name depends on the header and backend: for sokol_gfx.h targeting Metal, you define SOKOL_METAL before the include in the implementation file; for D3D11 you would define SOKOL_D3D11 instead. The header then compiles the backend-specific code only in that one translation unit.

The repository also includes a fips.yml file, indicating official support for the fips CMake-based build tool. Engineers not using fips need to link against the system libraries the chosen backend requires: the Metal framework on macOS, d3d11.lib on Windows targeting Direct3D 11, and OpenGL libraries on Linux. The README points to the sokol-samples repository and its section on building without a build system for platform-specific linking guidance.

The repository's assets/ and shdgen/ directories, along with a command-line shader compiler available through the sokol-tools project linked in the README, are relevant if you want to write GLSL shaders that compile to each backend's native shader language. Using sokol-tools is optional but practical for projects that need to share one GLSL source across all backends rather than maintaining separate shader strings per API.

The website at floooh.github.io/sokol-html5 hosts live WebAssembly samples built from the sokol-samples repository. Browsing those samples before starting a project shows concretely what sokol_gfx.h produces in the browser for a triangle, a textured quad, or an offscreen render pass.

## What sokol Will Not Do for You

sokol deliberately excludes several categories of functionality that a larger framework would include. The library has no built-in asset loading beyond raw byte streaming: sokol_fetch.h gives you bytes from a URL or file path; decoding those bytes into an image, a mesh, or an audio file is your responsibility. There is no geometry instancing API at the sokol_gfx.h abstraction level beyond what the underlying GPU draw calls expose through instance counts.

The audio layer is minimal by design. sokol_audio.h handles PCM buffer streaming; there is no pitch control, no reverb, no mixing of multiple audio sources, and no format decoding. An application that needs to play several audio sources simultaneously must implement its own mixer before passing mixed PCM to sokol_audio.h.

sokol_app.h handles window creation and basic keyboard, mouse, and touch input, but the README does not document a gamepad or joystick API. Multi-window support and any docking or tiling window management are outside the library's scope.

The library has no networking primitives. sokol_fetch.h can retrieve data from HTTP URLs on supported platforms, but it is not a general networking library. TCP connections, WebSocket support, and anything beyond file-like retrieval are absent. sokol also provides no threading primitives; if your application needs worker threads, you must bring your own synchronization layer.

## Companion Utilities and the External Ecosystem

The util/ directory in the repository contains optional integration headers that connect sokol_gfx.h to third-party libraries. sokol_imgui.h is a sokol_gfx.h rendering backend for Dear ImGui, a widely used C++ immediate-mode GUI library. sokol_nuklear.h provides the same for Nuklear. sokol_gl.h implements an OpenGL 1.x-style immediate-mode rendering API on top of sokol_gfx.h, useful for 2D drawing without switching APIs. sokol_debugtext.h renders text using built-in vintage home computer fonts, intended for debug overlays. sokol_shape.h generates simple geometric shapes (box, sphere, cylinder, torus) as vertex and index data compatible with sokol_gfx.h buffers. sokol_color.h provides X11-style named color constants.

These utility headers are additional includes, not separate build targets. Each one depends on sokol_gfx.h and on the external library it integrates with, if any. sokol_imgui.h requires Dear ImGui to be compiled separately; the README does not specify which version of Dear ImGui the utility header currently targets.

Beyond the repository itself, the README lists several third-party extensions. sokol_gp.h (from a separate repository) is a 2D shape drawing library built on top of sokol_gfx.h. A NanoVG backend for sokol_gfx.h is also listed. These are community projects, not maintained in the sokol repository.

## sokol vs SDL: Different Scopes, Different Integration Models

SDL (Simple DirectMedia Layer) is the most common alternative for the same class of cross-platform C problems. SDL ships as a compiled shared or static library with a C API that covers 2D rendering, audio mixing, input, joystick, networking, threading, and more. You link against libSDL2 as an external binary dependency.

sokol works differently. There is no precompiled binary to link against beyond the system frameworks the backend requires. Each header compiles directly into your application. The surface area per header is smaller than SDL's equivalent subsystem: sokol_gfx.h is a 3D-only API with no built-in 2D renderer (the sokol_gl.h utility header provides OpenGL 1.x-style immediate-mode 2D at the cost of a separate include), while SDL2's renderer handles 2D drawing as part of its core API.

If your target includes WebAssembly, sokol's compile-time backend selection makes the web path straightforward: the same source that produces a native binary also produces a WebAssembly module with WebGL2 when compiled through Emscripten. SDL2 also supports Emscripten, but the integration path differs. For projects that have no web target and need audio mixing, networking, or fuller input handling, SDL2's richer feature set may justify the added binary dependency. For projects that want the smallest possible footprint and full control over the rendering architecture, sokol's composition model is more direct.

## Maintenance Status and the Zlib Licence

The last push to the repository was on 2026-09-26. The CHANGELOG linked from the README recorded a change to mouse-locking behaviour on Linux on 14-Sep-2026. The repository has no GitHub releases; users follow the master branch and consult CHANGELOG.md for breaking changes and new features.

The Zlib licence permits use in commercial products without requiring disclosure of source changes. It asks that the original copyright notice be preserved and that the library is not misrepresented as your own work. There are no copyleft conditions. The licence terms are permissive enough for both commercial game releases and open-source tools.

The README also includes a CONTRIBUTING.md file for those who want to report issues or propose changes. The AGENTS.md and CLAUDE.md files at the repository root suggest the project uses automated tooling for some maintenance tasks. The README does not document a formal versioning scheme or a compatibility policy for the C API across versions, which means consumers who need API stability should pin to a specific commit rather than tracking master blindly.

## Conclusion

Engineers writing cross-platform C or C++ applications for native and WebAssembly targets, who want platform abstractions without framework lock-in, will find sokol's single-header approach practical. It is the wrong choice for anyone expecting built-in audio mixing, a 2D renderer beyond immediate mode, asset format decoding, or networking. Before adopting it, verify which graphics backend your target platform requires and confirm that the sokol-tools shader compiler is compatible with your build system, since cross-backend shader management is not solved by the headers alone.

## FAQ

### What is the sokol library?

sokol is a collection of STB-style single-file C headers for cross-platform development. It covers 3D graphics (sokol_gfx.h), application lifecycle and input (sokol_app.h), audio (sokol_audio.h), asynchronous file and HTTP fetching (sokol_fetch.h), time measurement, argument parsing, and logging. Each header works independently and activates its implementation through a preprocessor macro.

### How do you use sokol in a C project?

You copy the relevant header files into your project's include path and include them normally where you need the API. In exactly one C or C++ source file, you define the implementation macro for each header before including it (for example, SOKOL_GFX_IMPL for sokol_gfx.h). The README directs readers to the sokol-samples repository for build system integration examples.

### How does sokol compare to SDL?

SDL ships as a compiled library you link against and includes a 2D renderer, audio mixing, networking, and threading primitives. sokol is a set of single-file headers that compile directly into your application with no external binary dependency; it covers 3D graphics, basic audio streaming, and app lifecycle without a mixer or networking layer. SDL suits projects that need a fuller feature set out of the box; sokol suits projects that want a minimal platform layer with no framework overhead.

## Sources

- [floooh/sokol on GitHub](https://github.com/floooh/sokol)
- [Issues](https://github.com/floooh/sokol/issues)
- [License: Zlib](https://github.com/floooh/sokol/blob/master/LICENSE)
- [Project website](https://floooh.github.io/sokol-html5)
- [README](https://github.com/floooh/sokol/blob/master/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/floooh-sokol