Qt Documentation

Qt 5.8
Platform Notes - iOS

Platform Notes - iOS

Deployment

Developing, building, running, and debugging a Qt for iOS application can all be done with Qt Creator on macOS. The toolchain is provided by Apple's Xcode, and running qmake on a project targeted for iOS will also generate an Xcode project file (.xcodeproj), with initial application settings. As Qt Creator does not provide an interface for managing all of the settings specific to iOS platform, it is sometimes necessary to adjust them in Xcode directly. Checking that the application is configured correctly is especially important before submitting an application for publishing in Apple's App Store.

Information Property List Files

Information property list file (Info.plist) on iOS and macOS is used for configuring an application bundle. These configuration settings include:

Application display name and identifier
Required device capabilities
Supported user interface orientations
Icons and launch images

See the documentation on Information Property List File in iOS Developer Library for details.

When qmake is run, an Info.plist file is generated with appropriate default values.

It is advisable to replace the generated Info.plist with your own copy, to prevent it from being overwritten the next time qmake is run. You can define a custom information property list with QMAKE_INFO_PLIST variable in your .pro file.

ios {
    QMAKE_INFO_PLIST = ios/Info.plist
}

Application Assets

For files that cannot be bundled into Qt resources, QMAKE_BUNDLE_DATA qmake variable provides a way to specify a set of files to be copied into the application bundle. For example:

ios {
    fontFiles.files = fonts/*.ttf
    fontFiles.path = fonts
    QMAKE_BUNDLE_DATA += fontFiles
}

For image resources, an alternative way is to make use of asset catalogs in Xcode, which can be added in a similar way:

ios {
    assets_catalogs.files = $$files($$PWD/*.xcassets)
    QMAKE_BUNDLE_DATA += assets_catalogs
}

Important: resources are compiled only if the .path variable is not set. It is possible to recursively copy and compile directories though.

Icons

Icons need to be set in the Info.plist and copied to the application bundle. Xcode has special support for icons, but when using Qt, it is usually better to set them in the .pro file.

To support all resolutions and devices, several images should be created. A detailed list of what is required is available at Icon files. The filename is not important, but the actual pixel size is. Just a few icons are required. However, to support both iPhone and iPad, the following images are required:

AppIcon29x29.png: 29 x 29
[email protected]: 58 x 58
AppIcon29x29@2x~ipad.png: 58 x 58
AppIcon29x29~ipad.png: 29 x 29
[email protected]: 80 x 80
AppIcon40x40@2x~ipad.png: 80 x 80
AppIcon40x40~ipad.png: 40 x 40
AppIcon50x50@2x~ipad.png: 100 x 100
AppIcon50x50~ipad.png: 50 x 50
AppIcon57x57.png: 57 x 57
[email protected]: 114 x 114
[email protected]: 120 x 120
AppIcon72x72@2x~ipad.png: 144 x 144
AppIcon72x72~ipad.png: 72 x 72
AppIcon76x76@2x~ipad.png: 152 x 152
AppIcon76x76~ipad.png: 76 x 76

These files should be copied to the application bundle by adding something like the following code snippet to the .pro file:

ios {
    ios_icon.files = $$files($$PWD/ios/AppIcon*.png)
    QMAKE_BUNDLE_DATA += ios_icon
}

For the icons to be used, the filenames also have to be listed in the Info.plist. The best way is to list all icon files using the CFBundleIconFiles key. The iPad specific version can be given using the CFBundleIcons~ipad key, by adding something like the following code snippet to Info.plist:

<key>CFBundleIcons</key>
<dict>
    <key>CFBundlePrimaryIcon</key>
    <dict>
        <key>CFBundleIconFiles</key>
        <array>
            <string>AppIcon29x29.png</string>
            <string>[email protected]</string>
            <string>[email protected]</string>
            <string>AppIcon57x57.png</string>
            <string>[email protected]</string>
            <string>[email protected]</string>
        </array>
    </dict>
</dict>
<key>CFBundleIcons~ipad</key>
<dict>
    <key>CFBundlePrimaryIcon</key>
    <dict>
        <key>CFBundleIconFiles</key>
        <array>
            <string>AppIcon29x29.png</string>
            <string>[email protected]</string>
            <string>[email protected]</string>
            <string>AppIcon57x57.png</string>
            <string>[email protected]</string>
            <string>[email protected]</string>
            <string>AppIcon29x29~ipad.png</string>
            <string>AppIcon29x29@2x~ipad.png</string>
            <string>AppIcon40x40~ipad.png</string>
            <string>AppIcon40x40@2x~ipad.png</string>
            <string>AppIcon50x50~ipad.png</string>
            <string>AppIcon50x50@2x~ipad.png</string>
            <string>AppIcon72x72~ipad.png</string>
            <string>AppIcon72x72@2x~ipad.png</string>
            <string>AppIcon76x76~ipad.png</string>
            <string>AppIcon76x76@2x~ipad.png</string>
        </array>
    </dict>
</dict>

This ensures that the appropriate files are copied to the right place and the correct icons are used as required by the Apple App Store. Ad-hoc distributions should also include the following filenames in the application bundle to visualize the application in iTunes:

iTunesArtwork 512x512
iTunesArtwork@2x 1024x1024

Launch Images

Like icons, launch images consist of images that need to be copied to the application bundle and keys that have to be set in the Info.plist.

To support the iPhone 6, a launch file (an interface builder .xib file or a storyboard file) should be provided. For more information, see Launch Images. Assuming that you called the launch file Launch.xib, it can be added to the Info.plist as follows:

<key>UILaunchStoryboardName</key>
<string>Launch</string>

It is possible to use launch images (PNG files), as described below, to support the iPhone 6, but it is not recommended. Qmake generates a default LaunchScreen.xib, so it is better to use another name for a custom launch screen to avoid clashes.

Starting with iOS 7, the launch images are defined using the UILaunchImages key. To support these devices, you need to prepare the following images:

[email protected]: 640 x 1136
LaunchImage-iOS7-Landscape.png: 1024 x 768
[email protected]: 2048 x 1536
LaunchImage-iOS7-Portrait.png: 768 x 1024
[email protected]: 1536 x 2048
[email protected]: 640 x 960

The images can be added to the Info.plist as follows:

<key>UILaunchImages</key>
<array>
    <dict>
        <key>UILaunchImageMinimumOSVersion</key>
        <string>7.0</string>
        <key>UILaunchImageName</key>
        <string>LaunchImage-iOS7</string>
        <key>UILaunchImageOrientation</key>
        <string>Portrait</string>
        <key>UILaunchImageSize</key>
        <string>{320, 568}</string>
    </dict>
    <dict>
        <key>UILaunchImageMinimumOSVersion</key>
        <string>7.0</string>
        <key>UILaunchImageName</key>
        <string>LaunchImage-iOS7</string>
        <key>UILaunchImageOrientation</key>
        <string>Portrait</string>
        <key>UILaunchImageSize</key>
        <string>{320, 480}</string>
    </dict>
</array>
<key>UILaunchImages~ipad</key>
<array>
    <dict>
        <key>UILaunchImageMinimumOSVersion</key>
        <string>7.0</string>
        <key>UILaunchImageName</key>
        <string>LaunchImage-iOS7-Landscape</string>
        <key>UILaunchImageOrientation</key>
        <string>Landscape</string>
        <key>UILaunchImageSize</key>
        <string>{768, 1024}</string>
    </dict>
    <dict>
        <key>UILaunchImageMinimumOSVersion</key>
        <string>7.0</string>
        <key>UILaunchImageName</key>
        <string>LaunchImage-iOS7-Portrait</string>
        <key>UILaunchImageOrientation</key>
        <string>Portrait</string>
        <key>UILaunchImageSize</key>
        <string>{768, 1024}</string>
    </dict>
    <dict>
        <key>UILaunchImageMinimumOSVersion</key>
        <string>7.0</string>
        <key>UILaunchImageName</key>
        <string>LaunchImage-iOS7</string>
        <key>UILaunchImageOrientation</key>
        <string>Portrait</string>
        <key>UILaunchImageSize</key>
        <string>{320, 568}</string>
    </dict>
    <dict>
        <key>UILaunchImageMinimumOSVersion</key>
        <string>7.0</string>
        <key>UILaunchImageName</key>
        <string>LaunchImage-iOS7</string>
        <key>UILaunchImageOrientation</key>
        <string>Portrait</string>
        <key>UILaunchImageSize</key>
        <string>{320, 480}</string>
    </dict>
</array>

To support earlier iOS versions, one can use the UILaunchImageFile string in the Info.plist:

<key>UILaunchImageFile</key>
<string>LaunchImage</string>

The name defaults to Default, but qmake generates some of the images, so it is easier to use another name (for example LaunchImage as we did) to avoid clashes.

LaunchImage.png: 320 x 480
[email protected]: 640 x 960
[email protected]: 640 x 1136
LaunchImage-Landscape.png: 1024 x 748
[email protected]: 2048 x 1496
LaunchImage-Portrait.png: 768 x 1004
[email protected]: 1536 x 2008

You can change the filenames as long as the Info.plist and filenames stay in sync.

Finally, all these files have to be copied to the application bundle by adding something like the following code snippet to the .pro file:

ios {
    app_launch_images.files = $$PWD/ios/Launch.xib $$files($$PWD/ios/LaunchImage*.png)
    QMAKE_BUNDLE_DATA += app_launch_images
}

This allows you to produce universal applications with valid LaunchImages as required by the Apple App Store.

Important: "launch_images" is used internally by Qt, so it will be overwritten if used in your .pro file.

Publishing to Apple App Store

Verifying that your Qt for iOS application is ready for publishing to App Store can be done as described in Submitting the Application. To submit the application, you can use Xcode, or the Application Loader (installed with Xcode). Qt Creator does not provide an interface for managing all of the settings in an Xcode project configuration.

The application should be tested on a variety of iOS versions and devices, depending on what it's targeted to support. The minimum deployment target for Qt applications is iOS 7.0.

The actual publishing process involves creating a distribution certificate and a provision profile, creating a signed archive of your application, and running a set of validation tests on it.

See the App Distribution Guide in iOS Developer Library for more information.

© 2017 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.