Running SDL2 App on Mac/Linux, that don't have SDL2 installed - static linking? (CMake, CLion)

Dear users!

I want to develop simple games for PC (Windows, Mac and Linux). I already have made some small games on Linux using SDL.
The last days I tried to setup a CMake Cross Platform SDL App - with success!
With the following guide (SDL2 with CMake) I created a CMake SDL Project which build on Windows, Mac and Linux.
On Windows I am working with Visual Studio (like in guide) and on Linux/Mac I am working with CLion.

My CMakeLists.txt file has the following content:

cmake_minimum_required(VERSION 3.13)

find_package(SDL2 REQUIRED)
include_directories (${SDL2_INCLUDE_DIRS})


add_executable(CMake_Demo_Mac main.cpp)
target_link_libraries (CMake_Demo_Mac ${SDL2_LIBRARIES})

And is linked to the .cmake file from the linked guide, that searches for SDL on the system:

# Distributed under the OSI-approved BSD 3-Clause License. See accompanying
# file Copyright.txt or for details.

# FindSDL2
# -------
# Locate SDL2 library
# This module defines
# ::
# SDL2_LIBRARY, the name of the library to link against
# SDL2_FOUND, if false, do not try to link to SDL
# SDL2_INCLUDE_DIR, where to find SDL.h
# SDL2_VERSION_STRING, human-readable string containing the version of SDL
# This module responds to the flag:
# ::
# If this is defined, then no SDL2_main will be linked in because
# only applications need main().
# Otherwise, it is assumed you are building an application and this
# module will attempt to locate and set the proper link flags
# as part of the returned SDL2_LIBRARY variable.
# Don't forget to include SDLmain.h and SDLmain.m your project for the
# OS X framework based version. (Other versions link to -lSDLmain which
# this module will try to find on your behalf.) Also for OS X, this
# module will automatically add the -framework Cocoa on your behalf.
# Additional Note: If you see an empty SDL2_LIBRARY_TEMP in your
# configuration and no SDL2_LIBRARY, it means CMake did not find your SDL
# library (SDL.dll,, SDL.framework, etc). Set
# SDL2_LIBRARY_TEMP to point to your SDL library, and configure again.
# Similarly, if you see an empty SDLMAIN_LIBRARY, you should set this
# value as appropriate. These values are used to generate the final
# SDL2_LIBRARY variable, but when these values are unset, SDL2_LIBRARY
# does not get created.
# $SDL2DIR is an environment variable that would correspond to the
# ./configure --prefix=$SDL2DIR used in building SDL. l.e.galup 9-20-02
# Modified by Eric Wing. Added code to assist with automated building
# by using environmental variables and providing a more
# controlled/consistent search behavior. Added new modifications to
# recognize OS X frameworks and additional Unix paths (FreeBSD, etc).
# Also corrected the header search path to follow "proper" SDL
# guidelines. Added a search for SDLmain which is needed by some
# platforms. Added a search for threads which is needed by some
# platforms. Added needed compile switches for MinGW.
# On OSX, this will prefer the Framework version (if found) over others.
# People will have to manually change the cache values of SDL2_LIBRARY to
# override this selection or set the CMake environment
# CMAKE_INCLUDE_PATH to modify the search paths.
# Note that the header path has changed from SDL/SDL.h to just SDL.h
# This needed to change because "proper" SDL convention is #include
# "SDL.h", not <SDL/SDL.h>. This is done for portability reasons
# because not all systems place things in SDL/ (see FreeBSD).

  set(SDL2_DIR "" CACHE PATH "SDL2 directory")

