Le build du simulateur échoue avec « building for iOS Simulator but linking iOS arm64 » dès qu’une dépendance binaire ne correspond pas à la plateforme visée.

Solution la plus rapide : repérez la bibliothèque citée dans l’erreur, puis mettez à jour son XCFramework ou reconstruisez-le avec une tranche iOS Simulator. N’excluez pas durablement arm64 par réflexe : cette architecture peut servir au simulateur sur Apple silicon, et la masquer ne fournit pas la tranche de plateforme manquante.

Cet article s’adresse aux développeurs iOS qui rencontrent le problème après une migration vers Apple silicon, aux équipes utilisant des bibliothèques précompilées ou des SDK tiers, ainsi qu’aux personnes chargées de produire et maintenir des XCFramework.

Interpréter l’erreur Xcode de liaison iOS Simulator sans confondre plateforme et architecture

Le texte de l’erreur décrit une incompatibilité entre ce que le build demande et ce que le fichier binaire fournit. « iOS Simulator » indique la plateforme de destination ; « iOS » désigne ici la plateforme pour laquelle l’objet lié a été construit. Le terme arm64, à lui seul, ne suffit donc pas à conclure que le processeur n’est pas pris en charge.

C’est une distinction importante sur un Mac Apple silicon : une même famille d’instructions peut être utilisée pour une cible d’appareil et pour une cible de simulateur, sans que leurs bibliothèques soient interchangeables. Les métadonnées de plateforme du binaire comptent autant que son architecture. La note technique d’Apple sur les erreurs de construction liées à Apple silicon décrit notamment le cas d’une bibliothèque précompilée qui ne contient pas la tranche attendue pour le simulateur.

Avant de modifier les réglages du projet, relevez dans le journal complet du build :

  • le nom du fichier ou de la bibliothèque mentionnée après « linking » ;
  • le target Xcode qui échoue ;
  • la destination sélectionnée, par exemple un simulateur ou un appareil connecté ;
  • le chemin du binaire effectivement résolu par le projet.

Cette vérification évite de corriger le mauvais élément. Une erreur peut provenir d’une dépendance indirecte intégrée par un SDK, même si le nom du framework de premier niveau semble compatible. Elle peut aussi toucher une seule cible, tandis que les autres targets du projet continuent de compiler.

Pourquoi une bibliothèque arm64 pour appareil ne se lie-t-elle pas nécessairement au simulateur ? Parce que arm64 renseigne sur l’architecture du code, pas à lui seul sur la plateforme et l’environnement de compilation pour lesquels le binaire a été produit. Une tranche compilée pour iOS sur appareil ne devient pas une tranche iOS Simulator parce que son architecture porte le même nom. Les explications d’Apple sur la création d’un binaire multiplateforme au format XCFramework montrent justement l’intérêt de regrouper des variantes correspondant aux plateformes et destinations prises en charge.

Le diagnostic dépend du contenu réel de la dépendance

La première vérification consiste à déterminer si le binaire fautif est un XCFramework ou une bibliothèque distribuée sous une autre forme. Un XCFramework peut contenir des variantes distinctes pour l’appareil et pour le simulateur ; le simple fait que son nom contienne « iOS » ne prouve pas que la variante nécessaire au simulateur soit présente. La documentation Apple sur les frameworks binaires distribués comme paquets Swift rappelle également que le paquetage doit fournir les binaires appropriés aux destinations annoncées.

Pour un XCFramework, examinez son Info.plist et les entrées de bibliothèques qu’il décrit. Vérifiez notamment les plateformes déclarées et, lorsqu’il y a lieu, la variante de simulateur. Dans le cas d’une archive statique ou d’un framework traditionnel, les outils d’inspection de l’architecture peuvent donner des indices, mais ils ne remplacent pas la vérification de la plateforme de compilation : deux binaires arm64 peuvent ne pas être interchangeables.

