Porting to iOS

In this section, we are going to port an existing Qt application to iOS and deploy it to the device.

Most Qt applications should be portable to iOS with ease, unless they depend on a specific hardware or software feature not supported on iOS. A major part of the porting effort consists of ensuring that all the application's assets (for example, QML files, images, and icons) are deployed correctly to the device.

Like most UI applications, Qt applications also depend on resources such as images, icons, translation files, and so on. These resources must be made available on the device as they are required for the application to function correctly.

The most convenient option is to bundle the resources into a qrc file, which gets built into the application binary. This approach reduces the porting effort considerably and provides faster access to the resources. It is also a cross-platform approach, which makes porting to other platforms easier.

By default, all Qt applications can access the contents of a qrc file using the ":/" prefix or the URL scheme prefix, "qrc:". To know more about qrc files and how they are handled, see the Qt Resource System.

The following step-by-step instructions guide you to port an existing Qt Quick application to iOS using the qrc approach:

1. Open the existing project in Qt Creator and configure it with iOS or iOS Simulator kit. For more information, see Qt Creator: Configuring Projects.
2. Update all local directory imports in the qml files to use a local namespace. For example, to import the QML documents in the "contents" directory relative to main.qml, use the following import statement:

    import "contents" as Contents
   

3. Identify all the resources used by your application and add them to one or more qrc files. Qt Creator updates your qmake project file with the RESOURCES variable, listing the qrc files you added.
4. To load or refer to the resources in the qrc file from a C++ file, use the "qrc:" prefix for the URL. For example:

    QQuickView viewer;
    viewer.setSource(QUrl("qrc:qml/main.qml"));
    viewer.show();
   

   Note: QML documents can refer to files in the resources simply by using the relative path to the document. Such references do not require the "qrc:" or ":/" prefix.

5. Update the "Run" settings for your project as described in the Qt Creator: Specifying Run Settings
6. If your application uses imports or plugins that depend on special Qt modules, these Qt modules should be added to your build configuration file. For example, if your application uses the Qt Multimedia import in QML, you should add the following to your .pro or CMakeLists.txt file:
   

   Using CMake

    find_package(Qt6 REQUIRED COMPONENTS Multimedia)
    target_link_libraries(my_project PRIVATE Qt6::Multimedia)
   

   Using qmake

    QT += multimedia
   

   In Qt for iOS, everything is compiled statically and placed into the application bundle. The applications are "sandboxed" inside their bundles and cannot make use of shared object files. Because of this, also the plugins used by the Qt modules need to be statically linked. To do this, define the required plugins using the QTPLUGIN variable.

7. Save the changes to your project and run the application.

Qt Creator deploys your application on the iOS device, if the device is detected and configured correctly in Xcode. It is also possible to test the application in iOS Simulator. For more information, see Connecting iOS Devices.