How to install SDL2 on macOS
Tags: c, sdl2, setup
Published: 2024-06-26 14:20:50

---
title: How to install SDL2 on macOS
published: true
description: "Setting up SDL libraries on macOS can be challenging, this tutorial covers how to set it up, compile a program and open a window to as a test."
tags: c, sdl2, setup
canonical_url: https://www.csalmeida.com/log/how-to-install-sdl2-on-macos/
cover_image: https://dev-to-uploads.s3.amazonaws.com/uploads/articles/4x2ir7jjatpjcnpc19v6.png
# Use a ratio of 100:42 for best results.
# published_at: 2024-06-26 14:14 +0000
---

Running SDL2 libraries on macOS is slightly different than running them on Linux and Windows systems.

You might want to run these libraries to work on a native application or a video game that requires graphics and access to other system controls.

Since there are a few pitfalls to avoid I have put this resource together that covers installing `SDL2` and `SDL2_image` into the system.

Finally, I'll include a test program to open a window and a command to compile it.

It is written in C but SDL can be used with C++, Rust and a few other languages as well.

## Installation

The first step is to get all files required into your system.

Download SDL2 by picking the `.dmg` one from the release list:
> https://github.com/libsdl-org/SDL/releases

Additionally, download the SDL2_image library (also a `.dmg` from its release list:
> https://github.com/libsdl-org/SDL_image/releases

Execute the SDL2 file (will be named something similar to `SDL2-2.30.4.dmg`) and a window will open with a few files and an `SDL2.framework` folder.

Open Finder, click `Go` then `Go to folder...` and type `/Library/Frameworks` which will open the contents of that folder.

Drag `SDL2.framework` to `/Library/Frameworks` and repeat the steps for the SDL2_image file.

There should be two additional folders in `/Library/Frameworks`, `SDL2.framework` and `SDL2_image.framework`.

## Compile a program

One way to test the installation is to write a program, this one opens a window in the system.

Create a `main.c` file and add the contents below to it:

```c
#include <stdio.h>
#include <stdbool.h>
#include <SDL.h>
#include <SDL_timer.h>

int main(void)
{
    // Attempt to initialize graphics and timer system.
    if (SDL_Init(SDL_INIT_VIDEO|SDL_INIT_TIMER) != 0)
    {
        printf("error initializing SDL: %s\n", SDL_GetError());
        return 1;
    }

    SDL_Window* window = SDL_CreateWindow("Hello, SDL2 on macOS 🍎",
                                       SDL_WINDOWPOS_CENTERED,
                                       SDL_WINDOWPOS_CENTERED,
                                       640, 480, 0);
    if (!window)
    {
        printf("error creating window: %s\n", SDL_GetError());
        SDL_Quit();
	    return 1;
    }

    // Keep the window open, in this case SDL_Delay(5000); statement won't work.
    bool running = true;
    while (running)
    {
        SDL_Event e;
        while (SDL_PollEvent(&e) != 0)
        {
            if (e.type == SDL_QUIT)
            {
                running = false;
                break;
            }
        }
     }

    // clean up resources before exiting.
    SDL_DestroyWindow(window);
    SDL_Quit();
}
```


On a terminal window, navigate to the same directory of the `main.c` file and attempt to compile it:

```bash
gcc -o open_window main.o `sdl2-config --libs --cflags` -ggdb3 -O0 --std=c99 -Wall -F/Library/Frameworks -framework SDL2 -framework SDL2_image -lm
```

This could work first try but in my case I've hit quite a few issues a few are solved by the way the header files are included and the structure of the compile command which have already been addressed but there's a few more I found while trying to compile an SDL2 based program.

One of the issues might look like this: 

```
dyld[94016]: Library not loaded: @rpath/SDL2.framework/Versions/A/SDL2
  Referenced from: <BAD3873A-39CC-4033-8C2A-85A0FC365404> /Users/user/Projects/open_window/open_window
  Reason: no LC_RPATH's found
[1]    94016 abort      ./open_window
```

The way I solved it was by running the following in the terminal before compiling the program:

```bash
export DYLD_FRAMEWORK_PATH=/Library/Frameworks
```

macOS displays a notice saying _“SDL2.framework” cannot be opened because the developer cannot be verified_

The issue can be addressed by running the executable, e.g. `./open_window` then opening the Privacy & Security settings and scroll to _Security_.

You will see a button to allow the `SDL2.framework`, click "Allow Anyway".
Do the same for `SDL2_image.framework` if it shows up.

The notice should now show an "Open" option, there's more context in this Github issue:

> https://github.com/libsdl-org/SDL/issues/4689#issuecomment-2189963510

## Opening a window

Assuming the program compiled correctly we can now open a window by executing the program.

On a terminal run `./open_window` and an empty should should now show!

![A window with a black background with a title](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/4x2ir7jjatpjcnpc19v6.png)

## Additional Notes

- A lot of programs will use `#include <SDL2/SDL.h>` but in this case `#include <SDL.h>` needs to be used instead when including SDL related header files.
- SDL2 can also be installed with Homebrew, if you prefer it there's [a tutorial on dev.to that goes over the setup](https://dev.to/hacker_thronx/sdl2-on-macos-sonoma-installation-with-vscode-29pe) as well.