Android Gradle प्लग इन के DSL/API को माइग्रेट करने की टाइमलाइन

Android Gradle प्लगिन (एजीपी), Android ऐप्लिकेशन के लिए काम करने वाला बिल्ड सिस्टम है. इसमें कई तरह के सोर्स कंपाइल करने और उन्हें एक साथ लिंक करके ऐसा ऐप्लिकेशन बनाने की सुविधा शामिल है जिसे Android डिवाइस या एम्युलेटर पर चलाया जा सकता है.

इस सेक्शन में, एजीपी के डीएसएल और एपीआई के प्लान किए गए डेवलपमेंट के बारे में बताया गया है. स्टेबल रिलीज़ में नए एपीआई जोड़े जाने पर, पुराने एपीआई को सेवा में नहीं होने के तौर पर मार्क किया जाएगा. इसके बाद, सेवा में नहीं रहे एपीआई, अगले स्टेबल रिलीज़ में उपलब्ध नहीं होंगे. यहां दिए गए सेक्शन में, एजीपी के हर बड़े रिलीज़ में होने वाले बदलावों के बारे में जानकारी दी गई है.

एजीपी एपीआई के सेवा में नहीं होने या हटाए जाने की ज़्यादा जानकारी के लिए, एजीपी एपीआई अपडेट देखें.

एजीपी 10.0 (साल 2026 के आखिर तक)

Android Gradle प्लगिन 10.0 के एपीआई में बदलाव और मॉडर्नाइज़ेशन

एजीपी 10.0, पूरी तरह से लेज़ी, कॉन्फ़िगरेशन-कैशे-कंपैटिबल बिल्ड मॉडल में ट्रांज़िशन को पूरा करता है. यह रिलीज़, लेगसी, नॉन-लेज़ी एपीआई को ज़्यादा सुरक्षित और बेहतर परफ़ॉर्मेंस वाले आर्किटेक्चर से बदलने के लिए, कई सालों से किए जा रहे काम का नतीजा है.

लेज़ी बिल्ड मॉडल क्यों?

लेगसी, नॉन-लेज़ी बिल्ड मॉडल में, Gradle ऑब्जेक्ट का तुरंत आकलन करता है, वैरिएंट डेटा की क्वेरी करता है, और हर सिंक या बिल्ड इनवोकेशन के दौरान, सभी प्रोजेक्ट मॉड्यूल में टास्क कॉन्फ़िगर करता है. इस तुरंत आकलन की वजह से, उन वैरिएंट और टास्क पर सीपीयू का समय और मेमोरी बर्बाद होती है जो नहीं चल रहे हैं. साथ ही, जटिल बिल्ड स्क्रिप्ट में आकलन के क्रम से जुड़े टकराव होते हैं.

लेज़ी प्रोवाइडर (Provider<T>) और आधुनिक वैरिएंट एपीआई (androidComponents {}) का इस्तेमाल करके, पूरी तरह से लेज़ी बिल्ड मॉडल में ट्रांज़िशन करने पर, प्रॉपर्टी और टास्क वायरिंग का आकलन, सिर्फ़ तब किया जाता है, जब सक्रिय बिल्ड एक्ज़ीक्यूशन ग्राफ़ को इसकी ज़रूरत होती है.

इस रिलीज़ में हटाए जा रहे लेगसी एपीआई, इस आधुनिक आर्किटेक्चर के साथ काम नहीं करते थे. इन्हें हटाने से, एजीपी को Gradle कॉन्फ़िगरेशन कैशे और प्रोजेक्ट आइसोलेशन की पूरी तरह से सुविधा मिलती है. इससे Android Studio में बिल्ड की स्पीड और सिंक के समय में काफ़ी सुधार होता है.

आर्किटेक्चर में मुख्य अंतर

