Remarques sur la plateforme - iOS

Déploiement

Le développement, la compilation, l'exécution et le débogage d'une application Qt pour iOS peuvent tous être effectués à l'aide d'Qt Creator sur macOS. La chaîne d'outils est fournie par Xcode d'Apple, et l'exécution de qmake ou de CMake sur un projet destiné à iOS génère également un fichier de projet Xcode (.xcodeproj), contenant les paramètres initiaux de l'application. Comme Qt Creator ne propose pas d’interface permettant de gérer l’ensemble des paramètres spécifiques à la plateforme iOS, il est parfois nécessaire de les ajuster directement dans Xcode. Il est particulièrement important de vérifier que l’application est correctement configurée avant de la soumettre pour publication sur l’App Store d’Apple.

Ensembles d’applications

Les applications iOS sont généralement déployées sous forme de paquets d'application autonomes. Le paquet d'application contient l'exécutable de l'application ainsi que ses dépendances, telles que les bibliothèques Qt, les plugins, les traductions et les autres ressources dont l'application peut avoir besoin.

Pour compiler votre application sous forme de bundle avec CMake, définissez la MACOSX_BUNDLE propriété de votre cible exécutable comme suit :

qt_add_executable(MyApp)
if(APPLE)
    set_target_properties(MyApp PROPERTIES MACOSX_BUNDLE TRUE)
endif()

Avec qmake, les bundles sont activés par défaut. Définissez « CONFIG -= app_bundle » dans votre fichier de projet (.pro) pour les désactiver.

Fichiers de liste de propriétés d’information

Le fichier de liste de propriétés d’informations (Info.plist) sous iOS et macOS sert à configurer un bundle d’application. Ces paramètres de configuration comprennent :

• Le nom d'affichage et l'identifiant de l'application
• Les capacités requises de l'appareil
• Les orientations d'interface utilisateur prises en charge
• Les icônes et les images de lancement

Pour plus de détails, consultez la documentation sur le fichier de liste de propriétés d’information dans la bibliothèque des développeurs iOS.

Fichier Info.plist avec CMake

CMake génère un fichier « Info.plist » par défaut si la propriété « MACOSX_BUNDLE » d’une cible est définie sur « TRUE ». Malheureusement, ce fichier n’est pas adapté aux projets iOS.

À la place, les projets peuvent utiliser ` qt_add_executable`, qui générera automatiquement un fichier ` Info.plist ` avec des valeurs par défaut adaptées aux projets iOS.

Pour spécifier un fichier ` Info.plist` personnalisé, les projets peuvent définir la propriété ` MACOSX_BUNDLE_INFO_PLIST ` de la cible comme indiqué ci-dessous. Cela désactivera la génération automatique de fichiers fournie par `qt_add_executable` et utilisera à la place la gestion native de CMake pour le fichier ` Info.plist ` fourni par le projet.

qt_add_executable(app)
if(IOS)
    set_target_properties(app
        PROPERTIES MACOSX_BUNDLE_INFO_PLIST "${CMAKE_CURRENT_SOURCE_DIR}/ios/Info.plist")
endif()

Consultez la documentation CMake relative à MACOSX_BUNDLE_INFO_PLIST pour savoir quelles propriétés de cible et variables peuvent être spécifiées pour la substitution de modèles effectuée par CMake.

Info.plist avec QMake

Lorsque qmake est exécuté, un fichier ` Info.plist ` est généré avec les valeurs par défaut appropriées.

Il est conseillé de remplacer le fichier Info.plist généré par votre propre copie, afin d'éviter qu'il ne soit écrasé lors de la prochaine exécution de qmake. Vous pouvez définir une liste de propriétés d'informations personnalisée à l'aide de la variable QMAKE_INFO_PLIST dans votre fichier .pro.

ios {
    QMAKE_INFO_PLIST = ios/Info.plist
}

Ressources de l'application

Pour les fichiers qui ne peuvent pas être intégrés aux ressources Qt, la variable qmake QMAKE_BUNDLE_DATA permet de spécifier un ensemble de fichiers à copier dans le bundle de l'application. Par exemple :

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

Avec CMake, cela peut être réalisé de la manière suivante :

