Xcode JSON xcproj : le nouveau format de projet de Xcode 27.2

Chaque projet Xcode contient un fichier que presque personne ne lit volontairement : project.pbxproj. C'est de lui que viennent les conflits de fusion quand deux personnes ajoutent des fichiers sur des branches différentes. Xcode 27.2 le remplace. Le format Xcode JSON xcproj, un fichier nommé project.xcproj, stocke la même configuration de projet sous forme de JSON hiérarchique, avec lequel les personnes, les outils de diff et les agents de code peuvent réellement travailler.

Ce guide explique ce qu'est ce nouveau fichier, pourquoi Apple l'a changé, à quoi il ressemble, comment convertir un projet et ce qu'il faut vérifier avant de passer le cap : anciennes versions de Xcode, CI et outils tiers. Il s'appuie sur la documentation et les notes de version d'Apple, sur le package open source du format publié par Apple et sur les articles de @sarunw et d'Artem Novichkov. Le format est nouveau dans Xcode 27.2, et ses détails peuvent évoluer d'une version à l'autre.

Qu'est-ce que le nouveau format JSON .xcproj de Xcode 27.2 ?

Un .xcodeproj est un dossier. Il contient le fichier de configuration du projet, ainsi que d'autres fichiers comme les schemes partagés. L'article d'Apple Updating your Xcode project configuration file format explique le changement : dans les versions précédentes, ce fichier est une property list avec l'extension .pbxproj ; dans Xcode 27.2 et ultérieur, le format par défaut est un fichier JSON plus compact, hiérarchique et autodescriptif, avec l'extension .xcproj.

Trois faits posent le cadre :

• Les nouveaux projets passent au JSON par défaut. Les projets créés dans Xcode 27.2 et ultérieur utilisent project.xcproj.
• Les projets existants ne changent pas d'eux-mêmes. Xcode 27 et ultérieur prend en charge les deux formats, et vous choisissez le moment de la conversion.
• Le format est open source. Apple le publie sous le nom xcode-project-format, un package Swift qui modélise le fichier sous forme de valeurs typées.

Les notes de version de Xcode 27.2 le résument en une ligne : le format basé sur JSON est plus lisible, plus facile à fusionner et plus simple à modifier pour les agents de code. Comme l'a dit @sarunw à la sortie de 27.2, Xcode 27.2 remplace .pbxproj par un nouveau format JSON .xcproj.

Pourquoi Apple remplace-t-il project.pbxproj ?

L'ancien format stocke le projet sous forme de liste plate d'objets, chacun identifié par un ID hexadécimal opaque de 24 caractères. Les objets se référencent entre eux par ces ID. Ajouter un seul fichier Swift à une cible touche généralement plusieurs sections à la fois : une référence de fichier, sa place dans un groupe, une entrée de build file et la build phase Sources de la cible. @sarunw décrit le résultat bien connu : une seule modification réécrite dans trois sections de project.pbxproj. Quand deux branches ajoutent chacune un fichier, ces modifications éparpillées entrent en collision, et les résoudre à la main oblige à faire correspondre des ID d'une section à l'autre.

Les réglages de build posaient un problème similaire. Chaque configuration, comme Debug et Release, conservait son propre bloc complet de réglages : un même réglage pouvait donc apparaître à plusieurs endroits avec des valeurs différentes.

La documentation d'Apple donne trois raisons au nouveau format :

1. Des diffs lisibles. Les modifications affichées dans la vue de comparaison correspondent à vos actions dans Xcode.
2. Moins de conflits de fusion. Le format JSON isole les modifications de configuration : des modifications sans rapport risquent moins de toucher les mêmes lignes.
3. Adapté aux agents. Il est plus facile pour les agents de coding intelligence de modifier le fichier à votre place.

Les dossiers synchronisés de Xcode 16 avaient déjà supprimé les entrées par fichier pour les fichiers de ces dossiers. L'article de @sarunw note que le format JSON va plus loin, car les cibles, les build phases, les configurations et les références de packages utilisaient encore des ID dans la property list.

À quoi ressemble un fichier project.xcproj ?

