Posted on 21 Sep 2021.
EDIT: Changed some details about messages, added note about Big Sur
EDIT 2: Updated note about Big Sur
In this post I will be explaining how a basic SDL2 program compiling to a bare executable can be turned into a nice app bundle (.app) on macOS.
The starting point for this is a basic C/C++ SDL2 executable, that simply opens a window, handles events and quits on the SDL_QUIT event.
In my case this is a Chip-8 emulator (called 'Chip8e'), which therefore also handles opening a file (chip-8 rom) given on the command-line, but handling this (making 'open with' and such work) will come later.
We'll first focus on just having an app bundle that can be double clicked to open the SDL2 program. Note that this does require the program to stay open when run without being given arguments.
App bundles (apps) are actually just normal directories with a certain structure and a .app extention. The basic structure is as follows:
Chip8e.app
\- Contents
|- Info.plist (main information about the app)
|- PkgInfo (seems to generally be 8 bytes, containing "APPL????")
|- MacOS
| \- chip8e (bare executable, as created by the compiler)
|- Resources
| \- appicon.icns (icon for the application)
|- Frameworks
| \- (any frameworks (.framework) and libraries (.dylib) needed)
\- _CodeSignature
\- (files having to do with the apps signature, created when signing an app)
The Info.plist file is the main file for an app to work (except for the actual executable, of course). It is in Apple's 'property-list'-format, which is XML-based.
It contains core information about the app, including the identifier, version, excutable name, icon file name, and supported file-types.
An example (somewhat based on what XCode generates and what I use) follows:
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>CFBundleDevelopmentRegion</key>
<string>en</string> <!-- seems to always be 'en' -->
<key>CFBundleDocumentTypes</key>
<array> <!-- list of supported file-types, will come later -->
</array>
<key>CFBundleExecutable</key>
<string>chip8e</string> <!-- name of main executable file, inside MacOS-directory -->
<key>CFBundleIconFile</key>
<string>appicon.icns</string> <!-- name of icon file, inside Resources-directory -->
<key>CFBundleIdentifier</key>
<string>com.elzod.chip8e</string> <!-- bundle identifier, should be in reverse-url format -->
<key>CFBundleInfoDictionaryVersion</key>
<string>6.0</string> <!-- seems to always be '6.0' -->
<key>CFBundleName</key>
<string>Chip8e</string> <!-- name for the app -->
<key>CFBundlePackageType</key>
<string>APPL</string> <!-- seems to always be 'APPL' -->
<key>CFBundleShortVersionString</key>
<string>1.0.0</string> <!-- version string as seen when quick-looking, getting info in Finder, and in About-window -->
<key>CFBundleSupportedPlatforms</key>
<array>
<string>MacOSX</string> <!-- supported platforms, always 'MacOSX' -->
</array>
<key>CFBundleVersion</key>
<string>2</string> <!-- 'internal' version, seen in About window, usually used as a build-number -->
</dict>
</plist>
The PkgInfo file seems to be optional, although XCode does always generates it with the contents of APPL???? without a newline. It should therefore be 8 bytes in size.
The MacOS directory contains the main executable file and the Resources directory contains other resources, like the icon file. The file names for these are specified in Info.plist.
The icon file is in .icns format, and there are various ways of creating these (including command-line tools). In my case I just took an 512x512 pixel png and used Preview to save it as a .icns by using 'save as' and holding option while clicking the file type dropdown (which greatly expands the amount of file types available).
The Frameworks directory contains the framworks and libraries needed by the app. For this SDL2 program this is of course the SDL2 framework.
How this should be included and what to do when compling to make it work properly is the next point of action.
The _CodeSignature directory is created when an app is signed and contains its signature.
MacOS has two ways of handling libraries: the 'regular / classic' separate library (.dylib) and headers (.h), and a combined form of those in a framework bundle (.framework). For the purposes of packing SDL2 with the application, a framework is easier to handle.
Which type is used can somewhat depend on how SDL2 was accuired. If it used 'the unix way' (package managers, like Homebrew, tend do do this) it will be a library and header files.
If it was downloaded from the SDL2 site, then the downloaded disk image contained a .framework.
During compilation, the first way is usually done with something like running sdl2-config, while the second is manually specifing the framework (and search path).
Compiling like this does however (usually) force the library or framework to be in a certain spot on the users system for the executable to run succesfully.
App bundles however are supposed to be stand-alone, self-contained, and to require no further configuration, so that is no good.
This is where the install path and rpath come in. Libraries on macOS have a install path which is set on the library and indicates where it should be located.
When linking with it, this path is copied into the executable so when macOS loads it, it knows where it can find the library.
These can be static, or dynamic depending on (among others options) the executable location (using @executable_path).
One further option for the install path is to use @rpath, which allows the executable itself to subsistute that part with a path specified in the executables own rpath.
Libraries tend to use static install paths, which would require using some tools to modify the executable to update it to be correct for packaging into a app bundle. Frameworks (or at least SDL2.framework) tend to use a rpath-based install path that locates the library within the framework bundle, meaning these can be used as-is by setting an appropriate rpath while compiling the executable. This is why the framework is easier to handle.
Switching over to using the SDL2 framework and making it work in an app bundle is quite easy: Get the framework (in a disk image) from The SDL2 download page. When compiling, use -F to set the location where the SDL2.framework is located
(I put it in the same folder as where I'm compiling, so I used -F .).
Use -framework SDL2 to indicate we want to link with it,
and finally, to set the rpath, use -rpath @executable_path/../Frameworks, as that is where the SDL2.framework will go relative to the main executable in the app bundle.
SDL2.framework can then be copied into the Frameworks directory and the rpath will make sure it can be found when run.
Make sure to copy symlinks instead of following them while copying it because these are used within framework bundles and not doing this unnecessarily bloats its size.
To have the bare executable also work, add another -rpath with the relative path to the framework from the bare executable.
For instance, to have it run with the framework next to the executable, use -rpath @executable_path.
Now that the structure of the app bundle and using the framework is handled, this can be put together to create a functioning app.
Following is (part of) my Makefile which will set up the app bundle for Chip8e.
It assumes SDL2.framwework to be in the same directory, and Info.plist, PkgInfo and appicon.icns to be in a macos subdirecotry.
# additional flags for the compiler # (here with '-F .' to search in current directory for the framework, and a second rpath to have the bare executable still work) CFLAGS = -framework SDL2 -F . -rpath @executable_path/../Frameworks -rpath @executable_path # target for building a bundle, chip8e: regular target for bare executable bundle: chip8e # remove old app rm -rf Chip8e.app # create app structure mkdir -p chip8e.app/Contents/MacOS mkdir -p chip8e.app/Contents/Frameworks mkdir -p chip8e.app/Contents/Resources # copy framework (note capital R to copy symlinks instead of following them) cp -R SDL2.framework chip8e.app/Contents/Frameworks/ # copy main executable cp chip8e chip8e.app/Contents/MacOS/ # copy icon, Info.plist and PkgInfo, here from a macos subdirectory cp macos/appicon.icns chip8e.app/Contents/Resources/ cp macos/PkgInfo chip8e.app/Contents/ cp macos/Info.plist chip8e.app/Contents/
And with this, running make bundle should create a app bundle that is fully self-contained and can be double-clicked to open the SDL2 program.
When running this app yourself, no messages pop up and it simply runs. However, this is because it was compiled on the same system. When someone else tries to run it, they will run into security messages and can't run the app.
On macOS, running apps without any execution-blocking security messages requires the app to be both signed and notarized (which requires signing), which requires a paid ($100 / year) Apple developer account. How this works and to do this are outside the scope for this post (my budget, really).
Running an unsigned app says that the developer is unknown, and running a signed, but not notarized app says that it could not be checked for malware. Both of these do not have a 'open'-button. Additionally, if an app is signed, but was later changed (and therefore has the signature broken), a message saying that the app is damaged shows up, which has a 'move to trash' button.
Althoguh most sources talk about bypassing these messages with the privacy-panel in System Preferences, the easiest way is to right-click the app and choose open in the context menu instead.
This will still pop up a message, but now an 'open' button is also available.
The app does need to have been attempted to open at least once before the 'open' button will show up, though.
Also, running apps straight from the Downloads folder causes extra restrictions on what files it can access, so moving it somewhere else might be required too.
If you plan to distribute the app but don't intend on signing and notarizing it, it might be a good idea to indicate that this is required to run the app.
Note that on Big Sur, a message about not having permission to open the app can occur, and although there are various possible solution to this, I wasn't able to get them to work for a friend who is on Big Sur. It looks like this was a Big Sur bug, as it works as expected on Monterey.
In a followup post, I explain making file-opening ('open-with' and such) work within macOS.