Qt for iOS

Qt for iOS enables building applications for Apple's iPhone and iPad devices, as well as the Apple Vision Pro.

To develop with Qt for iOS, follow the getting started guide; then explore examples for iOS, and related topics.

Supported Configurations

The following versions of the build environment and runtime target platform are supported by Qt 6.8.

Build Environment

The build environment for iOS is provided by Apple's Xcode application, which includes both the toolchain (compiler, linker, and other tools), and the iOS platform-SDK (headers and libraries) that you build and link against. Together these define how your application is built.

Apple generally recommend (and in the case of the App Store, require) that applications are built against the latest available SDK, so you should always be using the latest available Xcode from Apple. This may require upgrading your system's macOS version, as new Xcode versions may not run on older macOS versions.

Opting out of behavior changes

One caveat to using the latest Xcode version and SDK to build your application is that the iOS system frameworks will sometimes decide whether or not to enable behavior changes based on the SDK you built your application against.

This technique allows Apple to ensure that binaries built against older SDKs will still continue to run without regressions on newer iOS releases.

For example, when dark mode was introduced in macOS 10.14 Mojave, macOS would only treat applications built against the 10.14 SDK as supporting dark mode, and would leave applications built against earlier SDKs with the default light mode look.

Building with an older Xcode version, against an older SDK, is one way to opt out of such behavior changes, but is a last-resort solution, and should only be applied if your application has no other ways of working around the problem.

Target Platforms

Building for iOS utilizes a technique called weak linking that allows you to build your application against the headers and libraries of the latest platform SDK, while still allowing your application to be deployed to iOS versions lower than the SDK version. When the binary is run on a iOS version lower than the SDK it was built with, Qt will check at runtime whether or not a platform feature is available before utilizing it.

In theory this would allow running your application on every single iOS version released, but for practical (and technical) reasons there is a lower limit to this range, known as the deployment target of your application. If the binary is launched on a iOS version below the deployment target Qt will give an error message and the application will not run.

Qt expresses the deployment target via the CMAKE_OSX_DEPLOYMENT_TARGET or QMAKE_MACOSX_DEPLOYMENT_TARGET variables, which by default is set to the minimum supported deployment target for Qt.

You only need to raise the deployment target if your own code uses APIs that were added in a iOS version higher than what Qt defaults to, and you are not using @available checks to guard their use at runtime.

To raise the deployment target with CMake:

 set(CMAKE_OSX_DEPLOYMENT_TARGET "42.0")

or with qmake:

 QMAKE_MACOSX_DEPLOYMENT_TARGET = 42.0

For more information about SDK-based development on Apple platforms, see Apple's developer documentation.

Getting Started

Installing Xcode

Xcode is a requirement for developing with Qt for iOS. It can be installed from the App Store, or downloaded from Apple's developer website.

Once installed, please run Xcode once to let it install any required dependencies.

Then verify that the system is using the correct Xcode installation using the xcode-select tool.

 $ xcode-select -print-path
 /Applications/Xcode.app/Contents/Developer

If the output does not match the expectation, choose the Xcode installation explicitly.

 $ sudo xcode-select --switch /Applications/Xcode.app

For testing Qt applications in the simulator that comes with Xcode, this is all you need. However, for running applications on a physical device and/or publishing your applications in the App Store, you must join the Apple Developer Program, and set up developer certificates and provisioning profiles.

Before building any Qt applications, you should test that Xcode is set up correctly, for example by running one of the standard Xcode application templates on your device.

Installing or building Qt

To install or build Qt, follow the general getting started with Qt guide.

Building Applications from the Command Line

Use CMake or qmake to define how to build your iOS application. Both CMake and qmake can generate an xcodeproj file, which can then be loaded and built from the command line.

Using CMake

The qt-cmake convenience script located in <Qt-dir>/<version>/ios/bin/ will take care of setting up the toolchain and correct architectures for you.

Using qt-cmake convenience script:

 <Qt-dir>/<version>/ios/bin/qt-cmake <source-dir>

Using the generated xcodeproj file, you can either use Xcode to build your application or run xcodebuild from the command line. For a list of available targets and schemes for your application, run the following command:

 xcodebuild -list -project <your-app>.xcodeproj

Then, run xcodebuild build, passing in your application details:

 xcodebuild build -allowProvisioningUpdates -project <your-app>.xcodeproj -scheme <your-scheme> -configuration Debug -destination "generic/platform=iOS" -destination-timeout 1 ENABLE_ONLY_ACTIVE_RESOURCES=NO

Using qmake

First, define how to build the application using qmake. Then, use the generated xcodeproj file to build the application, either in Xcode or from the command line.

 qmake <your-app>.pro

qmake creates a wrapper Makefile that in turns calls xcodebuild, so you can run make to build your application:

 make -j8

Note that you must re-import the project if its setup changes, for example, when adding or removing source files.

Customizing Xcode project settings

The QMAKE_MAC_XCODE_SETTINGS qmake variable can be used to customize Xcode settings, for example:

 development_team.name = DEVELOPMENT_TEAM
 development_team.value = <your-team-id>
 QMAKE_MAC_XCODE_SETTINGS += development_team

Other qmake variables are also useful:

 QMAKE_TARGET_BUNDLE_PREFIX = com.<your-company>
 QMAKE_BUNDLE = <your-app>

Running Applications in Xcode

The Xcode projects generated by qmake and CMake support running the application on both iOS devices and in the iOS simulator.

Building and Running Applications with Qt Creator

You can find information on how to set up and run Qt for iOS applications in the Qt Creator documentation:

• Qt Creator: Connect iOS devices.

Note that this still requires a working Xcode installation.

Examples for iOS

In Qt Creator, tested examples on iOS can be looked up. Use the ios keyword to search for examples in the Qt Creator Welcome mode. Note that some examples may have limited functionality.

For a list of examples known to work on iOS devices, visit Qt for iOS Examples.

Related Topics

The following topics provide more details about Qt for iOS:

• Porting a Qt Quick Application
• Platform Notes
• Qt for iOS - Building from Source

Using Objective-C Code in Qt Applications

Clang, the compiler used for applications on Apple Platforms, allows mixing C++ and Objective-C code. To enable this mode use the .mm extension for the relevant source files and add them to your project as usual.

With CMake:

 target_sources(myapp PRIVATE objc_code.mm)

With qmake:

 SOURCES += objc_code.mm

You can then use Objective-C frameworks from Apple's Developer Library in your Qt applications.

To expose functionality to the rest of your application, without having to rename all your source files, declare helper functions in a header, and implement the functionality in an Objective-C++ source file:

 // objc_code.h
 QString localizedHostName();

 // objc_code.mm
 #include <Foundation/NSHost.h>
 QString localizedHostName()
 {
     return QString::fromNSString(NSHost.currentHost.localizedName);
 }