Xcode 27.2 Mac Catalyst : échec de compilation ? Guide de correction 2026

Erreur « identifiant non déclaré » ou « symbole introuvable » uniquement sur la cible Mac Catalyst ?

Solution la plus rapide : vérifiez si le symbole vient d’une API propre à iOS 27.1 ; si oui, isolez le code par compilation conditionnelle, puis reconstruisez séparément iOS et Mac Catalyst.

Ce guide s’adresse aux développeurs qui maintiennent du code partagé entre iOS et Mac Catalyst et veulent distinguer une frontière de plateforme d’un défaut d’outillage.
Il concerne aussi les ingénieurs de construction responsables des cibles Xcode CI et les équipes DevOps qui doivent confirmer le résultat sur leur nœud Mac réel.

Dernière mise à jour : 9 octobre 2026. L’état du problème a été vérifié dans les notes de version officielles de Xcode 27.2 et doit être réexaminé si vous passez à une autre version de Xcode.

SECTION 01Reconnaître le problème signalé

Les notes de version de Xcode 27.2 Beta 2 mentionnent un échec de compilation Mac Catalyst lié à l’utilisation d’API propres à iOS 27.1. Elles indiquent aussi des contournements par compilation conditionnelle en Swift et en Objective-C. Cette information décrit le problème signalé pour cette version bêta, pas une cause universelle des échecs Mac Catalyst. Consultez la note de version Xcode 27.2 avant de modifier votre projet.

Les messages d’erreur qui peuvent orienter l’enquête comprennent « undeclared identifier », « not found » ou « cannot find ». Ils sont des indices, pas une preuve : un nom introuvable peut aussi venir d’un module absent, d’une dépendance non résolue, d’un réglage de compilation différent ou d’une erreur de code sans rapport avec la disponibilité d’une API.

La première question n’est donc pas « le Mac distant est-il assez puissant ? », mais « quelle cible compile le code qui échoue, et quel SDK lui est associé ? ». Un défaut de résolution d’un symbole ne se corrige généralement pas en remplaçant le nœud d’exécution. Changer de machine avant d’avoir isolé la cible ajoute une variable et peut rendre le diagnostic moins reproductible.

La documentation Apple sur la création d’une version Mac d’une application iPad rappelle que Mac Catalyst est une cible distincte à prendre en compte dans le projet. Dans le diagnostic, traitez-la comme telle : la réussite de la compilation iOS ne prouve pas que toutes les API appelées par le code partagé sont disponibles dans le contexte Catalyst.

Ne transformez pas la présence d’un message « introuvable » en diagnostic automatique d’API iOS 27.1. Relevez d’abord le nom exact du symbole, le fichier concerné, la cible de compilation et la version des outils.

SECTION 02Comparer les cibles avant de toucher au code

Reproduisez l’échec sur le même commit, puis construisez iOS et Mac Catalyst sans modifier entre-temps le code ou les dépendances. Cette comparaison réduit le nombre de variables : si les deux cibles échouent, l’hypothèse d’une restriction propre à Catalyst est moins solide ; si seule Catalyst échoue, vous pouvez examiner en priorité les différences de plateforme et de configuration.

Pour chaque exécution, conservez le journal complet, pas seulement la dernière ligne affichée par l’intégration continue. Notez la version de Xcode, le SDK sélectionné, la destination de compilation et les réglages pertinents. La référence Apple des réglages de construction Xcode permet de vérifier les paramètres effectifs plutôt que de supposer qu’ils sont identiques entre le poste local et la CI.

Vérifiez ensuite le symbole en cause. Déterminez si son API est documentée pour iOS seulement ou si elle est aussi utilisable par Mac Catalyst. Examinez les imports, les en-têtes, les modules et les versions des dépendances qui fournissent ce symbole. Une API indisponible pour la cible n’est pas la même chose qu’un module que la configuration n’a pas inclus.

Un cas fréquent à examiner dans un dépôt partagé est celui d’un fichier compilé par plusieurs cibles, mais dont certaines sections appellent des API qui ne sont pas communes à ces plateformes. Le fichier peut être correct pour iOS et néanmoins impossible à compiler pour Catalyst. À l’inverse, une dépendance qui a été mise à jour sur le poste local, mais pas dans la CI, peut produire un message ressemblant à un problème d’API. Le nom de l’erreur seul ne permet pas de choisir entre ces explications.