Apple ne publie pas d'exemple de fichier complet dans sa documentation, mais son package open source définit les clés de premier niveau. On y trouve notamment default-configuration, configurations, localizations, files, targets, packages et build-settings. Voici un extrait réduit qui utilise ces clés, avec des valeurs tirées du projet de démonstration de @sarunw. Ce n'est pas un fichier complet.

{
  "default-configuration": "Debug",
  "build-settings": {
    "DEBUG_INFORMATION_FORMAT[config=Debug]": "dwarf",
    "DEBUG_INFORMATION_FORMAT[config=Release]": "dwarf-with-dsym"
  }
}

Un réglage de build n'est écrit qu'une fois. Quand des configurations ont besoin de valeurs différentes, la condition est intégrée à la clé, comme [config=Debug] ci-dessus. Les fichiers sont des entrées de l'arborescence files, et chacun porte sa propre appartenance à une cible au lieu d'être référencé depuis une liste de build phase séparée. Dans l'exemple de @sarunw, un fichier tient sur une seule ligne :

{ "path": "CatalogView.swift", "target-membership": [ "ToolbarPlacements/compile-sources" ] }

La différence de taille est sensible. Sur le projet de démonstration de @sarunw, une property list de 300 lignes est devenue 123 lignes de JSON. La comparaison d'Artem Novichkov montre que l'ajout du même package Swift prenait 24 lignes à cinq endroits dans project.pbxproj, contre 12 lignes à deux endroits dans project.xcproj. Les résultats varieront selon votre projet, mais la tendance est constante.

Comment convertir un projet Xcode en JSON xcproj ?

Faites d'abord un commit de votre travail, pour que la conversion soit une modification propre et séparée. Puis, dans Xcode 27.2 :

1. Sélectionnez le projet en haut du Project navigator.
2. Ouvrez l'inspecteur File.
3. Sous Project Document, choisissez JSON dans le menu local Project Format.
4. Si une boîte de dialogue apparaît, cliquez sur Continue.

Dans le dossier .xcodeproj, project.pbxproj est supprimé et project.xcproj est ajouté. Apple note que, si vous utilisez un gestionnaire de versions, vous pouvez annuler la conversion en abandonnant ces deux modifications de fichier. Les schemes et autres fichiers du bundle ne sont pas concernés.

Pour les scripts et les grands dépôts, Artem Novichkov indique que xcodebuild dans Xcode 27.2 peut convertir dans les deux sens. Il a aussi constaté que le fichier converti remplace l'original : raison de plus pour faire un commit d'abord. Vérifiez xcodebuild -help sur votre machine, car ce n'est pas dans l'article d'Apple.

xcodebuild -project Weather.xcodeproj -convert-project xcproj
xcodebuild -project Weather.xcodeproj -convert-project pbxproj

Quelles versions de Xcode et quels outils peuvent lire .xcproj ?

La documentation d'Apple indique que le format .xcproj est compatible avec Xcode 27 et ultérieur, et les notes de version précisent que les projets qui l'utilisent s'ouvrent aussi dans les versions antérieures de Xcode 27. Une équipe sous Xcode 27.0 ou 27.1 peut donc ouvrir un projet converti, mais l'option de conversion elle-même se trouve dans 27.2. Quiconque travaille sous Xcode 26 ou antérieur a besoin du format property list, qui reste, comme le note l'article de @sarunw, le choix pour les anciennes versions de Xcode.

La prise en charge par les outils tiers arrive progressivement. La bibliothèque XcodeProj de Tuist, sur laquelle reposent de nombreux outils, a ajouté dans sa version 9.17.0 une prise en charge expérimentale du format de projet JSON de Xcode 27.2 (project.xcproj). Nous n'avons pas pu confirmer la prise en charge par XcodeGen ni par la gem xcodeproj de CocoaPods : considérez donc tout outil qui modifie project.pbxproj comme non compatible tant que ses propres notes de version n'indiquent pas le contraire. Si vous générez votre projet à partir d'une spécification sans le versionner, le format compte moins, tant que le générateur continue de fonctionner.