Il faut ensuite distinguer l’origine de la dépendance :

  • Bibliothèque ou SDK tiers précompilé : vérifiez les versions disponibles auprès de son fournisseur et les plateformes effectivement annoncées. Si la tranche simulateur manque, la correction durable est une version qui la fournit, ou une alternative compatible.
  • Bibliothèque statique construite dans votre projet : reprenez son processus de compilation en visant explicitement la plateforme simulateur, puis produisez un paquetage qui distingue les variantes nécessaires.
  • Dépendance issue des sources : assurez-vous que le système de compilation la reconstruit pour la destination sélectionnée, au lieu de réutiliser un artefact précompilé destiné à l’appareil.

Que faire si un SDK tiers ne fournit pas de tranche Simulator arm64 ? Demandez une version du SDK dont les artefacts prennent explicitement en charge les simulateurs Apple silicon, ou vérifiez si le fournisseur propose un XCFramework contenant les variantes appareil et simulateur requises. Si aucune version compatible n’existe, vous pouvez solliciter une reconstruction ou remplacer la dépendance. Ne supposez pas qu’une tranche d’appareil convient simplement parce qu’elle est elle aussi en arm64.

Choisir une correction selon la plateforme réellement fournie

Le tableau ci-dessous compare les voies de correction selon leur portée. L’appréciation est éditoriale : elle indique leur adéquation au diagnostic, et non un résultat de performance mesuré.

Option Quand elle convient Limite à vérifier Appréciation
Mettre à jour la dépendance Le fournisseur publie une version avec les variantes nécessaires au simulateur Confirmer que la nouvelle version couvre aussi les appareils et les cibles utilisées Recommandée en priorité
Reconstruire un XCFramework Vous contrôlez les sources ou le processus de compilation de la bibliothèque Produire et déclarer les variantes correspondant à chaque plateforme visée Recommandée si vous maîtrisez la chaîne de build
Exclure arm64 pour une cible précise Une contrainte documentée empêche temporairement l’usage de cette architecture dans cette configuration La modification peut empêcher d’autres builds ou masquer le problème sans fournir la tranche manquante Contournement provisoire
Remplacer la dépendance Aucune version compatible n’est disponible et la bibliothèque bloque la livraison Évaluer les API, la licence et les conséquences de migration À envisager si le fournisseur ne peut pas corriger

Pour fabriquer un XCFramework à partir de composants que vous êtes autorisé à compiler et distribuer, la procédure doit produire des binaires adaptés aux destinations retenues, puis les réunir dans le paquetage. La documentation Apple sur la création d’un binaire multiplateforme détaille ce modèle. Ne vous contentez pas de réunir deux fichiers portant la même architecture : leurs destinations de compilation doivent correspondre aux plateformes annoncées.

EXCLUDED_ARCHS peut-il corriger l’erreur d’architecture du simulateur ? Parfois, mais seulement comme mesure circonscrite, lorsque vous avez établi que le problème concerne une architecture précise et que la configuration de remplacement est effectivement prise en charge. Ce réglage ne transforme pas un binaire iOS appareil en binaire iOS Simulator. Il peut aussi reporter l’échec sur une autre destination ou rendre une cible indisponible. Apple documente la portée des réglages dans sa référence des paramètres de build Xcode : vérifiez leur niveau d’application et les valeurs héritées avant de changer le projet.

Si vous testez cette voie, limitez la modification au target et à la configuration concernés, plutôt que de l’appliquer globalement. Comparez le résultat avec les réglages initiaux et consignez le contournement comme temporaire, avec la version de dépendance qui le rend nécessaire. Si le build simulateur passe mais que le build appareil échoue ensuite, le réglage n’a pas résolu le défaut de compatibilité : il a déplacé la frontière de l’échec.

Procédure de dépannage et de validation

