macOS की पुरानी रिलीज़ का समर्थन करने के लिए, ऐसे SDK से बिल्ड करें जो नए API को जानता हो, समर्थित न्यूनतम डिप्लॉयमेंट टारगेट सेट करें, और उपलब्धता जाँचों तथा काम करने वाले फ़ॉलबैक से नए कॉल को सुरक्षित रखें। यह वॉकथ्रू macOS 12 पर एक छोटी नेटिव नोट्स विंडो को उपयोगी बनाए रखते हुए macOS 14 का व्यू अपनाता है।

किन संगतता सेटिंग्स का मेल होना चाहिए?

Mac ऐप डेवलपर के लिए ठोस काम ऐसा एक ऐप बनाना है जो सबसे पुराने समर्थित रिलीज़ पर लॉन्च हो और उपलब्ध होने पर नई सुविधाओं का उपयोग करे। शुरुआत में तीन इनपुट अलग रखें: कंपाइलर सोर्स भाषा को समझता है, SDK API घोषणाएँ देता है, और डिप्लॉयमेंट टारगेट सबसे पुराने लक्षित रनटाइम की पहचान करता है। Apple के बिल्ड सेटिंग्स संदर्भ में SDKROOT को उस SDK के रूप में परिभाषित किया गया है जिसके हेडर और लाइब्रेरी बिल्ड में शामिल होते हैं। बिल्ड सेटिंग्स संदर्भ

नया SDK और पुराना डिप्लॉयमेंट टारगेट साथ काम कर सकते हैं। Clang स्पष्ट रूप से सबसे नए SDK के विरुद्ध बिल्ड करते हुए -mmacos-version-min= से macOS का पुराना न्यूनतम संस्करण चुनने का दस्तावेज़ देता है। इस संयोजन में न्यूनतम संस्करण के बाद आए API के आसपास उपलब्धता जाँचें फिर भी आवश्यक हैं। Clang भाषा एक्सटेंशन

ऐसा न्यूनतम संस्करण चुनें जिसे आपका चुना हुआ Xcode वास्तव में समर्थन करता हो। Apple की संगतता तालिका Xcode चलाने के लिए आवश्यक macOS संस्करण और उन डिप्लॉयमेंट टारगेट में अंतर बताती है जिनके लिए वह बिल्ड कर सकता है। यदि आपका इच्छित न्यूनतम संस्करण उस टूलचेन की समर्थित सीमा से बाहर है, तो उपयुक्त समर्थित टूलचेन चुनें या फ़ॉलबैक लागू करने से पहले ऐप का न्यूनतम संस्करण संशोधित करें। SDK और सिस्टम आवश्यकताएँ

इस काल्पनिक उदाहरण के लिए अनुबंध है: macOS 12 या बाद का संस्करण, macOS 14 API वाला SDK, और दो अवस्थाओं वाली नोट्स विंडो—खाली संग्रह और एक नमूना नोट। नया खाली-अवस्था प्रस्तुतीकरण वैकल्पिक है; नोट दिखाना बेसलाइन पर भी उपलब्ध रहता है।

दोनों बिल्ड कॉन्फ़िगरेशन में न्यूनतम संस्करण सेट करें

ऐप टारगेट की Build Settings में, Debug और Release दोनों के लिए MACOSX_DEPLOYMENT_TARGET को 12.0 पर सेट करें। यदि आप कॉन्फ़िगरेशन फ़ाइलों में सेटिंग प्रबंधित करते हैं, तो यह एक संपूर्ण कॉन्फ़िगरेशन अंश है, प्रोग्राम नहीं:

MACOSX_DEPLOYMENT_TARGET = 12.0

प्रोजेक्ट के Info टैब में कॉन्फ़िगरेशन फ़ाइल को इच्छित कॉन्फ़िगरेशन से जोड़ें। इसके बाद टारगेट का अंतिम मान जाँचें: Apple के दस्तावेज़ के अनुसार टारगेट सेटिंग्स किसी असाइन की गई कॉन्फ़िगरेशन फ़ाइल से दिए गए मानों को ओवरराइड कर सकती हैं। केवल फ़ाइल को प्रोजेक्ट में जोड़ने से उसकी सेटिंग्स प्रभावी नहीं होतीं। अपने प्रोजेक्ट में बिल्ड कॉन्फ़िगरेशन फ़ाइल जोड़ना

ऐप का न्यूनतम संस्करण बढ़ाए बिना नया API कैसे जोड़ें?

