Xcode JSON xcproj: Xcode 27.2'deki Yeni Proje Biçimi

Her Xcode projesinde neredeyse kimsenin bilerek okumadığı bir dosya vardır: project.pbxproj. İki kişi farklı branch'lerde dosya eklediğinde merge conflict'ler buradan çıkar. Xcode 27.2 bu dosyayı değiştiriyor. Xcode JSON xcproj biçimi, yani project.xcproj adlı bir dosya, aynı proje yapılandırmasını insanların, diff araçlarının ve kodlama ajanlarının gerçekten üzerinde çalışabileceği hiyerarşik JSON olarak saklıyor.

Bu rehber yeni dosyanın ne olduğunu, Apple'ın onu neden değiştirdiğini, neye benzediğini, bir projenin nasıl dönüştürüleceğini ve geçmeden önce neleri kontrol etmeniz gerektiğini anlatıyor: eski Xcode sürümleri, CI ve üçüncü parti araçlar. Apple'ın dokümantasyonuna ve sürüm notlarına, Apple'ın açık kaynaklı biçim paketine ve @sarunw ile Artem Novichkov'un yazılarına dayanıyor. Biçim Xcode 27.2 ile geldi; ayrıntılar sürümler arasında değişebilir.

Xcode 27.2'deki yeni JSON .xcproj biçimi nedir?

Bir .xcodeproj aslında bir klasördür. İçinde, paylaşılan scheme'ler gibi başka dosyaların yanında proje yapılandırma dosyası bulunur. Apple'ın Updating your Xcode project configuration file format makalesi değişikliği açıklıyor: önceki sürümlerde bu dosya .pbxproj uzantılı bir property list; Xcode 27.2 ve sonrasında ise varsayılan, ".xcproj uzantılı, daha küçük, hiyerarşik ve kendini tanımlayan bir JSON dosyası."

Geri kalan her şeyi üç gerçek çerçeveliyor:

• Yeni projeler varsayılan olarak JSON alır. Xcode 27.2 ve sonrasında oluşturduğunuz projeler project.xcproj kullanır.
• Mevcut projeler kendiliğinden değişmez. Xcode 27 ve sonrası iki biçimi de destekler; ne zaman geçeceğinizi siz seçersiniz.
• Biçim açık kaynaklı. Apple onu, dosyayı tipli değerler olarak modelleyen bir Swift paketi olan xcode-project-format olarak yayınlıyor.

Xcode 27.2 sürüm notları bunu tek satırda özetliyor: JSON tabanlı biçim "daha okunabilir, merge dostu ve kodlama ajanlarının düzenlemesi daha kolay." @sarunw'nun 27.2 çıktığında söylediği gibi Xcode 27.2, .pbxproj'u yeni bir JSON .xcproj biçimiyle değiştiriyor.

Apple project.pbxproj'u neden değiştiriyor?

Eski biçim projeyi, her biri 24 karakterlik anlamsız bir onaltılık ID ile anahtarlanmış düz bir nesne listesi olarak saklıyor. Nesneler birbirine bu ID'lerle işaret ediyor. Bir target'a tek bir Swift dosyası eklemek genellikle aynı anda birkaç bölüme dokunuyor: bir dosya referansı, bir gruptaki yeri, bir build file girdisi ve target'ın Sources build phase'i. @sarunw bilinen sonucu, tek bir değişikliğin "project.pbxproj'un üç bölümünde yeniden yazılması" olarak tarif ediyor. İki branch'in her biri bir dosya eklediğinde bu dağınık düzenlemeler çakışıyor; onları elle çözmek de bölümler arasında ID'leri eşleştirmek demek.

Build ayarlarında da benzer bir sorun vardı. Debug ve Release gibi her yapılandırma kendi tam ayar bloğunu tutuyordu; bu yüzden tek bir ayar farklı değerlerle birkaç yerde görünebiliyordu.

Apple'ın dokümantasyonu yeni biçim için üç neden veriyor:

1. İncelenebilir diff'ler. Karşılaştırma görünümündeki değişiklikler Xcode'daki eylemlerinizle örtüşür.
2. Daha az merge conflict. JSON biçimi yapılandırma değişikliklerini yalıtır; böylece ilgisiz düzenlemelerin aynı satırlara dokunma olasılığı azalır.
3. Ajan dostu. Kodlama ajanlarının dosyayı sizin yerinize düzenlemesi daha kolay.

