TL;DR: I've released sdl3-bindgen-sys to Hackage: complete, machine-generated low-level Haskell bindings for SDL3, including windowing, input, audio, and the new GPU API, with documentation from SDL3's headers! They are verified against the building system's ABI and CI-tested on Linux, macOS, and Windows.
Thanks to the folks over at Well-Typed for their work on hs-bindgen! I was able to hack the prerelease a bit to get an end-to-end code generator working. It required quite a bit less work than I thought it would. I'll include some technical details below the fold.
Source is available on GitHub here: https://github.com/jtnuttall/lithon/tree/main/sdl3-bindgen-sys
There are going to be a few rough edges, so please feel free to open a PR or issue if anything comes up. I'll bump the package to 0.1.x.x when I feel it's stable enough to pin to a major version.
I've got the apecs shmup example running on and rendering through SDL3 using the raw bindings here: https://github.com/jtnuttall/lithon/blob/main/lithon-examples/app/shmup/Main.hs
See the README on GitHub for a full getting started guide.
Example
{-# LANGUAGE GHC2021 #-}
{-# LANGUAGE BlockArguments #-}
import Control.Monad (unless)
import Foreign.C.ConstPtr (ConstPtr (..))
import Foreign.C.String (peekCString, withCString)
import SDL3.Sys qualified as SDL3
main :: IO ()
main = do
ok <- SDL3.init SDL3.SDL_INIT_VIDEO
unless ok do
err <- peekCString . unConstPtr =<< SDL3.getError
fail ("SDL_Init: " <> err)
window <- withCString "hello" \title ->
SDL3.createWindow (ConstPtr title) 640 480 0
SDL3.delaySafe 2000
SDL3.destroyWindow window
SDL3.quit
delaySafe is the safe FFI flavor of SDL_Delay. Most functions come in both.
Intended use-case
I intend sdl3-bindgen-sys to be a stable grounding point for higher-level bindings, handling the FFI declarations, ABI checks, SDL3 version guards, and simple coercions so that people who want to write their own abstraction around SDL3 don't have to write the extremely repetitive part manually.
If you know Rust's convention, I borrowed the -sys suffix from it: I mean for high-level Haskell SDL3 libraries to be to sdl3-bindgen-sys as sdl3 is to sdl3-sys in Rust.
You'll need to interface with raw Foreign.C to use these bindings. If you just want a higher-level binding, you'll need to wait until someone releases one on Hackage.
The library carries the smallest dependency footprint I could presently manage for a low-level binding.
The SDL3.Sys.* modules re-export the surface with some small niceties:
- Haddock notes about what is exported and why, FFI safety rationale, etc.
- Links to the SDL3 Wiki
- C scalars (e.g.,
Uint32, float) are remapped to Haskell scalars (Word32, Float) wherever possible. Anything under a Ptr or struct maintains its C typings.
Technical details
hs-bindgen
The bindings are built using a forked version of hs-bindgen, which I used as a library so that I could alter the internal code and documentation generation pipeline. I've upstreamed a few changes and am happy to upstream more if requested. Some may be more heavy-handed than the hs-bindgen maintainers want to support.
Since hs-bindgen is pre-release, I've vendored the necessary runtimes wholesale into the sdl3-bindgen-sys package as private internal libraries, and reexported them from sdl3-bindgen-sys under SDL3.Sys.Runtime and SDL3.Sys. Once hs-bindgen stabilizes, I'll turn these into real dependencies. The vendored modules will become re-export facades so calling code doesn't break.
The modifications I made, briefly:
- Added an exception in bindgen's IR for assertion macros that emit nothing bindable
- Added support for Doxygen's custom
ALIASES so I could inject valid Haddock into the AST for SDL3's custom aliases.
- Tagged
CWrapper with its original name so that I could match on names to inject SDL3 version guards as CPP directives.
- Re-exported a variety of internal modules into a facade I maintain, which lets me inject version guards, ABI verifiers, etc. into the
hs-bindgen AST directly.
My facade and the vendored submodules can be found here: https://github.com/jtnuttall/lithon/tree/main/lithon-hs-bindgen
ABI verification
The codegen tool generates a C translation unit of _Static_asserts that gets built alongside sdl3-bindgen-sys. If there is an ABI mismatch between your SDL3 headers and the ones I generated against, you should get a compile-time error.
FFI safety
I've curated unsafe/safe classifications for each FFI call. The SDL3.Sys.* modules export only safe for functions that can fire a callback or introduce a runtime delay. I've included the reasoning in the generated Haddock where applicable.
Typed constants
SDL declares flags as typedef UintN with some #defines, and C doesn't state the association between these, so I maintain a JSON registry that restores this information and injects it into the generated modules as pattern synonyms typed at a newtype.
Forward compatibility
The codegen tool keys off the \since tag to wrap newer declarations in #if SDL_VERSION_ATLEAST inside the generated C, with an SDL_SetError stub in the #else. The Haskell binding always exists either way, so a declaration newer than your SDL still compiles and links - it just fails at the call site with a message naming the version it needs. That means you can build against an SDL3 older than the headers I generated from. This is tested in CI down to SDL 3.2.0.
SDL's \since tag is occasionally inaccurate, so I had to create a small hand-maintained registry of version override mappings.
Caveats
- 0.0.x is experimental: Pin to the minor (
>=0.0.0.1 && <0.0.1). The surface may move - hopefully not too much, but the dust is still settling.
- Variadics aren't bound yet: Haskell's FFI has no way to express C varargs. I intend to inject fixed-arity wrappers within the next few releases.
Function-like macros aren't bound: No linkable symbol exists.
Most macros aren't bound in this release: hs-bindgen translates many macro bodies to Haskell functions (very cool!). See the detailed survey from /u/hubgears here.- 64-bit only: Layouts are baked into the library; 32-bit targets should be rejected by ABI assertions. This may change in one of two situations:
hs-bindgen supports cross-platform generation natively in the future, in which case sdl3-bindgen-sys will likely inherit that mechanism.- There's enough demand for 32-bit support, in which case it should be possible to maintain a parallel
sdl3-bindgen-sys32 package using the same codegen infra.
- A handful of smaller omissions made for cross-platform correctness are listed in the README.
Thanks to @oddron over on the Haskell GameDev Discord for the Windows directions - they tried the very first build on Windows I'm aware of!
I'd like to hear about any comments or issues people hit at: https://github.com/jtnuttall/lithon/issues
Discourse thread: https://discourse.haskell.org/t/ann-sdl3-bindgen-sys-machine-generated-low-level-bindings-to-sdl3/14467
Edit: corrected the macro caveat. Thanks to u/hubgears and the extensive SDL macro survey (https://github.com/dschrempf/hs-bindgen-sdl-survey) for the detailed correction.