Suivez les étapes dans cet ordre. Il permet de préserver la preuve du problème avant de modifier des paramètres susceptibles de masquer sa cause.

  • [ ] Reproduisez l’échec dans la configuration concernée. Sélectionnez le target et la destination qui échouent, puis relancez le build. Conservez le journal complet, pas seulement la ligne de résumé.
  • [ ] Identifiez le binaire nommé dans l’erreur. Notez le chemin réellement résolu et remontez, si nécessaire, jusqu’au SDK ou à la dépendance qui le fournit. Vérifiez aussi les dépendances indirectes.
  • [ ] Inspectez les variantes disponibles. Pour un XCFramework, consultez ses métadonnées et comparez les plateformes déclarées à la destination du build. Pour une bibliothèque construite en interne, retrouvez les paramètres et le produit de compilation d’origine.
  • [ ] Confirmez la nature du problème. Si l’architecture requise est présente mais que la plateforme annoncée ne correspond pas, ne concluez pas à un simple défaut d’architecture. Si la variante du simulateur manque, demandez une version appropriée ou reconstruisez la bibliothèque à partir des sources disponibles.
  • [ ] Appliquez la correction la moins large. Mettez à jour la dépendance ou reconstruisez son XCFramework avant d’envisager un réglage d’architecture. Si un contournement est indispensable, limitez-le au target concerné et documentez pourquoi il est nécessaire.
  • [ ] Construisez pour le simulateur. Utilisez la destination réellement en cause et vérifiez que le journal ne fait plus référence au binaire incompatible. Ne vous fiez pas seulement à l’absence d’une erreur au premier plan : contrôlez le target qui a effectivement été construit.
  • [ ] Construisez ensuite pour un appareil iOS. Cette vérification confirme que la correction n’a pas rendu inutilisable la variante appareil ou modifié à tort les réglages partagés.
  • [ ] Consignez les éléments permettant de reproduire le résultat. Gardez la version de la dépendance, la provenance de l’artefact, le target, la destination et le changement de réglage. Lors d’une mise à jour d’outillage ou de SDK, ces informations facilitent la comparaison avec un build antérieur.

Apple distingue les destinations d’exécution dans sa documentation sur la construction et l’exécution d’une app sur un simulateur ou un appareil. Le passage du build simulateur au build appareil n’est donc pas une formalité : ce sont deux validations complémentaires de la prise en charge des destinations revendiquées par la dépendance.

Pour éviter qu’une mise à jour réintroduise le problème, associez à chaque artefact binaire sa version et sa provenance, puis exécutez les builds des destinations réellement utilisées avant de valider le changement. Si un SDK est distribué par un gestionnaire de dépendances, vérifiez que le paquet récupéré correspond bien à la version attendue et que le projet n’utilise pas parallèlement une copie locale plus ancienne.

Une autre machine ou un environnement isolé peut aider à déterminer si l’échec dépend d’un artefact local obsolète, d’un cache ou de réglages propres à votre installation. Cela ne remplace toutefois pas l’examen des métadonnées : si le binaire ne contient pas la variante simulateur requise, le même défaut réapparaîtra ailleurs. Pour préparer l’accès à une machine distante, consultez les informations sur l’accès à distance par VNC ; pour une session de test séparée, vous pouvez également examiner la location d’un Mac mini proposée par SSHMac.

Si vos builds échouent uniquement sur la machine habituelle, que son état local rend le diagnostic incertain ou que vous devez confirmer la reproductibilité sur un environnement distinct, une machine isolée peut compléter vos vérifications. Votre poste actuel peut conserver des caches anciens, des réglages hérités ou une installation d’outils différente de celle des autres développeurs ; une autre machine ne corrige pas une tranche manquante, mais permet de séparer un problème d’environnement d’un défaut du binaire. À l’inverse, si vous avez besoin d’une charge soutenue et prévisible au quotidien, ou d’interfaces physiques particulières, une location ponctuelle n’est pas forcément adaptée. Lorsque vous avez seulement besoin de reproduire et valider le build sur un environnement Mac distinct, SSHMac peut fournir cette possibilité sans présenter le changement de machine comme un remède à la compatibilité du XCFramework.