लेगसी BaseVariant एपीआई (applicationVariants.all {}) तुरंत काम करता था और टास्क पर फ़ोकस करता था. इससे डेवलपर को कॉन्फ़िगरेशन फ़ेज़ के दौरान, Gradle टास्क और इंटरनल कॉन्फ़िगरेशन का सीधा ऐक्सेस मिलता था. इससे, Gradle की आधुनिक परफ़ॉर्मेंस से जुड़ी सुविधाएं काम नहीं करती थीं.

नया वैरिएंट एपीआई (androidComponents {}) लेज़ी है और आर्टफ़ैक्ट पर फ़ोकस करता है. यह Gradle के प्रॉपर्टी एपीआई का बड़े पैमाने पर इस्तेमाल करता है और Task और TaskProvider के सभी रेफ़रंस को पूरी तरह से हटा देता है. इसके लिए, आपको टास्क के बजाय इनपुट और आउटपुट (Variant.artifacts) के साथ साफ़ तौर पर इंटरैक्ट करना होगा.

क्या हटाया जा रहा है और उसकी जगह क्या जोड़ा जा रहा है

लेगसी डीएसएल और पुराने वैरिएंट एपीआई में इस्तेमाल किए गए सभी पिछले इंटरफ़ेस और क्लास हटा दिए गए हैं. अपनी बिल्ड स्क्रिप्ट और कस्टम प्लगिन तैयार करने के लिए, सेवा में नहीं रहे इन एपीआई और फ़्लैग से माइग्रेट करें:

बदले गए सभी डीएसएल और वैरिएंट एपीआई (androidComponents {}) इंटरफ़ेस और क्लास को ऐक्सेस करने के लिए, कस्टम Gradle प्लगिन या बिल्ड लॉजिक डेवलप करते समय, हमेशा gradle-api आर्टफ़ैक्ट का इस्तेमाल करें.

माइग्रेशन के चरण

एजीपी 10.0 में अपग्रेड करने की प्रोसेस को आसान और अनुमान के मुताबिक बनाने के लिए, माइग्रेशन के ये तरीके अपनाएं:

1. एजीपी अपग्रेड असिस्टेंट चलाएं: सीधे 10.0 में अपग्रेड करने से पहले, Android Studio में आधिकारिक एजीपी अपग्रेड असिस्टेंट (Tools > AGP Upgrade Assistant) चलाएं. यह डीएसएल और बिल्ड स्क्रिप्ट के कई सामान्य माइग्रेशन को ऑटोमेट करता है. साथ ही, मौजूदा बिल्ड के व्यवहार को बनाए रखने में मदद करता है.
2. Android Studio में एजेंट मोड की सुविधाओं का इस्तेमाल करें: Android Studio में, जटिल बिल्ड लॉजिक और डीएसएल को ऑटोमेट करने और आसान बनाने के लिए, एआई अपग्रेड की सुविधाओं (जैसे, Android की सुविधाओं के रिपॉज़िटरी में उपलब्ध एजीपी अपग्रेड की सुविधाएं) का फ़ायदा लें.
3. सबसे पहले, एजीपी 9.x में सेवा में नहीं होने की चेतावनियों को ठीक करें: अपने प्रोजेक्ट को एजीपी 9.x के नए वर्शन पर अपग्रेड करें और सेवा में नहीं होने की सभी मौजूदा चेतावनियों को ठीक करें. जब आपका प्रोजेक्ट, 9.x के साथ बिना किसी चेतावनी के और android.newDsl=false या android.builtInKotlin=false पर निर्भर हुए बिना काम करता है, तब 10.0 पर माइग्रेट करना आसान होगा.
4. तीसरे पक्ष के Gradle प्लगिन की ऑडिट करें: पक्का करें कि तीसरे पक्ष के प्लगिन, एजीपी 10.0 के साथ काम करने वाले वर्शन पर अपग्रेड किए गए हों. लेगसी एक्सटेंशन टाइप पर अब भी निर्भर रहने वाले प्लगिन की वजह से, बिल्ड में गड़बड़ियां होंगी. जैसे, ClassCastException: ... cannot be cast to class BaseExtension.
5. माइग्रेशन के आधिकारिक तरीके इस्तेमाल करें: जटिल, असल दुनिया के माइग्रेशन के उदाहरण और तुलनाएं देखने के लिए, आधिकारिक gradle-recipes GitHub रिपॉज़िटरी देखें.