Xcode 16'nın synchronized folder'ları, bu klasörlerdeki dosyalar için dosya başına girdileri zaten kaldırmıştı. @sarunw'nun yazısı JSON biçiminin daha ileri gittiğini belirtiyor, çünkü target'lar, build phase'ler, yapılandırmalar ve paket referansları property list'te hâlâ ID kullanıyordu.

Bir project.xcproj dosyası neye benzer?

Apple dokümantasyonunda eksiksiz bir örnek dosya yayınlamıyor, ancak açık kaynaklı paketi üst düzey anahtarları tanımlıyor. Bunlar arasında default-configuration, configurations, localizations, files, targets, packages ve build-settings var. Aşağıda bu anahtarları kullanan, değerleri @sarunw'nun demo projesinden alınmış kısaltılmış bir alıntı var. Eksiksiz bir dosya değil.

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

Bir build ayarı bir kez yazılır. Yapılandırmalar farklı değerlere ihtiyaç duyduğunda, yukarıdaki [config=Debug] gibi, koşul anahtarın içine girer. Dosyalar files ağacındaki girdilerdir ve her biri ayrı bir build phase listesinden referans almak yerine kendi target üyeliğini taşır. @sarunw'nun örneğinde bir dosya tek bir satırdır:

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

Boyut farkı belirgin. @sarunw'nun demo projesinde 300 satırlık bir property list, 123 satırlık JSON'a dönüştü. Artem Novichkov'un karşılaştırmasında aynı Swift paketini eklemek project.pbxproj'da beş yerde 24 satır, project.xcproj'da ise iki yerde 12 satır tuttu. Sonuçlar projenize göre değişir, ama yön tutarlı.

Bir Xcode projesi JSON xcproj'a nasıl dönüştürülür?

Dönüştürmenin temiz ve ayrı bir değişiklik olması için önce çalışmanızı commit edin. Ardından Xcode 27.2'de:

1. Project navigator'ın en üstündeki projeyi seçin.
2. File inspector'ı açın.
3. Project Document altında, Project Format açılır menüsünden JSON'u seçin.
4. Bir diyalog görünürse Continue'ya tıklayın.

.xcodeproj klasörünün içinde project.pbxproj kaldırılır ve project.xcproj eklenir. Apple, source control kullanıyorsanız bu iki dosya değişikliğini geri alarak geçişi iptal edebileceğinizi belirtiyor. Paketteki scheme'ler ve diğer dosyalar değişikliğin parçası değil.

Script'ler ve büyük repository'ler için Artem Novichkov, Xcode 27.2'deki xcodebuild'in iki yönde de dönüştürebildiğini bildiriyor. Ayrıca dönüştürülen dosyanın orijinalin yerini aldığını fark etti; bu da önce commit etmek için bir başka neden. Bu Apple'ın makalesinde yer almadığından kendi makinenizde xcodebuild -help'i kontrol edin.

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

Hangi Xcode sürümleri ve araçlar .xcproj okuyabilir?

Apple'ın dokümantasyonu .xcproj biçiminin Xcode 27 ve sonrasıyla uyumlu olduğunu, sürüm notları da bu biçimi kullanan projelerin Xcode 27'nin önceki sürümlerinde de açıldığını söylüyor. Yani Xcode 27.0 veya 27.1 kullanan bir ekip dönüştürülmüş bir projeyi açabilir, ama dönüştürme seçeneğinin kendisi 27.2'de. Xcode 26 veya daha eskisini kullanan herkes property list biçimine ihtiyaç duyar; @sarunw'nun yazısı da eski Xcode sürümleri için tercihin bu biçim olmaya devam ettiğini belirtiyor.

Üçüncü parti destek hâlâ geliyor. Birçok aracın üzerine kurulduğu Tuist'in XcodeProj kütüphanesi, 9.17.0 sürümünde "[Experimental] support Xcode 27.2's JSON project format (project.xcproj)" ekledi. XcodeGen'de veya CocoaPods'un xcodeproj gem'inde desteği doğrulayamadık; bu yüzden project.pbxproj'u düzenleyen her aracı, kendi sürüm notları aksini söyleyene kadar desteklenmiyor kabul edin. Projenizi bir spec'ten üretip commit etmiyorsanız, üreteç çalışmaya devam ettiği sürece biçim daha az önemli.

