Eski macOS sürümlerini desteklemek için yeni API’leri bilen bir SDK ile derleyin, desteklenen bir minimum dağıtım hedefi belirleyin ve yeni çağrıları kullanılabilirlik denetimleriyle koruyup çalışan geri dönüş seçenekleri sağlayın. Bu anlatım, macOS 14 görünümünü benimserken küçük bir yerel not penceresini macOS 12’de kullanılabilir tutar.

Hangi uyumluluk ayarları birbiriyle uyuşmalı?

Bir Mac uygulaması geliştiricisi için somut görev, desteklenen en eski sürümde açılan ve yeni özellikleri kullanılabilir olduklarında kullanan tek bir uygulama oluşturmaktır. Üç girdiyi birbirinden ayırarak başlayın: derleyici kaynak dilini anlar, SDK API bildirimlerini sağlar ve dağıtım hedefi amaçlanan en eski çalışma ortamını belirtir. Apple’ın derleme ayarları başvuru belgesi, SDKROOT değerini derlemeye katılan başlık ve kitaplıkları sağlayan SDK olarak tanımlar. Derleme ayarları başvurusu

Daha yeni bir SDK ile daha eski bir dağıtım hedefi birlikte kullanılabilir. Clang, en yeni SDK’ya karşı derleme yaparken -mmacos-version-min= ile daha eski bir macOS minimumu seçmeyi açıkça belgeler. Bu birleşim, minimum sürümden sonra eklenen API’ler çevresinde yine kullanılabilirlik denetimleri gerektirir. Clang Dil Uzantıları

Seçtiğiniz Xcode’un gerçekten desteklediği bir minimum sürüm belirleyin. Apple’ın uyumluluk tablosu, Xcode’u çalıştırmak için gereken macOS sürümü ile Xcode’un derleyebildiği dağıtım hedeflerini birbirinden ayırır. İstediğiniz minimum sürüm bu araç zincirinin desteklenen aralığının dışındaysa, uygun ve desteklenen bir araç zinciri seçin ya da geri dönüşleri uygulamadan önce uygulamanın minimum sürümünü değiştirin. SDK’ler ve sistem gereksinimleri

Bu kurgusal örnekte sözleşme; macOS 12 veya daha yenisi, macOS 14 API’lerini içeren bir SDK ve iki durumu olan bir not penceresidir: boş bir koleksiyon ve tek bir örnek not. Daha yeni boş durum sunumu isteğe bağlıdır; notu görüntüleme temel sürümde de kullanılabilir.

Minimum sürümü her iki derleme yapılandırmasında da ayarlayın

Uygulama hedefinin Build Settings bölümünde hem Debug hem de Release için MACOSX_DEPLOYMENT_TARGET değerini 12.0 olarak ayarlayın. Ayarları yapılandırma dosyalarında yönetiyorsanız aşağıdaki, bir program değil, eksiksiz bir yapılandırma parçasıdır:

MACOSX_DEPLOYMENT_TARGET = 12.0

Yapılandırma dosyasını projenin Info sekmesinde istenen yapılandırmalara atayın. Ardından hedefin son değerini kontrol edin: Apple, hedef ayarlarının atanmış bir yapılandırma dosyasından sağlanan değerleri geçersiz kılabileceğini belgeliyor. Dosyayı projeye eklemek tek başına ayarlarının geçerli olmasını sağlamaz. Projenize bir derleme yapılandırma dosyası ekleme

Uygulamanın minimum sürümünü yükseltmeden daha yeni bir API’yi nasıl eklersiniz?

Swift’in if #available denetimi, çalışma zamanındaki kullanılabilirliği kontrol eder ve derleyiciye bu dalın içinde hangi API’lere izin verildiğini bildirir. Eski sistemin eksiksiz bir uygulamaya sahip olması için geri dönüşü aynı karar yapısında tutun. Gerekli *, açıkça adlandırılmayan platformları kapsar; adı geçen macOS API’sini eski sürümlerde kullanılabilir hâle getirmez. Denetim Akışı — API Kullanılabilirliğini Denetleme