यहां, पहले और बाद की तुलना दिखाई गई है. इसमें बताया गया है कि लेगसी वैरिएंट की तुरंत क्वेरी करने के बजाय, androidComponents {} का इस्तेमाल करके, वैरिएंट को लेज़ी तरीके से कैसे कॉन्फ़िगर किया जाए:

पहले: लेगसी वैरिएंट एपीआई (एजीपी 10.0 में हटाया गया)

// Eager evaluation using the legacy Variant API
android {
    applicationVariants.all { variant ->
        if (variant.buildType.name == "release") {
            // Eagerly queries and modifies properties during evaluation
        }
    }
}

बाद में: आधुनिक वैरिएंट एपीआई (androidComponents {})

// Lazy, Configuration Cache compatible Variant API
androidComponents {
    onVariants(selector().withBuildType("release")) { variant ->
        // Safely and lazily configures properties
    }
}

एजीपी 9.x में एजीपी 10.0 के व्यवहार की जांच करने का तरीका

आपको एजीपी 10.0 के रिलीज़ होने का इंतज़ार करने की ज़रूरत नहीं है. इसके बिल्ड के व्यवहार की जांच और कंपैटिबिलिटी की पुष्टि अभी से की जा सकती है. एजीपी 9.x के किसी भी रिलीज़ पर काम करते समय, एजीपी 10.0 के व्यवहार को साफ़ तौर पर लागू किया जा सकता है. इसके लिए, यह पुष्टि करें कि आपके gradle.properties में, ऑप्ट-आउट की सुविधा बंद हो और ये सख्त व्यवहार वाले फ़्लैग सेट हों:

# Enforce modern DSL and Variant API interfaces exclusively
android.newDsl=true

# Enforce built-in Kotlin support without optional opt-out
android.builtInKotlin=true

android.newDsl=true और android.builtInKotlin=true को लागू करके, यह पुष्टि की जा सकती है कि आपका कस्टम बिल्ड लॉजिक और तीसरे पक्ष के प्लगिन, एजीपी 10.0 की सख्त एपीआई की ज़रूरी शर्तों के साथ पूरी तरह से कंपैटिबल हैं.

माइग्रेशन के दौरान, चुनिंदा सब-प्रोजेक्ट के लिए ऑप्ट-आउट की सुविधा

अगर आपको आधुनिक व्यवहार की जांच करने के लिए, अपने प्रोजेक्ट में android.newDsl=true को ग्लोबल तौर पर चालू करना है, लेकिन खास सब-प्रोजेक्ट को माइग्रेट करने के लिए ज़्यादा समय चाहिए, तो एजीपी 9.4.0-alpha04 से, चुनिंदा मॉड्यूल के लिए ऑप्ट-आउट किया जा सकता है. gradle.properties में, प्रोजेक्ट के पाथ तय करके android.newDsl.optOut जोड़ें:

# Enable modern DSL globally across the build
android.newDsl=true

# Selectively opt out specific sub-projects that still require legacy DSL APIs
android.newDsl.optOut=:lib

हर मॉड्यूल के लिए, बिल्ट-इन Kotlin को चुनिंदा तौर पर बंद करना

अगर आपको अपने प्रोजेक्ट में बिल्ट-इन Kotlin को ग्लोबल तौर पर चालू करना है (android.builtInKotlin=true), लेकिन खास सब-प्रोजेक्ट को kotlin-android से माइग्रेट करने के लिए ज़्यादा समय चाहिए (या Kotlin कोड के बिना मॉड्यूल के लिए), तो उन मॉड्यूल को प्रोजेक्ट लेवल के बजाय डीएसएल लेवल पर कॉन्फ़िगर करें. मॉड्यूल की बिल्ड फ़ाइल में, enableKotlin = false सेट करें:

android {
    enableKotlin = false
}

सुझाव/राय देना या शिकायत करना और गड़बड़ी की रिपोर्ट करने का वर्कफ़्लो

हम यह पक्का करना चाहते हैं कि नया वैरिएंट एपीआई, आपके ज़रूरी इस्तेमाल के उदाहरणों के साथ काम करे. अगर आपको पुराने एपीआई से माइग्रेट करने में कोई समस्या आ रही है और नया वैरिएंट एपीआई, आपके इस्तेमाल के उदाहरण के साथ काम नहीं कर रहा है, तो सुझाव/राय देने या शिकायत करने के लिए यह तरीका अपनाएं:

1. मौजूदा आइटम देखें: सबसे पहले, एजीपी 10.0 के वैरिएंट एपीआई की ग्लोबल ट्रैकिंग से जुड़ी गड़बड़ी देखें. इससे पता चलेगा कि माइग्रेशन में आने वाली समस्या पहले से मौजूद है या नहीं. अगर समस्या पहले से मौजूद है, तो उस पर +1 करें.
2. गायब एपीआई की रिपोर्ट करें: अगर आपके इस्तेमाल का उदाहरण यूनीक है, तो एजीपी 10.0 के खास टेंप्लेट का इस्तेमाल करके, नई सुविधा का अनुरोध सबमिट करें. इससे हमें जांच करने और मदद करने में आसानी होगी.

(अस्थायी) एजीपी के निजी इंटरनल क्लास का ऐक्सेस हटाया गया

gradle आर्टफ़ैक्ट पर डिपेंडेंसी होने की वजह से, अब सभी इंटरनल क्लास छिपी रहेंगी. साथ ही, कंपाइलेशन का ऐक्सेस सिर्फ़ gradle-api आर्टफ़ैक्ट में उपलब्ध इंटरफ़ेस और क्लास को मिलेगा. इससे प्लगिन कंपाइलेशन पर असर पड़ता है.

इंटरनल क्लास का ऐक्सेस पाने के लिए, मैन्युअल तरीके से डिपेंडेंसी नहीं जोड़ी जा सकती.

एजीपी 9.0 (जनवरी 2026)

वैरिएंट के नए एपीआई स्टेबल हैं, पुराने एपीआई सेवा में नहीं हैं

वैरिएंट के वे एपीआई जो 4.1 और 4.2 में इनक्यूबेट हो रहे थे, अब स्टेबल हैं और gradle-api आर्टफ़ैक्ट में मौजूद हैं. वैरिएंट के पुराने एपीआई में इस्तेमाल किए गए पिछले इंटरफ़ेस और क्लास अब सेवा में नहीं हैं. इनका इस्तेमाल करने के लिए, साफ़ तौर पर ऑप्ट-इन करना ज़रूरी है.

डीएसएल के नए इंटरफ़ेस स्टेबल हैं, पुराने इंटरफ़ेस सेवा में नहीं हैं

वे डीएसएल इंटरफ़ेस जो 4.1, 4.2, और 7.0 में इनक्यूबेट हो रहे थे, अब स्टेबल हैं और gradle-api आर्टफ़ैक्ट में मौजूद हैं. डीएसएल में इस्तेमाल किए गए पिछले इंटरफ़ेस और क्लास अब सेवा में नहीं हैं. इनका इस्तेमाल करने के लिए, साफ़ तौर पर ऑप्ट-इन करना ज़रूरी है.

एजीपी के निजी इंटरनल क्लास का ऐक्सेस अब भी उपलब्ध है

एजीपी के निजी इंटरनल क्लास, जो अन्य आर्टफ़ैक्ट में मौजूद हैं, बिल्ड फ़ाइलों और प्लगिन के कंपाइलेशन के दौरान अब भी ऐक्सेस किए जा सकते हैं. हालांकि, हम इनका इस्तेमाल करने का सुझाव नहीं देते, क्योंकि इनमें कभी भी बड़े बदलाव हो सकते हैं.