SDL3 Haskell Bindings λ

Work in progress bindings for the SDL3 library written in Haskell.

Please report any bugs or suggestions you have for the bindings!

Setup Instructions

Install SDL3 from source: SDL GitHub

Linux

To build SDL3 from source on Linux:

# Navigate to SDL3 source directory
cd path/to/SDL3/source

# Create and enter build directory
mkdir build
cd build

# Configure with cmake.
# CMAKE_BUILD_TYPE can be whatever you need it to be.
cmake -DCMAKE_BUILD_TYPE=Release -GNinja ..

# Build
cmake --build . --config Release --parallel

# Install (requires sudo)
sudo cmake --install . --config Release

This will install SDL3 to your system so that cabal can find and build the sdl3 package.

Find your way back to this project's directory and run cabal build sdl3 to build just the package.

Windows

Recommendation: Use the Developer PowerShell or Developer Command Prompt that comes with Visual Studio for best results.

# Navigate to SDL3 source directory
cd path/to/SDL3/source

# Create and enter build directory
mkdir build
cd build

# Configure with cmake.
# CMAKE_BUILD_TYPE can be whatever you need it to be.
cmake -DCMAKE_BUILD_TYPE=Release -GNinja ..

# Build
cmake --build . --config Release --parallel

# Install (requires sudo)
cmake --install . --config Release

Make sure SDL3 compiles a .DLL file, and pkgconfig knows that SDL3 exists. (You might have to install pkgconfig using your pacman of choice.)

You can do this by setting:

set PKG_CONFIG_PATH="path\to\SDL3\lib\pkgconfig"
# or
$env:PKG_CONFIG_PATH="path\to\SDL3\lib\pkgconfig\"

Ensure the .DLL file is present in your PATH environment variable or within the root directory for this project.

You'll also want to add a cabal.project.local file to the root directory with:

package *
  extra-include-dirs: "path/to/SDL3/include/"
  extra-lib-dirs: "path/to/SDL3/lib/"

Once all of this is done, you can find your way into this directory and run cabal build sdl3 to build just the package.

Building and Running Examples

To build all examples:

cabal build --flag examples

To see a list of all available examples:

cabal run --flag examples

To run a specific example:

cabal run --flag examples EXAMPLE_NAME

For example, to run the init example:

cabal run --flag examples init

You can also build specific executables in a similar manner by specifying the target name.

Build Options

The bindings support two main build configurations:

Dynamic Linking (Default)

cabal build sdl3                    # Build library only
cabal build --flag examples        # Build with examples

This is the default and recommended approach for development. Your executable will depend on SDL3 shared libraries.

Static Linking

cabal build --flag static-linking  # Build with static SDL3 (Linux only)

Creates self-contained executables with SDL3 compiled in. Requires SDL3 to be built with static libraries enabled.

⚠️ macOS Limitation: Static linking is not supported on macOS due to Apple's linking restrictions. The static-linking flag is ignored on macOS. Use dynamic linking with bundled libraries instead (see DISTRIBUTION.md).

Note: Static linking requires SDL3 built with -DBUILD_SHARED_LIBS=OFF. See DISTRIBUTION.md for details.

Cabal Project Configuration

Add to cabal.project.local:

package sdl3
  flags: +static-linking  # Enable static linking

Distribution

For distributing applications to end users, see our comprehensive Distribution Guide which covers:

• Bundling official SDL3 releases (recommended)
• Static linking strategies
• Platform-specific distribution
• Testing and optimization
• Production considerations

Quick Summary:

• Development: Use dynamic linking (default)
• Distribution: Bundle SDL3 libraries with your executable
• Self-contained: Use static linking for single-file distribution (Linux only)
• macOS: Use dynamic linking with bundled libraries

Working Examples

Core Functionality

Initialization & System

• Init - Basic SDL initialization
• System - System information and capabilities
• Platform - Platform-specific functionality
• CPU Info - Processor information
• Power - Power state monitoring
• Hints - SDL configuration hints

Window & Rendering

Rendering

• Render - 2D rendering basics

Misc

• Rect - Rectangle basics (no rendering here)

GPU & Graphics

These examples are based off of the original SDL3 GPU Examples

• GPU Triangle - Raw triangle rendering
• GPU Clear - Basic screen clearing
• GPU Vertex Buffer - Vertex buffer usage (matches gpu-vbuf)
• GPU Textured Quad - Texture mapping
• GPU Custom Sampling - Implementing custom texture sampling logic
• GPU Animated Quad - Animation basics
• GPU Instanced - Instanced rendering
• GPU Stencil - Stencil buffer operations
• GPU Cull - Culling techniques
• GPU Multi-Window - Multiple window rendering
• GPU Draw Indirect - Leveraging indirect draw commands for GPU-driven rendering
• GPU Basic Compute - Basic compute shader usage
• GPU Clear 3D Slice - Clearing a slice of a 3D texture
• GPU Compute Uniforms - Using uniforms with compute shaders
• GPU Compute Sampler - Using samplers within compute shaders
• GPU Compute Tonemapping - Using compute pipelines for HDRI texture tonemapping.
• GPU Copy Consistency - Copy a texture to the GPU, alter it, and draw it to the framebuffer.
• GPU Copy & Readback - Write texture to GPU and read it back, verifying data integrity.
• (... More coming ...)

Input & Interaction

User Input

• Events - Event handling
• Gamepad - Controller input
• Touch Device - Touch input handling (Can't test properly but compiles.)
• Haptic - Force feedback (Can't test properly but compiles.)

User Interface

• Dialog - Dialog boxes
• Message Box - Simple message dialogs
• Clipboard - Clipboard manipulation
• Tray - System tray integration

Audio & Media

Audio

• Audio - Audio playback
• WAV - WAV file handling

Camera

• Camera - Camera device access (tested on macOS)

System Integration

File & Data

• Filesystem - File system operations
• Storage - Persistent storage
• GUID - Globally unique identifier handling

Internationalization

• Locale - Localization support

Time & Process Management

Time

• Time - Time functions
• Timer - Timer functionality

Process

• Process - Process management

Sensors

Hardware

• Sensor - Hardware sensor access (Can't test properly but compiles.)

📊 Binding Status

Last updated: 2025-08-20 18:40 UTC

SDL3 commit: e1a623f129e75ad532315852d656fb26c80382a6

Summary

• Total Modules: 55
• Modules with Bindings: 55
• Complete Bindings: 55
• Missing Functions: 0
• Completion Rate: 100%

Status by Module

Legend

• ✅ Complete: All functions from the header are bound
• ⚠️ X missing: Header has bindings but X functions are missing
• ❌ No bindings: No Haskell bindings exist for this header
• ❓ Unknown: Status could not be determined

Notes

• Status reflects core SDL3 headers (test/internal headers excluded)
• Missing function details are available in the broken/ directory after running the binding checker
• Use ./check-sdl-bindings -i for interactive binding status checking
• Some modules may intentionally have no bindings if not applicable to Haskell