Apple’ın ContentUnavailableView görünümü macOS 14 ve sonrasında kullanılabilir ve boş içerik sunumlarını destekler. Burada küçük bir VStack, macOS 12 ve 13’te buna karşılık gelen sunumu sağlar. Her iki dal da aynı sonraki adımı anlatır. ContentUnavailableView

Eksiksiz kurgusal SwiftUI uygulaması

CompatibilityNotes adlı bir macOS uygulama projesi oluşturun, Swift ve SwiftUI’yi seçin ve dağıtım hedefini 12.0 olarak ayarlayın. macOS 14 API’lerini içeren bir SDK kullanın. Oluşturulan uygulama ve içerik görünümü bildirimlerini aşağıdaki tek dosyayla değiştirin; hedefte yalnızca bir @main bildirimi bulunduğundan emin olun. Varlık, paket veya girdi dosyası gerekmez.

import SwiftUI

@main
struct CompatibilityNotesApp: App {
    var body: some Scene {
        WindowGroup {
            NotesView()
        }
    }
}

struct NotesView: View {
    @State private var notes: [String] = []

    var body: some View {
        VStack(spacing: 16) {
            if notes.isEmpty {
                emptyState
            } else {
                List(notes, id: \.self) { note in
                    Text(note)
                }
            }

            Button(notes.isEmpty ? "Add sample note" : "Reset sample") {
                if notes.isEmpty {
                    notes = ["Sample note: arrange the blue shapes."]
                } else {
                    notes = []
                }
            }
        }
        .padding()
        .frame(minWidth: 360, minHeight: 240)
    }

    @ViewBuilder
    private var emptyState: some View {
        if #available(macOS 14.0, *) {
            ModernEmptyState()
        } else {
            VStack(spacing: 8) {
                Text("No notes")
                    .font(.headline)
                Text("Add a sample note to begin.")
            }
        }
    }
}

@available(macOS 14.0, *)
private struct ModernEmptyState: View {
    var body: some View {
        ContentUnavailableView {
            Label("No notes", systemImage: "note.text")
        } description: {
            Text("Add a sample note to begin.")
        }
    }
}

Amaçlanan davranış basittir: macOS 12 ve 13 metin geri dönüşünü görüntüler; macOS 14 ve sonrası ContentUnavailableView görünümünü görüntüler. Add sample note seçildiğinde kurgusal not görüntülenir. Reset sample seçildiğinde boş duruma dönülür. Bu gösterim verileri bellekte tutar ve notları uygulama açılışları arasında kaydetmez.

@available açıklaması, yardımcı işlevin kullanımını macOS 14 ve sonrasıyla sınırlar. Çağıranın #available dalı bu kısıtlamayı karşılar. Bir açıklama, bildirimin kullanılabilirliğini belirtir; eski bir uygulama sağlamaz. Öznitelikler — available

Bu örnek, alınan belgelere göre incelendi ancak derlenmedi veya çalıştırılmadı: mevcut yürütme ortamı Linux’tu ve Swift ya da Clang yüklü değildi. macOS’te derleme ve çalışma zamanı denetimleri yine de gereklidir.

Kullanılabilirlik denetimleri bağlama aşamasında neyi çözer?

Bir yürütülebilir dosya yüklenemiyorsa çalışma zamanı dalı işe yaramaz. Clang, dağıtım hedefinden sonra eklenen ve kullanılabilirlik açıklaması taşıyan bildirimlerin normalde zayıf bağlanabildiğini belgeliyor. Zayıf başvuru, bildirimin çalışma zamanında bulunmamasına izin verir; uygulama, bildirim yokken onu kullanmaktan yine de kaçınmalıdır. Bu nedenle dalın yanı sıra dağıtım hedefi ve derleme sırasında görülen bildirimler de önemlidir. Clang’de Öznitelikler — kullanılabilirlik