Le package d'Apple est la meilleure voie pour vos propres outils. Il requiert Swift 6.1 ou ultérieur, se compile sur macOS 14 et ultérieur ainsi que sur d'autres plateformes, et est distribué sous licence Apache 2.0 avec Runtime Library Exception. Son README montre la lecture d'un projet avec XCSchema.Project :

import XcodeProjectFormat

func listTargets(in projectURL: URL) throws {
    let projectData = try Data(contentsOf: projectURL)
    let project = try XCSchema.Project(jsonRepresentation: projectData)
    for target in project.targets {
        print(target.name)
    }
}

En quoi xcproj aide-t-il les agents de code et la CI ?

Pour @sarunw, le format JSON est plus lisible par les humains et modifiable par les agents de coding intelligence, ce qui rejoint la formulation d'Apple. Un agent qui ajoute un fichier ou un package à une property list doit inventer des ID valides et mettre à jour chaque section qui les référence. Avec le JSON, la modification est petite et locale, et vous pouvez la relire dans une pull request.

Le package d'Apple inclut aussi xcprojformatter, un outil en ligne de commande construit sur la bibliothèque. Artem Novichkov décrit son utilisation avec xcrun xcprojformatter : il affiche le fichier sous une forme canonique, et --update le réécrit sur place. Cela en fait une vérification de CI utile, car un diff du formateur révèle toute modification manuelle ou faite par un agent qui n'est pas sous forme canonique. Consultez xcrun xcprojformatter --help pour connaître les arguments exacts acceptés par votre version.

xcrun xcprojformatter --update MyApp.xcodeproj/project.xcproj
git diff --exit-code -- MyApp.xcodeproj/project.xcproj

Il a aussi constaté que le formateur supprime sans prévenir les clés qu'il ne reconnaît pas, comme une clé mal orthographiée : relisez donc ce qu'il modifie au lieu de supposer qu'il valide tout. Il en va de même après un conflit de fusion : résolvez le JSON, lancez le formateur et vérifiez dans Xcode que les cibles et les packages sont toujours corrects.

Le format de projet JSON compte-t-il pour les apps iPhone Duo ?

Pas pour le fonctionnement de votre app. Le format de projet ne change que la façon dont Xcode stocke votre configuration ; l'app que vous compilez pour iPhone ou iPhone Duo est la même. Il compte en revanche pour le travail qui l'entoure. Adapter une app à l'iPhone Duo implique de recompiler avec le SDK iOS 27.1 et souvent de modifier des réglages de projet sur plusieurs branches, précisément le moment où surgissent les conflits de fusion dans project.pbxproj.

Il se combine aussi bien avec les agent skills intégrés à Xcode 27, qui couvrent les bonnes pratiques actuelles et les nouvelles API. Comme le note @sarunw, l'ancien skill uikit-app-modernization s'appelle désormais app-resizability et ajoute la prise en charge de l'iPhone Duo. Si vous laissez un agent vous aider dans ce travail, un fichier de projet JSON garde ses modifications assez petites pour être relues. Notre guide sur l'export des agent skills de Xcode 27 couvre cet aspect, et la checklist de préparation à l'iPhone Duo liste les modifications de l'app elle-même.

Ce qu'il faut retenir

• Xcode 27.2 remplace project.pbxproj par project.xcproj, un fichier JSON plus compact et hiérarchique, utilisé par défaut pour les nouveaux projets.
• Le format JSON produit des diffs fidèles à vos actions, isole les modifications pour réduire les conflits de fusion et est plus facile à modifier pour les agents de code.
• Convertissez les projets existants dans l'inspecteur File, sous Project Document ; faites d'abord un commit pour pouvoir annuler.
• .xcproj s'ouvre dans Xcode 27 et ultérieur. Gardez la property list si un membre de l'équipe ou une machine de CI est encore sous Xcode 26.
• Vérifiez les générateurs, scripts et gestionnaires de dépendances qui analysent project.pbxproj avant de convertir ; le package open source d'Apple et xcprojformatter vous aident pour vos propres outils.

Une fois votre projet en ordre, mettez-le au travail sur l'appareil : commencez par la checklist de préparation à l'iPhone Duo, et découvrez ce que d'autres développeurs ont publié dans Built for the fold.