SECTION 03Isoler les appels selon la plateforme

Lorsque l’erreur correspond bien au problème documenté, utilisez une condition de compilation adaptée à la cible. En Swift, targetEnvironment(macCatalyst) permet de distinguer l’environnement Mac Catalyst lors de la compilation. La documentation Apple décrit la compilation conditionnelle en Swift. En Objective-C, la condition TARGET_OS_MACCATALYST est le mécanisme correspondant mentionné dans les notes de version de Xcode 27.2 Beta 2.

Exemple en Swift :

#if targetEnvironment(macCatalyst)
    // Chemin propre à Mac Catalyst
#else
    // Chemin utilisé par les autres environnements concernés
#endif

Exemple en Objective-C :

#if TARGET_OS_MACCATALYST
    // Chemin propre à Mac Catalyst
#else
    // Chemin utilisé par les autres environnements concernés
#endif

Ces extraits montrent où placer une séparation, mais ne décident pas à votre place quelle branche doit appeler une API. Vous devez vous appuyer sur la disponibilité réelle du symbole et sur le comportement attendu du produit. Si le code utilise une API iOS 27.1 dans un chemin qui n’est pas valide pour Catalyst, préservez une implémentation adaptée à chaque cible ou excluez uniquement l’appel concerné.

Une vérification à l’exécution ne remplace pas une condition de compilation si le compilateur doit résoudre un symbole qui n’existe pas pour la cible en cours. Le programme peut ne jamais exécuter cette branche, mais la compilation peut tout de même échouer avant l’exécution. La séparation doit donc intervenir assez tôt pour que le compilateur ne traite pas le code incompatible pour la cible concernée.

Écarter le fichier entier de la compilation peut faire disparaître l’erreur tout en supprimant une fonctionnalité attendue sur iOS. Contrôlez la portée de chaque condition et les chemins conservés pour chaque cible avant de considérer le correctif terminé.

Le choix de la séparation dépend aussi de l’emplacement du code. Dans un fichier appartenant à l’application, vous pouvez généralement corriger directement la branche concernée. Dans un module partagé, vérifiez quels produits et quelles cibles le compilent. Pour une dépendance tierce, commencez par relever sa version exacte et le point d’entrée qui appelle le symbole ; vous devez savoir si le défaut vient du paquet, de son intégration ou de votre appel avant de modifier la résolution des dépendances.

SECTION 04Décider quoi corriger selon l’origine

Utilisez les branches de décision suivantes avant de changer l’architecture ou le nœud de CI :

• Si le même commit compile pour iOS, échoue seulement pour Mac Catalyst, et que le symbole est une API propre à iOS 27.1, alors appliquez une séparation conditionnelle ciblée et reconstruisez les deux cibles.
• Si iOS et Catalyst échouent sur le même symbole, alors examinez d’abord le code, l’import du module, les dépendances et les réglages communs ; ne partez pas du principe que l’erreur signalée en bêta explique les deux échecs.
• Si l’échec n’apparaît que dans un environnement de CI, alors comparez les versions de Xcode et du SDK, les paramètres de construction et les dépendances résolues avant de modifier le code.
• Si le code fautif est dans une dépendance que vous ne pouvez pas modifier, alors consignez sa version et la cible en échec, puis évaluez une mise à niveau, un remplacement ou le report de la cible Catalyst.
• Si une version ultérieure de Xcode est envisagée, alors vérifiez ses notes officielles et reproduisez le cas dans votre projet avant de retirer le contournement. Une correction annoncée ne valide pas automatiquement votre configuration.

Cette distinction évite deux corrections trompeuses. La première consiste à désactiver toute une portion de code et à conclure que le problème est résolu, sans contrôler les fonctionnalités perdues. La seconde consiste à faire une mise à jour de Xcode ou à déplacer la tâche sur un autre Mac sans vérifier si la cause est une API indisponible. Ces choix peuvent être pertinents dans certains contextes, mais ils ne remplacent pas un diagnostic par cible.

Si le symbole se trouve dans un module partagé, vérifiez également les conséquences sur ses consommateurs. Une condition ajoutée au mauvais niveau peut faire disparaître du code utile pour iOS, ou laisser l’appel fautif compilé dans une autre cible. Faites examiner la branche dans le même contexte que celui où elle sera compilée, plutôt que de vous limiter à une recherche textuelle du symbole dans le dépôt.