Swift का if #available रनटाइम उपलब्धता जाँचता है और कंपाइलर को बताता है कि उस ब्रांच के भीतर किन API का उपयोग अनुमत है। फ़ॉलबैक को उसी निर्णय में रखें ताकि पुराने सिस्टम पर पूरा कार्यान्वयन उपलब्ध हो। आवश्यक * उन प्लेटफ़ॉर्म को कवर करता है जिनका स्पष्ट उल्लेख नहीं है; इससे नामित macOS API पहले के रिलीज़ पर उपलब्ध नहीं हो जाता। कंट्रोल फ़्लो — API उपलब्धता जाँचना

Apple का ContentUnavailableView macOS 14 से उपलब्ध है और खाली सामग्री के प्रस्तुतीकरण का समर्थन करता है। यहाँ एक छोटा VStack macOS 12 और 13 पर वैसा ही प्रस्तुतीकरण देता है। दोनों ब्रांच अगला कदम एक ही तरह से बताती हैं। ContentUnavailableView

संपूर्ण काल्पनिक SwiftUI ऐप

CompatibilityNotes नाम का macOS ऐप प्रोजेक्ट बनाएँ, Swift और SwiftUI चुनें, और उसका डिप्लॉयमेंट टारगेट 12.0 पर सेट करें। macOS 14 API वाले SDK का उपयोग करें। जनरेट की गई ऐप और कंटेंट-व्यू घोषणाओं को नीचे दी गई एकल फ़ाइल से बदलें और सुनिश्चित करें कि टारगेट में केवल एक @main घोषणा हो। किसी एसेट, पैकेज या इनपुट फ़ाइल की आवश्यकता नहीं है।

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

अपेक्षित व्यवहार सरल है: macOS 12 और 13 पर टेक्स्ट फ़ॉलबैक दिखता है; macOS 14 और बाद के संस्करणों पर ContentUnavailableView दिखता है। Add sample note चुनने पर काल्पनिक नोट दिखता है। Reset sample चुनने पर खाली अवस्था फिर से आती है। यह प्रदर्शन डेटा को मेमोरी में रखता है और लॉन्च के बीच नोट सहेजता नहीं है।

@available एनोटेशन हेल्पर के उपयोग को macOS 14 और बाद के संस्करणों तक सीमित करता है। कॉलर की #available ब्रांच इस सीमा को पूरा करती है। एनोटेशन किसी घोषणा की उपलब्धता बताता है; यह पुराना कार्यान्वयन उपलब्ध नहीं कराता। एट्रिब्यूट — available

इस उदाहरण को प्राप्त दस्तावेज़ों के आधार पर देखा गया, लेकिन कंपाइल या चलाया नहीं गया: उपलब्ध निष्पादन वातावरण Linux था और उसमें Swift या Clang इंस्टॉल नहीं थे। macOS पर बिल्ड और रनटाइम जाँच अब भी आवश्यक हैं।

लिंक समय पर उपलब्धता जाँचें क्या हल करती हैं?

रनटाइम ब्रांच तभी उपयोगी है जब एक्ज़ीक्यूटेबल लोड हो सके। Clang दस्तावेज़ देता है कि डिप्लॉयमेंट टारगेट के बाद आए उपलब्धता-एनोटेटेड घोषणाओं को सामान्यतः वीकली लिंक किया जा सकता है। वीक रेफ़रेंस से घोषणा रनटाइम पर अनुपस्थित हो सकती है; फिर भी ऐप को उसके अनुपस्थित होने पर उसका उपयोग नहीं करना चाहिए। इसलिए ब्रांच के साथ डिप्लॉयमेंट टारगेट और कंपाइल के दौरान दिखने वाली घोषणाएँ भी मायने रखती हैं। Clang में एट्रिब्यूट — availability

इस उदाहरण के लिए SwiftUI को सामान्य रूप से लिंक रखें: macOS 12 बेसलाइन पर यह फ़्रेमवर्क पहले से मौजूद है। संगतता सीमा नए व्यू के आसपास रखें। यदि कोई पूरी तरह नया फ़्रेमवर्क आपकी बेसलाइन पर मौजूद नहीं है, तो फ़्रेमवर्क की निर्भरता का स्वयं आकलन करें; एक कॉल को सुरक्षित रखने से लोडिंग की हर आवश्यकता हल नहीं होती। Apple की वीक-लिंकिंग गाइड किसी अनुपस्थित सिंबल की अनुमति देने और वास्तव में उसका उपयोग करने के बीच का अंतर समझाती है। फ़्रेमवर्क और वीक लिंकिंग

सोर्स भाषा के अनुरूप उपलब्धता सिंटैक्स का उपयोग करें:

सोर्स भाषा रनटाइम उपलब्धता शर्त
Swift if #available(macOS 14.0, *)
Objective-C या Objective-C++ if (@available(macOS 14.0, *))
Clang के Apple-प्लेटफ़ॉर्म समर्थन वाला C या C++ if (__builtin_available(macOS 14.0, *))

Clang Objective-C का रूप और C/C++ बिल्ट-इन, साथ ही -Wunguarded-availability, दस्तावेज़ करता है। C-फ़ैमिली कोड के लिए उपलब्धता डायग्नॉस्टिक्स सक्षम करें और पुराने डिप्लॉयमेंट टारगेट को उपयोग योग्य मानने से पहले चेतावनियों की जाँच करें। Clang भाषा एक्सटेंशन

यदि बिल्ड SDK में API नहीं है तो क्या करें?

रनटाइम जाँच SDK में अनुपस्थित घोषणा उपलब्ध नहीं करा सकती। यदि कंपाइलर ContentUnavailableView को पहचान नहीं पा रहा, तो ऐसे SDK से बिल्ड करें जिसमें यह मौजूद हो। यदि प्रोजेक्ट को पुराने SDK से भी बिल्ड करना आवश्यक है, तो जानबूझकर ऐसी सशर्त सोर्स व्यवस्था रखें जो उन बिल्ड से असमर्थित संदर्भों को बाहर रखे।

Swift का #if compiler(...) कंपाइलर संस्करण जाँचता है, जबकि #if canImport(...) जाँचता है कि कोई मॉड्यूल इंपोर्ट किया जा सकता है या नहीं। इनमें से कोई भी यह स्थापित नहीं करता कि मौजूदा मॉड्यूल का कोई खास सदस्य चल रहे Mac पर उपलब्ध है। इन कंपाइलेशन शर्तों का उपयोग उनके दस्तावेज़ित उद्देश्यों के लिए करें, फिर जहाँ ज़रूरी हो रनटाइम उपलब्धता जाँचें। स्टेटमेंट — सशर्त कंपाइलेशन ब्लॉक

Swift ABI और C++ लाइब्रेरी की सीमाएँ उत्तर को कहाँ बदलती हैं?

Swift ABI की स्थिरता से पुराने सिस्टम पर हर नया स्टैंडर्ड-लाइब्रेरी या रनटाइम फ़ीचर उपलब्ध नहीं हो जाता। Swift की व्याख्या सोर्स-भाषा मोड और रनटाइम समर्थन में अंतर बताती है: भाषा-मोड बदलना कंपाइल-समय का विकल्प है, जबकि नए रनटाइम फ़ंक्शन की आवश्यकता वाले फ़ीचर पर OS की आवश्यकताएँ लागू हो सकती हैं। अपनाए गए विशिष्ट फ़ीचर की उपलब्धता का पालन करें। ABI स्थिरता के बाद Apple प्लेटफ़ॉर्म पर Swift का विकास

C++ में भी कंपाइलर समर्थन और लाइब्रेरी समर्थन अलग-अलग हैं। Apple Xcode के माध्यम से Apple Clang और अपने SDK तथा ऑपरेटिंग सिस्टम के माध्यम से libc++ रनटाइम देता है। इसकी फ़ीचर तालिका उन आवश्यकताओं की पहचान करती है जो OS द्वारा दी गई साझा लाइब्रेरी पर निर्भर हो सकती हैं। -std=c++17 या -std=c++20 चुनने से उपयोगकर्ता के Mac पर वह रनटाइम फ़ंक्शन इंस्टॉल नहीं होता। C++ भाषा समर्थन

एक उपयोगी उदाहरण संख्यात्मक रूपांतरण है: Apple इंटीग्रल std::to_chars और std::from_chars के लिए macOS 10.15 को न्यूनतम बताता है, लेकिन उनके फ़्लोटिंग-पॉइंट ओवरलोड के लिए macOS 13.3 को। इसलिए macOS 12 ऐप को संगत रूपांतरण कार्यान्वयन चाहिए, यदि अन्यथा उसे उन फ़्लोटिंग-पॉइंट ओवरलोड की आवश्यकता होती। केवल हेडर या C++ स्टैंडर्ड संस्करण नहीं, बल्कि सटीक ओवरलोड जाँचें। C++ भाषा समर्थन

यह न मानें कि हर C++ लाइब्रेरी कॉल को __builtin_available में लपेटना पर्याप्त है। Clang के उपलब्धता एट्रिब्यूट में strict रूप शामिल है, जो पुराने प्लेटफ़ॉर्म को लक्ष्य बनाते समय उपयोग अस्वीकार करता है, और libc++ कंपाइल के दौरान रनटाइम समर्थन की कमी का पता लगाने के लिए उपलब्धता मार्कअप का उपयोग करता है। जहाँ चुने गए हेडर ऑपरेशन को अस्वीकार करते हैं, वहाँ बेसलाइन-संगत कार्यान्वयन उपयोग करें या न्यूनतम संस्करण बढ़ाएँ। Clang में एट्रिब्यूट — availability, विक्रेता दस्तावेज़ — उपलब्धता मार्कअप

