/* This file is part of Magnum. Copyright © 2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019, 2020, 2021, 2022, 2023 Vladimír Vondruš Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. */ namespace Magnum { /** @page platforms-ios iOS @brief Building, testing and deploying apps for Apple iOS platforms @tableofcontents @m_footernavigation @m_keyword{Apple iOS,,} With Apple decision to focus on Metal, iOS OpenGL ES support is stuck on version 3.0 (i.e., a version before compute shaders are available). Moreover, OpenGL ES is deprecated since iOS 12. See also @ref Platform::Sdl2Application for more information, majority of the @ref platforms-macos "macOS platform-specific info" applies here as well. @section platforms-ios-bundle Bundle creation Unlike on macOS, where applications can also run directly from a compiled executable, on iOS you are required to create a bundle. The bundle setup is similar to macOS, see the @ref platforms-macos-bundle "macOS platform guide" for details. Compared to macOS, the `*.plist` file controls many more options (such as HiDPI/Retina support, supported display orientation, icons, splash screen...). CMake uses its own template that can be configured using various `MACOSX_BUNDLE_*` variables, but the builtin file is tailored for macOS and you are much better off rolling your own template and passing **abosolute** path to it to CMake using the `MACOSX_BUNDLE_INFO_PLIST` property: @code{.cmake} if(CORRADE_TARGET_IOS) set_target_properties(my-application PROPERTIES MACOSX_BUNDLE ON MACOSX_BUNDLE_INFO_PLIST ${CMAKE_CURRENT_SOURCE_DIR}/MacOSXBundleInfo.plist.in) endif() @endcode Below are contents of the `*.plist` file as is used in the @ref Platform-Sdl2Application-bootstrap-ios "SDL2 bootstrap application", requesting OpenGL ES 2.0 and advertising Retina support: @code{.xml} CFBundleDevelopmentRegion en-US CFBundleExecutable ${MACOSX_BUNDLE_EXECUTABLE_NAME} CFBundleIdentifier cz.mosra.magnum.MyApplication CFBundleInfoDictionaryVersion 6.0 CFBundleName My Application CFBundlePackageType APPL UIRequiredDeviceCapabilities opengles-2 NSHighResolutionCapable @endcode Again, see [the official Apple Property List file documentation](https://developer.apple.com/library/content/documentation/General/Reference/InfoPlistKeyReference/Articles/AboutInformationPropertyListFiles.html) for information about all options. @section platforms-ios-native-resolution Running at native resolution In order to run at a native resolution on iOS, you need to add a Launch Screen Storyboard. A `LaunchScreen.storyboard` file can be generated from Xcode as shown in [Apple documentation](https://developer.apple.com/documentation/xcode/specifying-your-apps-launch-screen), you also can find a sample file [here](https://gist.github.com/hsdk123/ee940c1dd21a2055e7d1df5111dbedaa) or [here](https://github.com/Microsoft/appcenter-sampleapp-xamarin/blob/master/iOS/LaunchScreen.storyboard). Then, do the following in CMake: @todoc figure out what the heck is all the cruft in the file, check if it's possible to trim it down and then paste it here verbatim @code{.cmake} target_sources(my-application PRIVATE path/to/LaunchScreen.storyboard) set_property(SOURCE path/to/LaunchScreen.storyboard PROPERTY MACOSX_PACKAGE_LOCATION "Resources/LaunchScreen.storyboard") @endcode You may also want to add this to your `*.plist` file: @code{.xml} UILaunchStoryboardName LaunchScreen @endcode @section platforms-ios-xcode Xcode @subsection platforms-ios-xcode-cmake CMake can't find a compiler Right after installing Xcode for the first time, CMake might fail with a message saying > No CMAKE_CXX_COMPILER could be found. In order to fix this, you need to run this command: @code{.sh} sudo xcode-select -s /Applications/Xcode.app/Contents/Developer @endcode @section platforms-ios-deploying Deploying iOS apps @subsection platform-ios-deploying-signing Application signing Apps have to be signed in order to run on iPhone. After generating the CMake project, you'll have no code signing set up. In the Xcode go to the *General* properties for given app target and enable automatic signing. First time you do this for an account, you'll need to set up a certificate. Also note that in case of free developer accounts, you have only a low limit of different bundle IDs to install & launch in a day (usually just 10). Once you reach the limit (for example when running a lot of test executables), you'll be prevented from using new ones. A possible workaround is to reuse a bundle ID from an existing app. @subsection platform-ios-deploying-certificate Certificate trusting When deploying with a developer account for given device for a first time, you'll be prompted to verify your Developer Account. In the iPhone Settings, go to *General* -> *Profiles & Device Management* and *trust* your certificate there. @subsection platform-ios-deploying-target Deployment target Generated Xcode projects by default require the iOS version to be matching the iPhone SDK version. If you need to make the app running on older devices, set the `CMAKE_OSX_DEPLOYMENT_TARGET` to desired version: @code{.sh} cmake . -DCMAKE_OSX_DEPLOYMENT_TARGET=10.1 # iOS 10.1 at least @endcode @section platforms-ios-best-practices Best practices Official Apple documentation: - [Best Practices for Working with Vertex Data](http://developer.apple.com/library/ios/#documentation/3DDrawing/Conceptual/OpenGLES_ProgrammingGuide/TechniquesforWorkingwithVertexData/TechniquesforWorkingwithVertexData.html) - [Best Practices for Working with Texture Data](http://developer.apple.com/library/ios/#documentation/3DDrawing/Conceptual/OpenGLES_ProgrammingGuide/TechniquesForWorkingWithTextureData/TechniquesForWorkingWithTextureData.html) - [Best Practices for Shaders](http://developer.apple.com/library/ios/#documentation/3DDrawing/Conceptual/OpenGLES_ProgrammingGuide/BestPracticesforShaders/BestPracticesforShaders.html#//apple_ref/doc/uid/TP40008793-CH7-SW3) @section platforms-ios-troubleshooting Troubleshooting - GLSL @glsl texelFetch() @ce returns zero results if you have a texture with integer type and the filtering is not @ref SamplerFilter::Nearest. Yes, it shouldn't matter, but it does. @todoc https://cmake.org/cmake/help/v3.8/prop_gbl/XCODE_EMIT_EFFECTIVE_PLATFORM_NAME.html and `$` property and https://gitlab.kitware.com/cmake/cmake/merge_requests/404, doesn't work for me on 3.10 and xcode 9.2 on Travis :/ @todoc CMake -G Xcode, testsuite integration, bundling, controlling xcode properties from cmake @todoc CORRADE_TESTSUITE_BUNDLE_IDENTIFIER_PREFIX @todoc alternatives - including *.a files manually in your xcode project @todoc move stuff from Sdl2App @todoc static plugins @todoc ci setup */ }