Skip to content

Restructuring the iOS readme #13836

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 1 commit into from
+67 −20
Closed

Restructuring the iOS readme #13836

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
87 changes: 67 additions & 20 deletions docs/README-ios.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,9 +12,58 @@ Instructions:
2. Select your desired target, and hit build.


Using the Simple DirectMedia Layer for iOS
Using the Simple DirectMedia Layer for iOS with the SDL3 xcFramework
==============================================================================

The recommended way to use SDL for iOS is by including the SDL3.xcframework which is now a build target of the SDL.xcodeproj file. An xcframework is a new (Xcode 11) uber-framework which can handle any combination of processor type and target OS platform.
You can either build the SDL3.xcframework yourself or download the latest release disk image asset (*.dmg).

In the past, iOS devices were always an ARM variant processor, and the simulator was always i386 or x86_64, and thus libraries could be combined into a single framework for both simulator and device. With the introduction of the Apple Silicon ARM-based machines, regular frameworks would collide as CPU type was no longer sufficient to differentiate the platform. So Apple created the new xcframework library package.

The xcframework target builds into a Products directory alongside the SDL.xcodeproj file, as SDL3.xcframework. This can be brought in to any iOS project and will function properly for both simulator and device, no matter their CPUs. Note that Intel Macs cannot cross-compile for Apple Silicon Macs. If you need AS compatibility, perform this build on an Apple Silicon Mac.

This target requires Xcode 11 or later. The target will simply fail to build if attempted on older Xcodes.

In addition, on Apple platforms, main() cannot be in a dynamically loaded library.
However, unlike in SDL2, in SDL3 SDL_main is implemented inline in SDL_main.h, so you don't need to link against a static libSDL3main.lib, and you don't need to copy a .c file from the SDL3 source either.
This means that iOS apps which used the statically-linked libSDL3.lib and now link with the xcframwork can just `#include <SDL3/SDL_main.h>` in the source file that contains their standard `int main(int argc, char *argv[])` function to get a header-only SDL_main implementation that calls the `SDL_RunApp()` with your standard main function.

To use the SDL3.xcframework follow these steps:

1. Run Xcode and create a new project using the iOS Game template, selecting the Objective C language and Metal game technology.
2. In the main view, delete all files except for Assets and LaunchScreen
3. Select the project in the main view, go to the "General" tab, scroll down to "Frameworks, Libraries, and Embedded Content", and drag and drop the SDL3.xcframework
4. Still in "Frameworks, Libraries, and Embedded Content", select "Embed & Sign" for the SDL3.xcframework.
5. Add the source files that you would normally have for an SDL program, making sure to have #include <SDL3/SDL_main.h> at the top of the file containing your main() function.
6. Add any assets that your application needs.
7. Enjoy!

Using an xcFramework is similar to using a regular framework. However, issues have been seen with the build system not seeing the headers in the xcFramework. To remedy this, add the path to the xcFramework in your app's target ==> Build Settings ==> Framework Search Paths and mark it recursive (this is critical). Also critical is to remove "*.framework" from Build Settings ==> Sub-Directories to Exclude in Recursive Searches. Clean the build folder, and on your next build the build system should be able to see any of these in your code, as expected:

#include "SDL3/SDL_main.h"
#include <SDL3/SDL.h>
#include <SDL3/SDL_main.h>

Notes for distributing your iOS app on the AppStore when using the SDL3.xcframework:
To distribute your app you need to generate the DWARF debug symbols for the SDL3.xcframework. Also by embedding the Xcode project the SDL3 framework is now a target that gets archived along with your app in the Archive step needed for submitting your app to the AppStore. This will prevent your ability to distribute your app so you need to delete the framework after the "Embed & Sign" step of building your app.
To do both via a script:

1. Select the project in the main view, go to the "Build Phases" tab, click on the big '+' in this tab and click "New Run Script Phase".
2. Scroll down to "Run Script" (after the "Embed Frameworks") and enter the following script:
```
if [ -d "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/SDL3.framework" ]; then
echo "Generating dSYM for SDL3.framework"
dsymutil "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/SDL3.framework/SDL3" -o "${BUILT_PRODUCTS_DIR}/SDL3.framework.dSYM"
fi
```
3. Below the script entry uncheck the "Run Script:" options "For install builds only" and "Based on dependency analysis"