find_path(SDL2_INCLUDE_DIR SDL.h
                # path suffixes to search inside ENV{SDL2DIR}
                include/SDL2 include

  set(VC_LIB_PATH_SUFFIX lib/x64)
  set(VC_LIB_PATH_SUFFIX lib/x86)


# Hide this cache variable from the user, it's an internal implementation
# detail. The documented library variable for the user is SDL2_LIBRARY
# which is derived from SDL2_LIBRARY_TEMP further below.

  if(NOT SDL2_INCLUDE_DIR MATCHES ".framework")
    # Non-OS X framework versions expect you to also dynamically link to
    # SDLmain. This is mainly for Windows and OS X. Other (Unix) platforms
    # seem to provide SDLmain for compatibility even though they don't
    # necessarily need it.
      NAMES SDL2main
        ENV SDL2DIR

# SDL may require threads on your system.
# The Apple build may not need an explicit flag because one of the
# frameworks may already provide it.
# But for non-OSX systems, I will use the CMake Threads package.

# MinGW needs an additional link flag, -mwindows
# It's total link flags should look like -lmingw32 -lSDLmain -lSDL -mwindows
  set(MINGW32_LIBRARY mingw32 "-mwindows" CACHE STRING "link flags for MinGW")

  # For SDLmain

  # For OS X, SDL uses Cocoa as a backend so it must link to Cocoa.
  # CMake doesn't display the -framework Cocoa string in the UI even
  # though it actually is there if I modify a pre-used variable.
  # I think it has something to do with the CACHE STRING.
  # So I use a temporary variable until the end so I can set the
  # "real" variable in one-shot.
    set(SDL2_LIBRARY_TEMP ${SDL2_LIBRARY_TEMP} "-framework Cocoa")

  # For threads, as mentioned Apple doesn't need this.
  # In fact, there seems to be a problem if I used the Threads package
  # and try using this line, so I'm just skipping it entirely for OS X.

  # For MinGW library

  # Set the final string here so the GUI reflects the final state.
  set(SDL2_LIBRARY ${SDL2_LIBRARY_TEMP} CACHE STRING "Where the SDL Library can be found")

  file(STRINGS "${SDL2_INCLUDE_DIR}/SDL2_version.h" SDL2_VERSION_MAJOR_LINE REGEX "^#define[ \t]+SDL2_MAJOR_VERSION[ \t]+[0-9]+$")
  file(STRINGS "${SDL2_INCLUDE_DIR}/SDL2_version.h" SDL2_VERSION_MINOR_LINE REGEX "^#define[ \t]+SDL2_MINOR_VERSION[ \t]+[0-9]+$")
  file(STRINGS "${SDL2_INCLUDE_DIR}/SDL2_version.h" SDL2_VERSION_PATCH_LINE REGEX "^#define[ \t]+SDL2_PATCHLEVEL[ \t]+[0-9]+$")
  string(REGEX REPLACE "^#define[ \t]+SDL2_MAJOR_VERSION[ \t]+([0-9]+)$" "\\1" SDL2_VERSION_MAJOR "${SDL2_VERSION_MAJOR_LINE}")
  string(REGEX REPLACE "^#define[ \t]+SDL2_MINOR_VERSION[ \t]+([0-9]+)$" "\\1" SDL2_VERSION_MINOR "${SDL2_VERSION_MINOR_LINE}")
  string(REGEX REPLACE "^#define[ \t]+SDL2_PATCHLEVEL[ \t]+([0-9]+)$" "\\1" SDL2_VERSION_PATCH "${SDL2_VERSION_PATCH_LINE}")



                                  REQUIRED_VARS SDL2_LIBRARY SDL2_INCLUDE_DIR
                                  VERSION_VAR SDL2_VERSION_STRING)

On Windows I created a Visual-Studio Project with the CMake-Gui. When I run it, it only needs the SDL2.dll file in the same path as the generated .exe-file. In Visual Studio, I linked all the .dll-dependencies needed to my .exe-file (properties / Configuration / C/C++ / Code Generation / Runtime library / Multithreaded). Then I copied my .exe file and the SDL2.dll file to another Windows Computer to see, if the SDL App would start and yes, it worked!

Now I need the same for Linux/Mac, I already tried running the SDL App on my sisters MacBook but it says it can’t find the sdl-framework. How can I set it up that the sdl-framework needed libraries are linked to my executable-file in Mac/Linux? What do I have do add to my CMakeLists.txt-File to build id properly with all the dependencies so it works on a non-SDL Linux/Mac system? I also read about, that I need to include a .a or .dylib file as they are the equivalent to the .dll-files on windows but I was not able to find these files (something like SDL2.a or SDL2.dylib (?)). I also studied A LOT threads but a lot of them were old or didn’t build the project with cmake, so they didn’t help me either…

