Information on how to get SDL2 working on OSX

[bvssvni]

If you don't have brew installed, see #177

This solution is relevant if you get an long error message when running cargo build ending in:

ld: library not found for -lSDL2

Lacking permission to link SDL2

On some computers, the brew command fails to create the symlinks to the libraries it installs. This means the Rust compiler can not find them. To get permission to do this, use the chown command as following:

brew install sdl2
sudo chown root:wheel /usr/local/bin/brew
brew unlink sdl2 && brew link sdl2

Missing path in LIBRARY_PATH environment variable

The Homebrew package manager symlinks library to the directory /usr/local/lib. To use these libraries with Rust, you need to add it to the LIBRARY_PATH environment variable. The command echo $LIBRARY_PATH will tell you if /usr/local/lib is added. If it is missing, add the following to the ~/.bash_profile configuration file:

export LIBRARY_PATH="$LIBRARY_PATH:/usr/local/lib"

This will add the directory to the environment variable each time you start up a new Terminal window.

M1 Hardware

This solution was suggested by #175 (comment)

export LIBRARY_PATH="$LIBRARY_PATH:/opt/homebrew/lib

[golergka]

I've just spend about 2 hours troubleshooting this issue... Could it be linked somewhere from README file?

[indiv0]

@bvssvni I think that @golergka's suggestion is reasonable, but maybe we should compile a caveats.md or similar for FAQs and common issues?

[bvssvni]

@golergka I opened up an issue on the sdl2_game_window repo. PistonDevelopers/sdl2_window#72
It is already linked from the README in rust-sdl2

[subhashb]

👍
Can even link this issue in piston-examples README. That's where most people starting with Piston will land up.

Let me know if you want me to raise a PR.

[bvssvni]

@subhashb Please do.

[subhashb]

@bvssvni Here goes: PistonDevelopers/piston-examples#92

[rofrol]

On ubuntu 14.10:

apt-get install libsdl2-dev

[ghost]

brew install sdl2

worked fine for me. I didn't take any other actions. Consider editing the info. here.

[OpenUAS]

@rofrol ..Hmm was the OSX part in the description not obvious ;)

[tylerseymour]

For anyone arriving here recently, I'm just confirming that this is still an issue on MacOS Catalina as of August 2020, and that the provided solution by @bvssvni (Thank you!) still works. Only caveat is you'll need to add the $LIBRARY_PATH to your .zshrc, assuming you've migrated to it.

[nwilson314]

Spent a long time debugging the "ld: library not found for -lSDL2" issue on an M1 Mac with Big Sur. What ended up solving it for me was actually installing SDL2 via macports instead of homebrew. I have no idea why that matters (perhaps someone more knowledgeable than I can say) but I figured I'd post in case someone else runs into the same issue.

EDIT: While I can run vanilla SDL2, I have not been able to get SDL2_image to work. The instructions above work well for a Mac with an Intel CPU (I checked on my laptop) but it appears there is a problem with the M1. I attempted to use the SDL2 Framework route and found that the SDL2 libraries are not compatible with the ARM-64 architecture that the M1 uses (and SDL2 doesn't). This appears to be a fairly common problem that remains unaddressed as far as I can tell.

[kbolino]

Running brew as root is no longer supported, at least on recent versions of macOS on M1 hardware:

% uname -r
20.6.0
% uname -m
arm64
% brew --version
Homebrew 3.2.13
Homebrew/homebrew-core (git revision ecf3c35ee41; last commit 2021-09-23)
% sudo brew link sdl2
Password:
Error: Running Homebrew as root is extremely dangerous and no longer supported.
As Homebrew does not drop privileges on installation you would be giving all
build scripts full access to your system.

However, brew link sdl2 gives a hint for how to work around this:

% brew link sdl2
Warning: Already linked: /opt/homebrew/Cellar/sdl2/2.0.16
To relink, run:
  brew unlink sdl2 && brew link sdl2

The link is now in /opt/homebrew/lib instead of /usr/local/lib. So the following solves the problem:

% export LIBRARY_PATH="$LIBRARY_PATH:/opt/homebrew/lib"

[kodalli]

Make sure you run

echo $SHELL

and see what your default shell interpreter is. I was editing my bash_profile instead of my zprofile for the LIBRARY_PATH and was wondering why I couldn't get it to work.

[TomLisankie]

@kbolino Thank you!!

[shteffen]

None of the solutions above worked for me, unfortunately. However, editing Cargo.toml dependency like this helped:
[dependencies.sdl2] git = "https://github.com/AngryLawyer/rust-sdl2"

This uses github instead of local library, obviously, but it was fine in my case and maybe helps someone else who finds this answer.

[EriKWDev]

In the interest of the public, given that this is still the first page that comes up for me when I google this issue, it would be great if there could be an edit made to the description of the original post above to include the new updated information by @kbolino

I.e the new path being:

export LIBRARY_PATH="$LIBRARY_PATH:/opt/homebrew/lib"

@bvssvni

[bvssvni]

@EriKWDev Updated!