Örnekte SwiftUI’yi normal şekilde bağlı tutun: macOS 12 temel sürümünde bu çerçeve zaten bulunur. Uyumluluk sınırı daha yeni görünümü çevreler. Temel sürümünüzde tamamen yeni bir çerçeve bulunmuyorsa çerçeve bağımlılığını ayrıca değerlendirin; tek bir çağrıyı korumak tüm yükleme gereksinimlerini çözmez. Apple’ın zayıf bağlama kılavuzu, eksik bir simgeye izin vermek ile o simgeyi gerçekten kullanmak arasındaki farkı açıklar. Çerçeveler ve Zayıf Bağlama

Kaynak dilinize ait kullanılabilirlik söz dizimini kullanın:

Kaynak dili Çalışma zamanı kullanılabilirlik koşulu
Swift if #available(macOS 14.0, *)
Objective-C veya Objective-C++ if (@available(macOS 14.0, *))
Clang’in Apple platformu desteğine sahip C veya C++ if (__builtin_available(macOS 14.0, *))

Clang, Objective-C yazımını ve C/C++ yerleşik işlevini -Wunguarded-availability ile birlikte belgeler. C ailesi kodu için kullanılabilirlik tanılamalarını etkinleştirin ve eski bir dağıtım hedefini kullanılabilir saymadan önce uyarıları inceleyin. Clang Dil Uzantıları

Derleme SDK’sı API’yi içermiyorsa ne olur?

Çalışma zamanı denetimi, SDK’da bulunmayan bir bildirimi sağlayamaz. Derleyici ContentUnavailableView simgesini çözemiyorsa bu API’yi içeren bir SDK ile derleyin. Projenin eski SDK’larla da derlenmesi gerekiyorsa, bu derlemelerde desteklenmeyen başvuruları dışarıda tutan bilinçli bir koşullu kaynak düzeni kullanın.

Swift’in #if compiler(...) özelliği derleyici sürümünü, #if canImport(...) ise bir modülün içe aktarılıp aktarılamayacağını sınar. Bu koşulların hiçbiri mevcut bir modülün tekil bir üyesinin çalışan Mac’te kullanılabilir olduğunu göstermez. Bu derleme koşullarını belgelenen amaçları için kullanın; gerektiğinde çalışma zamanı kullanılabilirlik denetimlerinden yararlanın. Deyimler — Koşullu Derleme Bloğu

Swift ABI ve C++ kitaplığı sınırları yanıtı nerede değiştirir?

Swift ABI kararlılığı, standart kitaplığın veya çalışma zamanının her yeni özelliğini eski sistemlerde kullanılabilir kılmaz. Swift’in açıklaması, kaynak dili kipini çalışma zamanı desteğinden ayırır: dil kipi değişikliği derleme zamanı seçimidir; yeni çalışma zamanı işlevselliği gerektiren özelliklerin ise işletim sistemi gereksinimleri olabilir. Benimsediğiniz belirli özelliğin kullanılabilirliğini izleyin. ABI Kararlılığından Sonra Apple Platformlarında Swift’in Gelişimi

C++’ta da derleyici desteği ile kitaplık desteği birbirinden ayrılır. Apple, Xcode aracılığıyla Apple Clang’i ve SDK’ları ile işletim sistemleri aracılığıyla libc++ çalışma zamanını sağlar. Özellik tablosunda, gereksinimlerin işletim sistemi tarafından sağlanan paylaşımlı kitaplığa bağlı olabileceği belirtilir. -std=c++17 veya -std=c++20 seçmek bu çalışma zamanı işlevselliğini kullanıcının Mac’ine yüklemez. C++ dili desteği

Sayısal dönüşüm buna iyi bir örnektir: Apple, tamsayı std::to_chars ve std::from_chars için minimum macOS sürümünü 10.15; kayan noktalı aşırı yüklemeleri içinse 13.3 olarak listeler. Bu nedenle macOS 12 uygulaması, aksi hâlde kayan noktalı aşırı yüklemeleri gerektirecekse uyumlu bir dönüşüm uygulamasına ihtiyaç duyar. Yalnızca başlığa veya C++ standart sürümüne değil, tam aşırı yüklemeye bakın. C++ dili desteği

