Library 'SDL3' not found (macOS)

Help
1

Hi there, complete Odin beginner here. I’m looking to tinker with a simple game idea, and was able to build and run the GLFW example from the Odin overview documentation without issue. Yay!

I can similarly create a basic Raylib window with Karl Zylinski’s example code.

But when I try a basic SDL3 example for comparison:

package main

import "core:fmt"
import SDL "vendor:sdl3"

main :: proc() {
    if !SDL.Init({.VIDEO}) {
        fmt.eprintln("Failed to initialize SDL:", SDL.GetError())
        return
    }
    defer SDL.Quit()
}

I get:

$ odin version
odin version dev-2025-04-nightly:d9f990d
$ odin run .
ld: library 'SDL3' not found
clang: error: linker command failed with exit code 1 (use -v to see invocation)

What am I doing wrong? Is SDL3 bundled with Odin differently than GLFW and Raylib? I assume I’m misunderstanding something basic.

If it helps, I’m on macOS 15.4.1 (ARM), and I installed Odin by just downloading the latest stable release from GitHub, extracting dist.tar adding the folder to my PATH, and then running xattr -d com.apple.quarantine on the odin executable and the libs for libLLVM/libz3/libzstd to resolve the macOS quarantine issues. Thanks in advance.

2

SDL3 wants you to dynamically link it, opposed to Raylib. So for SDL3 we ask the linker for sdl3, and as you can see it can’t find it, usually meaning you haven’t installed it.

The easiest way to do that on MacOS is using brew install sdl3, after doing that it should just work.

3

Thanks so much for the help! Do you know where I can learn more about how Odin/the linker finds SDL3 on the system? I prefer compiling my dependencies from source, but I can’t seem to get Odin to find it. I’ve tried putting it in the same directory as my Odin code, as well as in /usr/local/lib and /usr/local/include. Clearly I’m a little out of my depth in this area :sweat_smile:

4

For anyone else who runs into this issue, I ended up getting it to work, though I’d still love to learn more from anyone with more knowledge than me.

When I built SDL, I had to modify the default instructions and use -DSDL_FRAMEWORK=OFF:

cmake -S . -B build -DSDL_FRAMEWORK=OFF -DCMAKE_OSX_ARCHITECTURES="arm64;x86_64"
cmake --build build
cmake --install build --prefix ~/SDL

(With -DSDL_FRAMEWORK=ON, I’d tried putting the framework in all sorts of locations and using all sorts of Odin linker flags but never got it all to work; if someone knows how to make it work please share!)

Then to make Odin happy I had to use:

odin run . -extra-linker-flags:"-L$HOME/SDL/lib -rpath $HOME/SDL/lib"
5

I don’t know exactly how SDL3 compiles as I did not use it yet, but to see if the linker searches for it and where you can use:
odin run . -show-system-calls
Which will show the call to the linker with all the params:

image
image1920×428 164 KB