qt_add_executable(app)
file(GLOB_RECURSE font_files CONFIGURE_DEPENDS "fonts/*.ttf")
if(IOS AND font_files)
    target_sources(app PRIVATE ${font_files})
    set_source_files_properties(
        ${font_files}
        PROPERTIES MACOSX_PACKAGE_LOCATION Resources/fonts)
endif()

Pour les ressources d'images, une autre solution consiste à utiliser les catalogues de ressources dans Xcode, qui peuvent être ajoutés de la manière suivante avec qmake :

ios {
    QMAKE_ASSET_CATALOGS += ios/Assets.xcassets
}

Avec CMake :

qt_add_executable(app)
set(asset_catalog_path "ios/Assets.xcassets")
target_sources(app PRIVATE "${asset_catalog_path}")
set_source_files_properties(
    ${asset_catalog_path}
    PROPERTIES MACOSX_PACKAGE_LOCATION Resources)

Icônes

À partir de Xcode 13, les icônes doivent être ajoutées à l’ensemble d’icônes d’un catalogue de ressources, généralement nommé « AppIcon ». Xcode se chargera ensuite de mettre à jour le fichier « Info.plist » avec les clés et les valeurs appropriées, ainsi que de copier tous les fichiers d’icônes nécessaires directement dans le bundle de l’application.

À partir de Xcode 14, une seule image de 1 024 × 1 024 pixels est requise. Xcode se charge de générer toutes les icônes nécessaires à partir de celle-ci. Il est également possible de spécifier les images manuellement dans le catalogue de ressources.

Une liste détaillée des icônes pouvant être spécifiées est disponible à la page Fichiers d’icônes.

Le nom du fichier n'a pas d'importance, mais la taille réelle en pixels est essentielle. Pour prendre en charge une application iOS universelle, les images suivantes sont requises :