निर्भरताओं में लाइब्रेरी का ABI कॉन्फ़िगरेशन समान रखें। LLVM विशिष्ट ABI गारंटियों और उनकी सीमाओं, दोनों का दस्तावेज़ देता है; इनमें यह भी शामिल है कि नए libc++ हेडर के विरुद्ध कंपाइल किया गया कोड किसी पुरानी लाइब्रेरी के साथ काम न करे। इसके ABI को बदलने वाले कॉन्फ़िगरेशन फ़्लैग विक्रेता के नियंत्रण हैं। ऐप कोड में इन्हें बदलना संगत रनटाइम का विकल्प नहीं है। libc++ की ABI गारंटियाँ

तैयार बिल्ड की समस्या का पता कैसे लगाएँ और उसे कैसे सत्यापित करें?

अगली जाँच चुनने के लिए विफलता के चरण का उपयोग करें। यह निर्णय-सहायिका ऊपर दिए गए कंपाइलर, उपलब्धता और रनटाइम की सीमाओं का अनुसरण करती है; यह डायग्नॉस्टिक क्रम है, इस बात का दावा नहीं कि नमूने ने परीक्षण पास कर लिया है।

लक्षण पहले किसकी जाँच करें व्यावहारिक अगला कदम
नया API नाम अज्ञात है SDK घोषणाएँ ऐसा SDK चुनें जिसमें API मौजूद हो।
API डिप्लॉयमेंट टारगेट से नया है बिना सुरक्षा वाला उपयोग समर्थित उपलब्धता सीमा और फ़ॉलबैक जोड़ें।
C++ लाइब्रेरी ऑपरेशन अब भी अस्वीकृत है सटीक ओवरलोड और लाइब्रेरी की आवश्यकताएँ संगत कार्यान्वयन उपयोग करें या न्यूनतम संस्करण संशोधित करें।
विंडो दिखने से पहले ऐप विफल हो जाता है लोडिंग आवश्यकताएँ और निर्भरताएँ रिपोर्ट की गई अनुपस्थित लाइब्रेरी या सिंबल की जाँच करें।
केवल नया फ़ीचर विफल होता है सुरक्षित ब्रांच के बाहर किया गया काम निर्माण, इनिशियलाइज़ेशन और हेल्पर कॉल की जाँच करें।
बिल्ड केवल एक प्रोसेसर परिवार पर काम करता है एक्ज़ीक्यूटेबल और निर्भरता आर्किटेक्चर आवश्यक आर्किटेक्चर स्लाइस बनाएं और जाँचें।

आर्किटेक्चर समर्थन एक अतिरिक्त आवश्यकता है। Apple की यूनिवर्सल-बाइनरी गाइड arm64 और x86_64 को कवर करती है, जिनमें कंपाइल की गई लाइब्रेरी और फ़्रेमवर्क शामिल हैं। ऐप एक्ज़ीक्यूटेबल के साथ निर्भरताओं की भी जाँच करें; आपके डेवलपमेंट Mac के लिए सफल बिल्ड केवल उसी बिल्ड की संगतता साबित करता है। यूनिवर्सल macOS बाइनरी बनाना

इस नमूने के लिए रिलीज़ कॉन्फ़िगरेशन बिल्ड करें और परिणामी ऐप को समर्थित हार्डवेयर पर macOS 12, macOS 13, और macOS 14 या बाद के संस्करणों में जाँचें। हर सिस्टम पर खाली संग्रह के साथ लॉन्च करें, नमूना नोट जोड़ें और उसे रीसेट करें। पुराने रिलीज़ पर फ़ॉलबैक के ज़रिए पूरा इंटरैक्शन उपलब्ध रहना चाहिए। हर उस आर्किटेक्चर की जाँच करें जिसे वितरित करने का इरादा है।

ऐप बढ़ने के साथ समर्थन सीमा स्पष्ट रखें: समर्थित डिप्लॉयमेंट टारगेट, उपयुक्त SDK से घोषणाएँ, सुरक्षित नए फ़ंक्शन और उपयोगी बेसलाइन कार्यान्वयन। बिल्ड का हिस्सा बनने से पहले हर अतिरिक्त API या निर्भरता को इसी अनुबंध के अनुरूप होना चाहिए।

स्रोत