Her C++ kitaplığı çağrısını __builtin_available ile sarmalamanın yeterli olduğunu varsaymayın. Clang’in kullanılabilirlik öznitelikleri, daha eski bir platform hedeflenirken kullanımı reddeden bir strict biçimi içerir; libc++ ise derleme sırasında eksik çalışma zamanı desteğini bildirmek için kullanılabilirlik işaretlemesinden yararlanır. Seçilen başlıklar işlemi reddediyorsa temel sürümle uyumlu bir uygulama kullanın veya minimum sürümü yükseltin. Clang’de Öznitelikler — kullanılabilirlik, Satıcı Belgeleri — Kullanılabilirlik İşaretlemesi

Bağımlılıklar arasında kitaplığın ABI yapılandırmasını koruyun. LLVM, belirli ABI garantilerini ve bunların sınırlarını belgeliyor; bunlara yeni libc++ başlıklarıyla derlenen kodun eski bir kitaplıkla çalışmayabileceği de dahil. ABI’yi değiştiren yapılandırma bayrakları satıcıya ait denetimlerdir. Bunları uygulama kodunda değiştirmek uyumlu bir çalışma zamanının yerini tutmaz. libc++ ABI Garantileri

Tamamlanmış derlemeyi nasıl tanılar ve doğrularsınız?

Bir sonraki incelemeyi seçmek için hatanın oluştuğu aşamayı kullanın. Bu karar yardımcısı, yukarıdaki derleyici, kullanılabilirlik ve çalışma zamanı sınırlarını izler; örneğin testleri geçtiği iddiasında bulunmaz, bir tanılama sıralamasıdır.

Belirti Önce incelenecek konu Uygulanabilir sonraki adım
Yeni API adı bilinmiyor SDK bildirimleri API’yi içeren bir SDK seçin.
API, dağıtım hedefinden daha yeni Korumasız kullanım Desteklenen bir kullanılabilirlik sınırı ve geri dönüş ekleyin.
C++ kitaplığı işlemi hâlâ reddediliyor Tam aşırı yükleme ve kitaplık gereksinimleri Uyumlu bir uygulama kullanın veya minimum sürümü değiştirin.
Uygulama penceresi görünmeden hata veriyor Yükleme gereksinimleri ve bağımlılıklar Bildirilen eksik kitaplığı veya simgeyi inceleyin.
Yalnızca yeni özellik başarısız oluyor Korunan dalın dışında yapılan işler Oluşturma, başlatma ve yardımcı işlev çağrılarını inceleyin.
Derleme yalnızca bir işlemci ailesinde çalışıyor Yürütülebilir dosya ve bağımlılık mimarileri Gerekli mimari dilimlerini derleyip test edin.

Mimari desteği ek bir gereksinimdir. Apple’ın evrensel ikili dosya kılavuzu, derlenmiş kitaplıklar ve çerçeveler de dahil olmak üzere arm64 ve x86_64 konularını kapsar. Uygulamanın yürütülebilir dosyasının yanı sıra bağımlılıkları da doğrulayın; geliştirme Mac’iniz için başarılı bir derleme yalnızca o derlemenin uyumlu olduğunu gösterir. Evrensel bir macOS ikili dosyası oluşturma

Bu örnek için release yapılandırmasını derleyin ve ortaya çıkan uygulamayı desteklenen donanımlarda macOS 12, macOS 13 ve macOS 14 veya daha yenisinde test edin. Her sistemde boş koleksiyonla başlayın, örnek notu ekleyin ve sıfırlayın. Eski sürümler, geri dönüş üzerinden etkileşimin tamamını sunmalıdır. Dağıtmayı planladığınız her mimariyi test edin.

Uygulama büyüdükçe destek sınırını açık tutun: desteklenen bir dağıtım hedefi, uygun bir SDK’dan alınan bildirimler, korumalı yeni işlevler ve temel sürümde işe yarayan bir uygulama. Eklenen her API veya bağımlılık, derlemenin parçası olmadan önce aynı sözleşmeye uymalıdır.

Kaynaklar