Using the Simple DirectMedia Layer for iOS by adding the SDL3 Xcode project
==============================================================================

To maintain compatibility with older Xcode versions than version 11 you can add the SDL3 Xcode project file to your project:

1. Run Xcode and create a new project using the iOS Game template, selecting the Objective C language and Metal game technology.
2. In the main view, delete all files except for Assets and LaunchScreen
3. Right click the project in the main view, select "Add Files...", and add the SDL project, Xcode/SDL/SDL.xcodeproj
Expand All @@ -26,6 +75,23 @@ Using the Simple DirectMedia Layer for iOS
9. Add any assets that your application needs.
10. Enjoy!

Notes for distributing your iOS app on the AppStore when using the embedded SDL3 Xcode project:
Similar to when using the SDL3.xcframework you need to generate the DWARF debug symbols. Also by embedding the Xcode project the SDL3 framework is now a target that gets archived along with your app in the Archive step needed for submitting your app to the AppStore. This will prevent your ability to distribute your app so you need to delete the framework after the "Embed & Sign" step of building your app.
To do both via a script:

1. Select the project in the main view, go to the "Build Phases" tab, click on the big '+' in this tab and click "New Run Script Phase".
2. Scroll down to "Run Script" (after the "Embed SDL3 Framework") and enter the following script:
```
if [ -d "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/SDL3.framework" ]; then
echo "Generating dSYM for SDL3.framework"
dsymutil "${BUILT_PRODUCTS_DIR}/${FRAMEWORKS_FOLDER_PATH}/SDL3.framework/SDL3" -o "${BUILT_PRODUCTS_DIR}/SDL3.framework.dSYM"
fi
if [ -d "$INSTALL_ROOT/Library" ]; then
echo "Removing SDL3.framework from INSTALL_ROOT for archiving"
rm -rf "$INSTALL_ROOT/Library"
fi
```
3. Below the script entry uncheck the "Run Script:" options "For install builds only" and "Based on dependency analysis"

TODO: Add information regarding App Store requirements such as icons, etc.

Expand Down Expand Up @@ -154,26 +220,7 @@ More information on this subject is available here:
http://developer.apple.com/library/ios/#documentation/iPhone/Conceptual/iPhoneOSProgrammingGuide/Introduction/Introduction.html


Notes -- xcFramework
==============================================================================

The SDL.xcodeproj file now includes a target to build SDL3.xcframework. An xcframework is a new (Xcode 11) uber-framework which can handle any combination of processor type and target OS platform.

In the past, iOS devices were always an ARM variant processor, and the simulator was always i386 or x86_64, and thus libraries could be combined into a single framework for both simulator and device. With the introduction of the Apple Silicon ARM-based machines, regular frameworks would collide as CPU type was no longer sufficient to differentiate the platform. So Apple created the new xcframework library package.

The xcframework target builds into a Products directory alongside the SDL.xcodeproj file, as SDL3.xcframework. This can be brought in to any iOS project and will function properly for both simulator and device, no matter their CPUs. Note that Intel Macs cannot cross-compile for Apple Silicon Macs. If you need AS compatibility, perform this build on an Apple Silicon Mac.

This target requires Xcode 11 or later. The target will simply fail to build if attempted on older Xcodes.

In addition, on Apple platforms, main() cannot be in a dynamically loaded library.
However, unlike in SDL2, in SDL3 SDL_main is implemented inline in SDL_main.h, so you don't need to link against a static libSDL3main.lib, and you don't need to copy a .c file from the SDL3 source either.
This means that iOS apps which used the statically-linked libSDL3.lib and now link with the xcframwork can just `#include <SDL3/SDL_main.h>` in the source file that contains their standard `int main(int argc, char *argv[])` function to get a header-only SDL_main implementation that calls the `SDL_RunApp()` with your standard main function.

Using an xcFramework is similar to using a regular framework. However, issues have been seen with the build system not seeing the headers in the xcFramework. To remedy this, add the path to the xcFramework in your app's target ==> Build Settings ==> Framework Search Paths and mark it recursive (this is critical). Also critical is to remove "*.framework" from Build Settings ==> Sub-Directories to Exclude in Recursive Searches. Clean the build folder, and on your next build the build system should be able to see any of these in your code, as expected:

#include "SDL_main.h"
#include <SDL.h>
#include <SDL_main.h>


Notes -- iPhone SDL limitations
Expand Down
Loading