This project provide a CMake macro to help you deploy Qt Application for iOS. This macro replace all kind of stuff QMake is doing under the hood and add lots of options to customize Info.plist
.
- Correctly link to all qt libraries. Optimization can be done here.
- Link with required framework. Optimization can be done here.
- Redirect entry point to create UIApplication before regular
main()
. - Generate
Info.plist
with inputs - Sign the XCode Generated project
The main goal is to build the app without any change inside XCode.
This utility has been developed for my own needs. Don't hesitate to use / share / fork / modify / improve it freely :)
This project is conceptually based on the great QtAndroidCMake of Laurent Gomila.
The Application QQuickMaterialHelperGallery showcase the use of this library. See QtIosCMake call in platform/PostBuildPlatform.cmake
and iOs ressources in platform/ios/
. See QtStaticCMake call in CMakeLists.txt
All you have to do is to call the add_qt_ios_app
macro. No additionnal target will be generated, only the main target property are going to change. Of course this is not enough and you'll need to add extract arguments.
IF(${CMAKE_SYSTEM_NAME} STREQUAL "iOS")
INCLUDE(QtIosCMake/AddQtIosApp.cmake)
add_qt_ios_app(MyApp)
ENDIF()
Prerequisite:
- Be on recent version of macOs.
- Latest Version of XCode.
- Qt compiled for iOs as static library.
- iOs CMake Toolchain.
- Generate Qt Import Plugin statement. See these macros.
- An Apple Developer Licence if you want to deploy on real device.
If you installed official Qt binary, Qt Sdk binary is located in:
export QT_USER_ID=$(id -un)
export QT_IOS_VERSION=5.12.0
export QT_IOS_DIR=/Users/$QT_USER_ID/Qt/$QT_IOS_VERSION/ios
Then simply run CMake with this toolchain. Read the toolchain README for more information.
cmake -DCMAKE_PREFIX_PATH=$QT_IOS_DIR \
-DDEPLOYMENT_TARGET=11.0 \
-DCMAKE_TOOLCHAIN_FILE=/path/to/ios.toolchain.cmake \
-DPLATFORM=OS64COMBINED \
-DENABLE_BITCODE=FALSE \
-G "XCode" \
path/to/Projet/
Then you can simply build your app:
cmake --build . --config Release
Notes
- OS64COMBINED is only available if you are using CMake 3.14+.
- Generator XCode is required to sign app and create a bundle app.
- Qt 5.12:
- If you use prebuild qt ios library, then bitcode is disabled.
- Library is build with minimum Os support 11.0. You need to do the same.
- You can also specify
QT_IOS_CODE_SIGN_IDENTITY
andQT_IOS_TEAM_ID
when running CMake because these variables are rarely inside theCMakeLists.txt
.
The first argument is the executable target that will become an app.
The macro also accepts optional named arguments. Any combination of these arguments is valid. Example:
add_qt_ios_app(MyApp
NAME "My App"
BUNDLE_IDENTIFIER "com.company.app"
VERSION "1.2.3"
SHORT_VERSION "1.2.3"
LONG_VERSION "1.2.3.456"
CUSTOM_PLIST "path/to/MacOSXBundleInfo.plist.in"
CODE_SIGN_IDENTITY "iPhone Developer"
TEAM_ID "AAAAAAAA"
COPYRIGHT "My Cool Copyright"
QML_DIR "${QT_IOS_QT_ROOT}/qml"
ASSET_DIR "path/to/Assets.xcassets"
MAIN_STORYBOARD "/path/to/Main.storyboard"
LAUNCHSCREEN_STORYBOARD "path/to/LaunchScreen.storyboard"
CATALOG_APPICON "AppIcon"
CATALOG_LAUNCHIMAGE "LaunchImage"
ORIENTATION_PORTRAIT
ORIENTATION_PORTRAIT_UPSIDEDOWN
ORIENTATION_LANDSCAPELEFT
ORIENTATION_LANDSCAPERIGHT
SUPPORT_IPHONE
SUPPORT_IPAD
REQUIRES_FULL_SCREEN
HIDDEN_STATUS_BAR
VERBOSE
)
Here is the full list of possible arguments:
NAME
The bundle display name is the name displayed underneath the application icon. This value should be localized for all supported languages. If not given, the name of the source target is taken. The default is ${TARGET}
. This is the name displayed on the os. This is the equivalent of the Display Name field under General XCode.
Example:
add_qt_ios_app(MyApp
NAME "My App"
)
BUNDLE_IDENTIFIER
The application bundle identifier. A bundle identifier lets iOS and macOS recognize any updates to your app. Your bundle ID must be registered with Apple and be unique to your app. Bundle IDs are app-type specific (either iOS or macOS). The same bundle ID cannot be used for both iOS and macOS apps.
Bundle identifiers are usually (not always) written out in reverse DNS notation (com.myCompany.myApp
).
Example:
add_qt_ios_app(MyApp
BUNDLE_IDENTIFIER "com.myCompany.myApp"
)
VERSION
The string that specifies the build version number of the bundle. This value is a monotonically increased string, comprised of one or more period-separated integers. This value can correspond to either released or unreleased versions of the application. This value cannot be localized. The default is 1.0.0
.
Example:
add_qt_ios_app(MyApp
VERSION "1.2.3"
)
SHORT_VERSION
The release version of the application. The value of this key is a string comprised of three period-separated integers. This is default to VERSION.
Example:
add_qt_ios_app(MyApp
SHORT_VERSION "1.2.3"
)
LONG_VERSION
The release version of the application that usualy include the build number. This is default to VERSION.
Example:
add_qt_ios_app(MyApp
LONG_VERSION "1.2.3"
)
CUSTOM_PLIST
It is possible to specify a custom pList file. The default is MacOSXBundleInfo.plist.in
. CMake include a basic template here. Qt also add some recommendation, read more about it here. The file in this repository is a variant of the CMake ones that have more configurable field from CMake. If you use your own plist.in
some feature of this macro won't work anymore. Don't forget to copy in your file:
Orientation
<!-- Ui Orientation -->
<key>UISupportedInterfaceOrientations</key>
<array>
<string>${MACOSX_BUNDLE_PORTRAIT}</string>
<string>${MACOSX_BUNDLE_LANDSCAPELEFT}</string>
<string>${MACOSX_BUNDLE_LANDSCAPERIGHT}</string>
</array>
<key>UISupportedInterfaceOrientations~ipad</key>
<array>
<string>${MACOSX_BUNDLE_PORTRAIT}</string>
<string>${MACOSX_BUNDLE_PORTRAITUPDOWN}</string>
<string>${MACOSX_BUNDLE_LANDSCAPELEFT}</string>
<string>${MACOSX_BUNDLE_LANDSCAPERIGHT}</string>
</array>
RequireFullScreen
<!-- Full screen, allow multi task or not -->
<key>UIRequiresFullScreen</key>
<string>${MACOSX_BUNDLE_REQUIRES_FULL_SCREEN}</string>
StatusBarHidden
<!-- Hide the status bar -->
<key>UIStatusBarHidden</key>
<${MACOSX_BUNDLE_HIDDEN_STATUS_BAR}/>
LaunchStoryboard
<!-- If supporting multitask LaunchScreen.storyboard must be provided -->
<key>UILaunchStoryboardName</key>
<string>${MACOSX_BUNDLE_LAUNCHSCREEN_STORYBOARD}</string>
MainStoryboard
<!-- Optionnal StoryBoard filename -->
<key>UIMainStoryboardFile</key>
<string>${MACOSX_BUNDLE_MAIN_STORYBOARD}</string>
Example:
add_qt_ios_app(MyApp
CUSTOM_PLIST "path/to/Info.plist.in"
)
The pList file can also be a file that isn't gonna be configured it's gonna work the same way.
CODE_SIGN_IDENTITY
Code signing is required in order to deploy to real ios device (ie non simulator). More info here. By default "iPhone Developer". Possible values are:
"iPhone Developer"
"iPhone Distribution"
Example:
add_qt_ios_app(MyApp
CODE_SIGN_IDENTITY "iPhone Developer"
)
TEAM_ID
The team id used to sign the application. By default "AAAAAAAA."
You can see possible values by executing:
/usr/bin/env xcrun security find-identity -v -p codesigning
Example:
add_qt_ios_app(MyApp
TEAM_ID "AAAAAAAA"
)
COPYRIGHT
Set the copyright in the info.plist. Optional
Example:
add_qt_ios_app(MyApp
COPYRIGHT "Cool Copyright 2019"
)
QML_DIR
Used to link with qml libs. By default it is set to qt sdk qml dir but you can specify your own.
Example:
add_qt_ios_app(MyApp
QML_DIR "path/to/qml"
)
ASSET_DIR
You can specify with this variable one or multiples asset dir to be package with the app.
CATALOG_APPICON
Specify the AppIcon folder inside your Assets folder. By Default "AppIcon".
CATALOG_LAUNCHIMAGE
Specify the AppIcon folder inside your Assets folder. By Default "LaunchImage".
LAUNCHSCREEN_STORYBOARD
Specify the file to use as LaunchScreen Storyboard. This file will be bundle into the App. This is mandatory to support Split Screen if REQUIRES_FULL_SCREEN
isn't set.
MAIN_STORYBOARD
This file seems to be optionnal is you use only Qt/Qml.
Set the Main Storyboard of your app. The file will also be bundled.
ORIENTATION
The default allowed orientation can be set with flags:
ORIENTATION_PORTRAIT
: Set UIInterfaceOrientationPortrait flag.ORIENTATION_PORTRAIT_UPSIDEDOWN
: Set UIInterfaceOrientationPortraitUpSideDown flag.ORIENTATION_LANDSCAPELEFT
: Set UIInterfaceOrientationLandscapeLeft flag.ORIENTATION_LANDSCAPERIGHT
: Set UIInterfaceOrientationLandscapeRight flag.
SUPPORTED DEVICES
You can specify supported device either iPhone or iPad or both by settings:
SUPPORT_IPHONE
: Set by default
SUPPORT_IPAD
: If set and you want to keep iPhone you also need to specify SUPPORT_IPHONE
When the two flags are specified deployment will result in Universal.
REQUIRES_FULL_SCREEN
This flag disable the multitask feature. By doing so LaunchScreen.storyboard
become optionnal.
HIDDEN_STATUS_BAR
Set UIStatusBarHidden
to true.
VERBOSE
Print all debug information. Usefull to check if configuration is ok.
- On iPhone X+ the app doesn't show in full screen, you need to add
flags: Qt.MaximizeUsingFullscreenGeometryHint
to your main Qml window. - On iOs Qt is statically linked which mean you need to import by hand required plugins. Or you can use the macro in QtStaticCMake.
- Generate Qt Plugin import source file.
- Generate Qt Qml Plugin import source file.
- Add Correct linker to load platform library
qios
.
Tested with XCode 10.2.1, Qt5.12.0, iOs 12.2.
- Option to specify additional framework.
- Add iOs capabilities. Wifi, Background Mode, Hotspot Configuration, Multipath, NFC, Notification, ...
- Never tried to add ObjC.
- Access to Native Image Picker.
- Qt For Ios
- Qt Platform Notes
- QtStaticCMake
- Ios CMake Toolchain from leethal
- Ios helloworld project
- XCode flag example
- Apple Bundle Docs
- Deploy on App Store
- App Distribution Guide
- Olivier Le Doeuff: olivier.ldff@gmail.com