Kendi araçlarınız için Apple'ın paketi daha iyi bir yol. Swift 6.1 veya sonrasını gerektiriyor, macOS 14 ve sonrasında ve diğer platformlarda derleniyor ve Runtime Library Exception ile Apache 2.0 lisanslı. README'si bir projeyi XCSchema.Project ile okumayı gösteriyor:

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

xcproj kodlama ajanlarına ve CI'a nasıl yardım eder?

@sarunw'nun değişiklik özeti, JSON biçiminin insanlar tarafından daha okunabilir ve kodlama ajanları tarafından düzenlenebilir olduğu; bu da Apple'ın kendi ifadesiyle örtüşüyor. Bir property list'e dosya veya paket ekleyen bir ajan, geçerli ID'ler üretmek ve onlara referans veren her bölümü güncellemek zorunda. JSON'da düzenleme, bir pull request'te inceleyebileceğiniz küçük ve yerel bir değişiklik.

Apple'ın paketi ayrıca kütüphanenin üzerine kurulu bir komut satırı aracı olan xcprojformatter'ı da içeriyor. Artem Novichkov onu xcrun xcprojformatter ile çalıştırmayı anlatıyor: dosyayı kanonik biçimde yazdırıyor, --update ise dosyayı yerinde yeniden yazıyor. Bu, kullanışlı bir CI kontrolü sağlıyor, çünkü bir formatter diff'i kanonik biçimde olmayan her elle veya ajanla yapılmış düzenlemeyi gösterir. Sürümünüzün kabul ettiği argümanlar için xcrun xcprojformatter --help'i kontrol edin.

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

Ayrıca formatter'ın, yanlış yazılmış bir anahtar gibi tanımadığı anahtarları sessizce attığını fark etti; bu yüzden her şeyi doğruladığını varsaymak yerine neyi değiştirdiğini gözden geçirin. Aynısı bir merge conflict'ten sonra da geçerli: JSON'u çözün, formatter'ı çalıştırın ve target'ların ve paketlerin Xcode'da hâlâ doğru göründüğünü kontrol edin.

JSON proje biçimi iPhone Duo uygulamaları için önemli mi?

Uygulamanızın nasıl çalıştığı açısından değil. Proje biçimi yalnızca Xcode'un yapılandırmanızı nasıl sakladığını değiştiriyor; iPhone veya iPhone Duo için derlediğiniz uygulama aynı. Ama çevresindeki iş için önemli. Bir uygulamayı iPhone Duo'ya uyarlamak, iOS 27.1 SDK ile yeniden derlemek ve genellikle branch'ler arasında proje ayarlarına dokunmak demek; project.pbxproj'daki merge conflict'ler de tam bu sırada ortaya çıkıyor.

Ayrıca güncel en iyi uygulamaları ve yeni API'leri kapsayan, Xcode 27'nin yerleşik agent skills'i ile de iyi uyum sağlıyor. @sarunw'nun belirttiği gibi eski uikit-app-modernization skill'i artık app-resizability ve iPhone Duo desteği ekliyor. Bu işte bir ajanın yardım etmesine izin verirseniz JSON bir proje dosyası onun değişikliklerini incelenebilecek kadar küçük tutar. O tarafı Xcode 27 agent skills'i dışa aktarma rehberimiz anlatıyor; uygulama değişikliklerinin kendisini ise iPhone Duo hazırlık kontrol listesi listeliyor.

Önemli çıkarımlar

• Xcode 27.2, yeni projeler için varsayılan olarak project.pbxproj'u daha küçük, hiyerarşik bir JSON dosyası olan project.xcproj ile değiştiriyor.
• JSON biçimi diff'lerin eylemlerinizle örtüşmesini sağlar, merge conflict'leri azaltmak için değişiklikleri yalıtır ve kodlama ajanlarının düzenlemesi daha kolaydır.
• Mevcut projeleri File inspector'da Project Document altından dönüştürün; geri alabilmek için önce commit edin.
• .xcproj, Xcode 27 ve sonrasında açılır. Herhangi bir kişi veya CI makinesi Xcode 26'daysa property list'te kalın.
• Geçmeden önce project.pbxproj'u ayrıştıran üreteçleri, script'leri ve bağımlılık yöneticilerini kontrol edin; kendi araçlarınız için Apple'ın açık kaynaklı paketi ve xcprojformatter yardımcı olur.

Projeniz düzene girdiğinde onu cihazda çalıştırın: iPhone Duo hazırlık kontrol listesiyle başlayın ve diğer geliştiricilerin neler yayınladığını Built for the fold sayfasında görün.