• AppIcon60x60@2x.png: 120 x 120 (pour l'iPhone)
• AppIcon76x76@2x~ipad.png: 152 x 152 (pour l'iPad)
• AppIcon167x167.png: 167 x 167 (pour l'iPad Pro)
• AppIcon1024x1024.png: 1 024 x 1 024 (pour l'App Store)

Les distributions ad hoc doivent également inclure les noms de fichiers suivants dans le bundle de l'application afin de permettre la visualisation de l'application dans iTunes :

• iTunesArtwork 512 x 512
• iTunesArtwork@2x 1024 x 1024

La manière la plus simple d'ajouter ces icônes consiste à suivre les instructions de la documentation Xcode dans la section « Créer des catalogues et des ensembles de ressources ».

Lors de la compilation d'un projet avec CMake, il convient également de spécifier l'attribut Xcode suivant afin de garantir que les icônes de l'application soient générées par Xcode.

set_target_properties(app_target_name PROPERTIES
    XCODE_ATTRIBUTE_ASSETCATALOG_COMPILER_APPICON_NAME AppIcon)

Voici un exemple de ce à quoi pourrait ressembler un fichier « Assets.xcassets/AppIcon.appiconset/Contents.json » pour Xcode 14 :

{
  "images" : [
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "20x20"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "3x",
      "size" : "20x20"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "29x29"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "3x",
      "size" : "29x29"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "38x38"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "3x",
      "size" : "38x38"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "40x40"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "3x",
      "size" : "40x40"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "60x60"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "3x",
      "size" : "60x60"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "64x64"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "3x",
      "size" : "64x64"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "68x68"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "76x76"
    },
    {
      "idiom" : "universal",
      "platform" : "ios",
      "scale" : "2x",
      "size" : "83.5x83.5"
    },
    {
      "filename" : "AppIcon1024x1024.png",
      "idiom" : "universal",
      "platform" : "ios",
      "size" : "1024x1024"
    }
  ],
  "info" : {
    "author" : "xcode",
    "version" : 1
  }
}

Écrans de démarrage et images de démarrage

Écrans de démarrage

Toute application iOS doit fournir un écran de lancement qui s'affiche lors du démarrage de l'application. Un écran de lancement est un fichier « .xib » créé dans Interface Builder, également appelé fichier « storyboard ». Pour plus d'informations, consultez la section « Spécification de l'écran de lancement de votre application ».

La prise en charge des écrans de lancement a été introduite dans iOS 9.0.

qmake et CMake génèrent tous deux un écran de lancement par défaut nommé « LaunchScreen.storyboard ».

Pour définir un écran de lancement personnalisé, celui-ci doit être copié dans le bundle de l'application, et la clé UILaunchStoryboardName doit être définie sur le nom de l'écran de lancement dans le fichier Info.plist.

Qt prend en charge les écrans de lancement personnalisés avec CMake depuis la version 6.4 de Qt, et avec qmake depuis la version 6.0 de Qt.

En supposant que le fichier de démarrage s'appelle Launch.storyboard, il peut être ajouté à Info.plist comme suit :

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

Pour copier l'écran de lancement dans le bundle de l'application avec qmake, utilisez l'extrait de code suivant dans le fichier .pro de votre projet :

ios {
    QMAKE_IOS_LAUNCH_SCREEN = $$PWD/Launch.storyboard
}

Avec CMake :

qt_add_executable(app)
if(IOS)
    set_target_properties(app PROPERTIES
        QT_IOS_LAUNCH_SCREEN "${CMAKE_CURRENT_SOURCE_DIR}/Launch.storyboard")
endif()

Images de démarrage

Il est également possible de spécifier des images de démarrage (fichiers PNG) à la place de l'écran de démarrage.

Les images de lancement doivent être copiées dans le bundle de l'application et leurs noms doivent être définis dans le fichier ` Info.plist ` à l'aide de la clé ` UILaunchImages `.

Les images suivantes doivent être préparées :

• LaunchImage-iOS7-568h@2x.png : 640 x 1136
• LaunchImage-iOS7-Landscape.png : 1 024 x 768
• LaunchImage-iOS7-Landscape@2x.png : 2048 x 1536
• LaunchImage-iOS7-Portrait.png : 768 x 1024
• LaunchImage-iOS7-Portrait@2x.png : 1 536 x 2 048
• LaunchImage-iOS7@2x.png : 640 x 960

Les images peuvent être ajoutées à Info.plist comme suit :

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

Pour copier les images de démarrage dans le bundle de l’application à l’aide de qmake, utilisez l’extrait de code suivant dans le fichier .pro de votre projet :

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

Avec CMake :

qt_add_executable(app)
file(GLOB_RECURSE launch_images CONFIGURE_DEPENDS "ios/LaunchImage*.png")
if(IOS AND launch_images)
    target_sources(app PRIVATE ${launch_images})
    set_source_files_properties(
        ${launch_images}
        PROPERTIES MACOSX_PACKAGE_LOCATION Resources)
endif()

Sélecteur d’images natif

Si votre fichier ` Info.plist ` contient une entrée pour ` NSPhotoLibraryUsageDescription`, qmake inclura automatiquement un plugin supplémentaire permettant d'accéder au sélecteur d'images natif.

Pour CMake, liez manuellement le sélecteur d'images natif à l'aide de qt_import_plugins:

qt_import_plugins(app INCLUDE Qt6::QIosOptionalPlugin_NSPhotoLibraryPlugin)

Si le répertoire indiqué dans votre fichier ` QFileDialog ` est défini comme suit :

QStandardPaths::standardLocations(QStandardPaths::PicturesLocation).last();

ou bien si l’ currentFolder dans un fichier FileDialog en QML est définie comme suit :

shortcuts.pictures

le sélecteur d’images natif s’affiche alors pour permettre l’accès à l’album photo de l’utilisateur.

Spécification des versions iOS prises en charge

Les plateformes Apple disposent d’un mécanisme intégré permettant d’indiquer les versions du système d’exploitation prises en charge par une application. Cela permet aux anciennes versions de ces plateformes d’afficher automatiquement un message d’erreur convivial invitant l’utilisateur à mettre à jour son système d’exploitation, plutôt que de planter et d’afficher une trace de pile.

Les principaux concepts liés à l'indication de la prise en charge d'une plage spécifique de versions du système d'exploitation sont les suivants :

• La cible de déploiement spécifie la version minimale absolue de macOS ou d’iOS prise en charge par votre application.
• La version du SDK spécifie la version maximale ( non contraignante ) de macOS ou d’iOS prise en charge par votre application.

Lorsque vous développez une application pour une plateforme Apple, vous devez toujours utiliser la dernière version de Xcode et le dernier SDK disponible au moment du développement. Sur certaines plateformes, comme iOS, votre application sera en effet rejetée par l’App Store si vous ne le faites pas. Par conséquent, la version du SDK est toujours supérieure ou égale à la cible de déploiement.

Lorsque vous développez une application pour une plateforme Apple, vous devez définir la cible de déploiement. Divers outils de compilation de la chaîne d’outils Xcode disposent tous d’un indicateur que vous pouvez utiliser pour définir cette valeur, notamment le compilateur et l’éditeur de liens. En définissant la valeur de la cible de déploiement, vous déclarez explicitement que votre application doit fonctionner au moins sur cette version et qu’elle ne fonctionnera pas avec des versions antérieures du système d’exploitation. Il vous appartient alors de vous assurer que votre utilisation des API système correspond bien à ce que vous avez déclaré. Comme le compilateur connaît ce que vous avez déclaré, il peut vous aider à faire respecter cette consigne.

La version du SDK est considérée comme une version maximale indicative du système d’exploitation avec laquelle une application est compatible, en ce sens que si l’application est compilée avec un SDK, elle continuera à utiliser les comportements de ce SDK même sur des versions plus récentes du système d’exploitation, car celui-ci vérifie les commandes de chargement du binaire et émule la rétrocompatibilité avec les versions antérieures du système d’exploitation. Par exemple, si une application est compilée avec le SDK macOS 10.12, elle continuera à utiliser les comportements de la version 10.12 même sous 10.13 et les versions ultérieures.

Cependant, les binaires Mach-O sont intrinsèquement compatibles en aval. Par exemple, une application développée avec le SDK iOS 9 fonctionnera parfaitement sous iOS 10, mais ne bénéficiera peut-être pas des modifications de comportement éventuellement apportées à certaines fonctionnalités de la nouvelle version, tant que cette application n’aura pas été recompilée avec ce SDK plus récent.

La version minimale du système d’exploitation peut être indiquée au système via les options du compilateur et de l’éditeur de liens qui l’intègrent dans le binaire Mach-O. De plus, la clé « LSMinimumSystemVersion » doit être définie dans le bundle de l’application. Cette valeur doit être identique à celle transmise au compilateur et à l’éditeur de liens, car sous macOS, cela permettra au système d’afficher une boîte de dialogue d’erreur conviviale indiquant que l’application nécessite une version plus récente du système d’exploitation, plutôt qu’une boîte de dialogue de plantage. La clé « LSMinimumSystemVersion » est également celle utilisée par l’App Store pour afficher la version requise du système d’exploitation ; les indicateurs du compilateur et de l’éditeur de liens n’ont aucune incidence à ce niveau.

Dans la plupart des cas, les applications Qt fonctionneront sans problème. Par exemple, dans qmake, les mkspecs Qt définissent QMAKE_IOS_DEPLOYMENT_TARGET ou QMAKE_MACOSX_DEPLOYMENT_TARGET sur la version minimale prise en charge par Qt lui-même. De même, dans Qbs, les modules Qt définissent cpp.minimumIosVersion, cpp.minimumMacosVersion, cpp.minimumTvosVersion ou cpp.minimumWatchosVersion sur la version minimale prise en charge par Qt lui-même.

Cependant, vous devez faire preuve de prudence lorsque vous définissez manuellement votre propre version cible. Si vous la définissez sur une valeur supérieure à celle requise par Qt et que vous fournissez votre propre fichier ` Info.plist `, vous devez ajouter une entrée ` LSMinimumSystemVersion ` au fichier ` Info.plist ` qui corresponde à la valeur de la cible de déploiement, car le système d’exploitation utilisera la valeur ` LSMinimumSystemVersion ` comme valeur de référence.

Si vous spécifiez une valeur de « deployment target » inférieure à celle requise par Qt, l’application plantera presque certainement au niveau des bibliothèques Qt lorsqu’elle sera exécutée sur une version plus ancienne que celle prise en charge par Qt. Par conséquent, assurez-vous que le code réel du système de compilation reflète la version minimale du système d’exploitation qui est effectivement requise.

Publication sur l’App Store d’Apple

Vous pouvez vérifier que votre application Qt pour iOS est prête à être publiée sur l’App Store en suivant les instructions décrites dans la section « Soumettre l’application ». Pour soumettre l’application, vous pouvez utiliser Xcode ou l’Application Loader (installé avec Xcode). Qt Creator ne fournit pas d’interface permettant de gérer tous les paramètres de configuration d’un projet Xcode.

L'application doit être testée sur les versions d'iOS et les appareils qu'elle est censée prendre en charge. La cible de déploiement minimale pour les applications Qt varie selon la version de Qt. Pour plus d'informations, consultez la section « Configurations prises en charge ».

Le processus de publication proprement dit consiste à créer un certificat de distribution et un profil de provisionnement, à générer une archive signée de votre application, puis à y effectuer une série de tests de validation.

Pour plus d’informations, consultez le Guide de distribution des applications dans la Bibliothèque des développeurs iOS.

Avertissements relatifs à la visibilité des symboles

Dans le cadre de la liaison de bibliothèques C++, les fonctions et les objets sont appelés « symboles ». Les symboles peuvent avoir une visibilité « default » ou « hidden ».

Pour des raisons de performances, Qt et de nombreuses autres bibliothèques compilent leurs sources en utilisant par défaut la visibilité « hidden » et ne marquent les symboles avec la visibilité « default » que lorsqu'ils sont destinés à être utilisés dans les projets des utilisateurs.

Malheureusement, l’éditeur de liens Apple peut générer des avertissements lorsqu’une bibliothèque est compilée avec la visibilité « hidden » et qu’une application ou une bibliothèque d’un projet utilisateur est compilée avec la visibilité « default ».

Si les développeurs du projet souhaitent désactiver cet avertissement, ils doivent également compiler le code de leur projet avec une visibilité « hidden ».

Dans CMake, cela peut être réalisé en ajoutant le code suivant à votre fichier ` CMakeLists.txt` :

set(CMAKE_CXX_VISIBILITY_PRESET hidden)

Dans qmake, cela peut être fait en ajoutant le code suivant à votre fichier ` .pro ` :

CONFIG+=hide_symbols

Si un projet compile des bibliothèques, tous les symboles de la bibliothèque destinés à être utilisés dans une autre bibliothèque ou application devront être explicitement marqués comme « default s ». Par exemple, cela peut être fait en annotant ces fonctions ou classes avec Q_DECL_EXPORT.

Problème d’archivage du produit avec CMake

En raison d’un problème dans CMake, la création d’une archive de produit avec une application iOS peut échouer.

Cela peut se produire aussi bien lors de la création de l'archive dans Xcode via le menu « Product » → « Archive », que depuis la ligne de commande à l'aide de la commande « xcodebuild -archivePath ».

Le message d'erreur peut faire référence à des symboles non définis ou à des chemins d'accès à des fichiers inexistants.

Pour contourner ce problème, veillez à compiler une version « Release » du projet avant d’essayer de créer une archive.

Ensemble dSYM manquant dans l'archive xcarchive créée par un projet CMake Xcode

En raison d'un bug dans Xcode et de certaines limitations de CMake, un projet Xcode généré par CMake ne parviendra pas à inclure le bundle « dSYM » de l'application dans l'xcarchive, lors de la tâche d'archivage de Xcode.

Qt propose une solution de contournement optionnelle permettant d’inclure le bundle « dSYM » dans l’ xcarchive, mais celle-ci comporte des inconvénients. En effet, les fonctionnalités CMake suivantes ne fonctionneront pas correctement :

• toute expression de générateur de ` $<TARGET_FILE:app> ` risque de se développer en un chemin d’accès invalide ne menant pas au binaire de l’application
• la variable CMAKE_RUNTIME_OUTPUT_DIRECTORY et la propriété de cible associée RUNTIME_OUTPUT_DIRECTORY seront ignorées même si elles sont définies
• d'autres problèmes inconnus

Pour pallier les problèmes ci-dessus, vous pouvez :

• n'activer la solution de contournement que lorsque vous avez l'intention de créer l'xcarchive, et non pendant le développement du projet
• veiller à n'ajouter des exécutables et des bibliothèques que dans le répertoire racine du projet, et non dans les appels d'add_subdirectory.

Pour activer cette solution de contournement, configurez le projet à l'aide de l'option suivante :

cmake . -DQT_USE_RISKY_DSYM_ARCHIVING_WORKAROUND=ON

ou définissez la variable dans le projet avant tout appel à ` qt_add_executable ` ou ` qt_add_library ` :

set(QT_USE_RISKY_DSYM_ARCHIVING_WORKAROUND ON)

...

qt_add_executable(app)