Could someone help? I would much appreciate any help how I can run my Mac/Linux CMake-SDL App on Mac/Linux w/o SDL or any other needed lib installed. I tried so much but wasn’t successful.

Thank you guys!

the source code of my SDL App (testing):

#include "SDL.h"

int main(int argc, char *argv[])

    SDL_Window *window = SDL_CreateWindow(

    SDL_Renderer *renderer = SDL_CreateRenderer(window, -1, SDL_RENDERER_SOFTWARE);
    SDL_SetRenderDrawColor(renderer, 255, 255, 0, SDL_ALPHA_OPAQUE);


    return 0;


The documentation of SDL mentions on Mac “You can ship an SDL.framework, or just build the .dylib file and ship it with an appropriate install_name to ship beside your program’s binary.” How does this work? How can I make that with my SDL App?

And how does this work on Linux?

BUT it also says on the wiki under static linking " SDL 2.0, unlike 1.2, uses the zlib license, which means you can build a static library linked directly to your program, or just compile SDL’s C code directly as part of your project. You are completely allowed to do that. However, we encourage you to not do this for various technical and moral reasons". How can I make my SDL2 App then runnable on other platforms, without static linking on Mac/Linux?


The only thing I met that somehow is like my problem was the follwing post from 2005: SDL under MacOSX. But that didn’t help me either…


Ony my Mac, i found the mentioned files libSDL2-2.0.0.dylib, libSDL2_test.a, libSDL2.a and libSDL2main.a under /usr/local/Cellar/sdl2/2.0.9_1/lib. I copied the files the build folder where the binary-executable is stored. Then I tried to run it on my sisters Mac but still, I get the same error dylib: Library not loaded: @rpath/SDL2.framework/Versions/A/SDL2.


After a lot more searching, i found a recently post on this forum: Creating an Easily Distributable Executable File. As the discusssion progresses, it says that it is indeed not easy to setup everything for Mac or Linux. Altough there are some working ideas, I think it is not worth it for me to make the game for non-installed SDL for Mac/Linux as it would require me to get more into that topic. I think the easiest way for me is to just build for Windows. Potentially a solution on Mac could be using an install-setup to move the sdl2.framwork files to the /Libray/Frameworks folder, but I don’t know if this is even possible.

As long as there is not a complete “easy” tutorial for people like me I guess it is not worth the effort since I don’t wanna waste to much time on this. However, I learned some new things.

You can just bundle the SDL framework (SDL2.framework) in the app bundle, in the Frameworks subfolder.

On MacOS, the app bundle ( is really just a folder with a specific layout. You can put SDL2.framework in and MacOS will find it there (assuming you’re building with a recent version of Xcode, which sets up the rpath to look there by default). I set up my SDL-based Xcode projects to copy SDL2.framework to that folder as a post compilation step. I’ve played around with CMake a bit, and I’m fairly certain that it can generate an Xcode project that will include this step. You should also get comfortable with Xcode if you’re gonna do a Mac build.

As for Linux, either create a package for your game that lists SDL2 as a dependency so whatever distro’s package manager will auto-install SDL2 for your users, or just statically link SDL2 in. You could also ship the .so with your game’s executable, but that requires some steps that involve setting specific linker flags etc. that I’ve forgotten since I haven’t done any Linux stuff in a long time.

thank your for your response @sjr!

I wanted to avoid Xcode but I guess it is needed to build the I thought with CMake I could work on the project cross-platform. Statically linking is not suggested on the homepage so I should rather just include the framework to my SDL App. I am not familiar with Xcode, but when I setup everything is there an “build app” option that creates my “” with the framework in automatically? That would be awesome and mean that the game would be completely portable. EDIT: I just saw you can build an Xcode project with CMake (like on windows for Visual Studio) with the command cmake -G Xcode <dir of CMakeLists.txt> (src) - could this also be an option?

On Linux, I guess the best solution is to include a configure script, to build the game. So that after hitting ./configure then make and sudo make install all sdl dependencies are installed too, am I right with this solution?

Have your CMake project output an Xcode project for Mac and autoconf/automake stuff for Linux. You’ll need to specify in CMake that the Xcode project should have a post-compilation Copy Files build phase that copies SDL2.framework to your game’s frameworks folder ( Your game will need to link against the SDL2 framework instead of individual library files (SDL2.dylib or whatever) but it looks like you’re already doing that.

As to using automake to have your users install the game and SDL on Linux, it’s not very user friendly to require users to run a shell script to install your game (though it’s not unheard of). A good option would be to distribute packages for whatever Linux distros you’re supporting, and have SDL2 listed as a dependency. Then the package manager will install SDL for your users if it isn’t already.

I sucessfully managed to setup an Xcode project, that has the sdl2.framework inside the actual app included. This awesome article helped me a lot setting up Xcode.

Agree, I guess it isn’t that user friendly. How can I make a “package installer”? Are there tutorials (with sdl) online? I would love to support Debian (Ubuntu LTS 16.04 and above). Could you give me some hints/examples?

No, it’s not needed. As was mentioned, a Mac App bundle is just a directory with a defined structure (which you would usually distribute as a .dmg image file) so it’s possible to create it using a regular command-line script. Here’s an extract from the script I use to build my app:

rm -R
cp -R /Library/Frameworks/SDL2.framework/*
cp -R /Library/Frameworks/SDL2_ttf.framework/*
cp -R /Library/Frameworks/SDL2_net.framework/*

Thanks for pointing that out! Still, I think sticking to Xcode is easier (for me).

EDIT: On Linux. the “best” solution is probably as mentioned to package the game and its dependencies. As there a lots of distros available, I came across AppImageKit which can be used to deploy a Linux-SDL game on “all” Linux distros. Does anybody has experience with this tool?

EDIT2: Another solution could be MojoSetup by @icculus, maybe I am successfull with this tool. I am starting to read the documentation, but it seems not that easy…

1 Like

Just FYI, you can have Xcode build your game from the command line with “xcrun”. In case that’s a thing you want to do.

As for Linux packages, I would just pick a distro or two (say, Ubuntu and Fedora) and only build packages for those, to make testing and supporting your game on Linux easier. I’ve never built a Linux package before, but I imagine it wouldn’t be too difficult if you’re familiar with shell scripts etc, since it seems your game’s package wouldn’t need to do anything but copy the files.

Ubuntu packaging guide seems like a good place to learn how to make one.

1 Like

Yeah I guess just building let’s say for Ubuntu is a good start (.deb). But still i first will try MojoSetup. Also @icculus pointed out into his presentation (page 35) on Steam Dev Days: “Don’t ever ship .deb or .rpm, etc, packages. It’s not worth the trouble.”

I will first try MojoSetup, then maybe AppImage and at the end building a. deb-package. Wow I didn’t know that Linux is that hard for distributing an application. A last alternative could be also using the Steam API, but I don’t want to deploy my game on steam.

LAST UPDATE: After trying to make an installation-shield using MojoSetup I was not successful. Then I also tried the examples, which also failed.

AppImageKit did deliver too less information how to setup it proberly, so I didn’t use that either.
A last and maybe good solution would be using the Steam API. There are even tutorials how to setup (even without Steam installed). I will try that and if it doesn’t work, the “best” solution will be statically linking which is even preferred at distribution guide for Linux. As it seems with SDL2, statically linking is allowed because SDL2 is licensed by zlib. There are a lot of controversities about static vs. dynamic linking (e.g. StackOverflow). For my part, I think (right now) statical linking your SDL2-App on Linux is an easy and good solution (if it works). So if the steam API setup procedere gives me also a lot of pain, I will statically link everything.

All my research gave me a lot of headaches as I found out how difficult is it to release an “Universal” App for Linux. At least I understand now, why distribution-packages like deb or rpm exist. And setting up these is again in my opinion not a good solution.

What are you guys thinking? I would love to see your opinions about this! If I am anywhere incorrect then please correct me!


Did you have any success with this? I can’t believe something so basic takes this much effort in C++ land.
I’m trying to statically link SDL2 into my project with CMAKE and it seems to be impossible
I checked hundrends of SO questions and even made my own:

I honestly just switched to Visual Studio and Windows only (most gamers use Windows anyway).
it just isn’t worth the hassle in my opinion.