SECTION 05Valider le correctif et ses conséquences

Après la modification, reconstruisez iOS et Mac Catalyst à partir du même commit. Comparez les résultats avec les journaux initiaux : l’erreur visée doit disparaître sur la cible concernée, et le chemin de code iOS doit rester présent et compilable. Une réussite locale isolée ne suffit pas si la chaîne de livraison utilise une autre version de Xcode, des réglages différents ou des dépendances résolues ailleurs.

Si votre processus inclut des tests, un archivage ou une distribution, validez aussi ces étapes pour les cibles qui les utilisent. La compilation seule ne garantit pas que les étapes suivantes produisent le résultat attendu. Consultez la documentation Apple sur la distribution et l’archivage pour distinguer la construction du flux de distribution, et gardez dans le dossier de diagnostic les journaux associés à chaque résultat.

Pour la CI, consignez le commit, la version de Xcode, le SDK, la cible, les réglages de construction, la commande exécutée et le journal complet. Si la chaîne archive ou distribue un résultat, conservez aussi les éléments qui permettent d’identifier la cible et l’étape concernée. La documentation Apple sur la distribution aux appareils enregistrés s’applique aux processus qui incluent cette forme de distribution ; elle ne remplace pas la vérification de compilation propre à Catalyst.

Une reproduction fiable signifie que la même entrée de code, compilée pour chaque destination pertinente, donne des résultats que vous pouvez expliquer. Si le poste de travail passe et le nœud CI échoue, comparez d’abord les versions, le SDK, les paramètres et les dépendances réellement utilisés. Ne concluez à un défaut du Mac qu’après avoir écarté ces écarts.

SECTION 06Choisir la prochaine action

• Si le problème correspond à l’avis de Xcode 27.2 Beta 2 et que le correctif conditionnel fait passer les deux compilations, alors conservez le changement avec une note liée à la version et au symbole concernés.
• Si un Xcode ultérieur est disponible dans votre environnement de validation, alors reproduisez le cas avec cette version, consultez ses notes officielles, puis retirez le contournement uniquement après une compilation réussie des cibles concernées.
• Si le défaut vient d’une dépendance ou d’un réglage CI, alors corrigez la source de divergence et conservez séparément la validation Catalyst.
• Si aucun élément ne relie l’erreur à l’API iOS 27.1, alors revenez au diagnostic général : module, cible, réglages, code et version d’outil.

Pour comparer rapidement les options sans confondre correction logicielle et choix d’infrastructure, partez de la cause établie :

SECTION 07FAQ sur l’échec Mac Catalyst

Les réponses suivantes portent sur le cas documenté pour Xcode 27.2 Beta 2 et sur les contrôles qui permettent de ne pas l’étendre à tort à tous les échecs de construction. Associez chaque conclusion à la cible et au journal qui l’établissent.

Si vous devez aussi stabiliser l’environnement qui exécute ces validations, comparez vos besoins avec les informations de tarification des environnements Mac ; ce choix ne remplace toutefois pas le correctif de code lorsque la cause est une API indisponible pour la cible.

SECTION 08Environnement local ou exécution Mac distante

Un Mac local déjà configuré peut convenir si vous disposez d’un environnement reproductible et si vos validations restent liées à une seule machine. Une CI existante peut suffire si elle exécute déjà les cibles requises et conserve les journaux nécessaires. En revanche, des environnements difficiles à reproduire, des versions d’outils qui diffèrent entre le poste et la CI, ou une capacité de construction partagée avec d’autres travaux compliquent l’analyse de ce type d’échec.

Un Mac distant n’élimine ni les erreurs de compilation ni les contraintes de plateforme ; il peut surtout fournir un environnement macOS distinct pour reproduire une construction, vérifier un réglage et comparer les résultats avec votre poste. Si votre équipe a besoin d’un environnement temporaire pour ces tests plutôt que d’acheter un Mac dédié, examinez les options d’accès Mac proposées par MACNOX et confrontez-les à la fréquence réelle de vos tâches. Si votre chaîne actuelle reproduit déjà le problème de manière fiable et dispose de journaux complets, corrigez d’abord le projet et gardez cette chaîne comme référence.