search

OlivierLDff / QtIosCMake

📱 Deploy Qt Application for iOS with a single macro when using CMake.
BSD 3-Clause "New" or "Revised" License
58 stars 15 forks source link
cmake cpp ios qml qt qt5 qtquick qtquick-controls2 static

readme

Qt iOS CMake

What it is

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.

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.

Showcase

The Application QaterialGallery showcase the use of this library. See QtIosCMake call in platforms/Deploy.cmake and iOs resources in platforms/ios/. See QtStaticCMake call in platforms/Deploy.cmake.

The application also demonstrate full CI pipeline with Github Actions.

How to use it

How to integrate it to your CMake configuration

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()

How to run CMake

Prerequisite:

If you installed official Qt binary, Qt Sdk binary is located in:

export QT_USER_ID=$(id -un)
export QT_IOS_VERSION=5.15.2
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=12.0 \
-DCMAKE_TOOLCHAIN_FILE=/path/to/ios.toolchain.cmake \
-DPLATFORM=OS64COMBINED \
-DENABLE_BITCODE=FALSE \
-G "Xcode" \
path/to/Projet/

To sign your app you need at least a team id and a signing identity. I recommand you to override those variable when doing the cmake command, and not writting them inside your cmake scripts. This will give you more control when configuring the project.

Then you can simply build your app:

cmake --build . --config Release

Notes

target_link_libraries(MyApp PUBLIC "-framework Foundation -framework AVFoundation -framework SystemConfiguration -framework AssetsLibrary -framework OpenGLES \
    -framework CoreText -framework QuartzCore -framework CoreGraphics -framework ImageIO -framework Security -framework UIKit -framework WebKit \
    -framework CoreBluetooth -framework MobileCoreServices -framework QuickLook -framework AudioToolbox -framework CoreLocation \
    -framework Accelerate -framework CoreMedia -framework CoreVideo -framework MediaToolbox -framework MediaPlayer -framework GameController
    -framework CoreMotion -framework StoreKit -weak_framework Metal -lz")

Options of the add_qt_ios_app macro

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"
    PROVISIONING_PROFILE_SPECIFIER "my-profile"
    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_UPDOWN
    ORIENTATION_LANDSCAPE_LEFT
    ORIENTATION_LANDSCAPE_RIGHT
    PHOTO_LIBRARY_USAGE_DESCRIPTION "My App needs to access your photo library."
    SUPPORT_IPHONE
    SUPPORT_IPAD
    REQUIRES_FULL_SCREEN
    HIDDEN_STATUS_BAR
    IPA
    UPLOAD_SYMBOL
    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"
)

ScDisplayName

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).

If not specified, the default value is ${CMAKE_PROJECT_NAME}.${TARGET}.

Example:

add_qt_ios_app(MyApp
    BUNDLE_IDENTIFIER "com.myCompany.myApp"
)

ScBundleIdentifier

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 ${CMAKE_PROJECT_VERSION} is set, otherwise 1.0.0.

Example:

add_qt_ios_app(MyApp
    VERSION "1.2.3"
)

ScVersion

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_PORTRAITUPDOWN}</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"
)

ScSign

PROVISIONING_PROFILE_SPECIFIER

A provisioning profile can be generated there. If not specified, signing profile will be generated by cmake. Suitable for development but not for distribution. The BUNDLE_IDENTIFIER should match the on the the provisioning profile.

A profile hold a Certificate for an App ID for a Team Id.

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".

ScAppIconSource

CATALOG_LAUNCHIMAGE

Specify the AppIcon folder inside your Assets folder. By Default "LaunchImage".

ScLaunchImagesSource

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.

ScLaunchScreenFile

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.

ScMainInterface

ORIENTATION

The default allowed orientation can be set with flags:

ScOrientation

PHOTO LIBRARY USAGE DESCRIPTION

A message that tells the user why the app is requesting access to the user’s photo library.

Example:

add_qt_ios_app(MyApp
    PHOTO_LIBRARY_USAGE_DESCRIPTION "My App needs to access your photo library."
)

SUPPORTED DEVICES

You can specify supported device either iPhone or iPad or both by settings:

ScDeviceiPhone

ScDeviceiPad

When the two flags are specified deployment will result in Universal. This is also the default behavior.

ScDevices

REQUIRES_FULL_SCREEN

This flag disable the multitask feature. By doing so LaunchScreen.storyboard become optionnal.

ScRequiresFullScreen

HIDDEN_STATUS_BAR

Set UIStatusBarHiddento true.

ScHideStatusBar

IPA

If specified, two additional target are going to be generated.

Ipa file is the format required by App Store Connect. It can be uploaded straight to TestFlight.

When specifying IPA, additionnal parameters are available:

DISTRIBUTION_METHOD can be overwritten at configure time by specifying a -DQT_IOS_DISTRIBUTION_METHOD="ad-hoc" for example.

ITS_ENCRYPTION_EXPORT_COMPLIANCE_CODE

The export compliance code provided by App Store Connect for apps that require it. This will add a key ITSEncryptionExportComplianceCode in Info.plist.

If not provided (means you don't need it), it will create a key ITSAppUsesNonExemptEncryption to false.

This is required by Apple Connect. If this key doesn't exist in your Info.plist, you will need to fix this in Apple TestFlight website when uploading the IPA.

VERBOSE

Print all debug information. Usefull to check if configuration is ok.

Notes

Improvement Idea

Related Link

Contact