स्रोत जनरेटर

यह पृष्ठ इस बात का उच्च-स्तरीय दृश्य प्रदान करता है कि जेनरेट किए गए स्रोत का समर्थन कैसे किया जाता है और इसे बिल्ड सिस्टम में कैसे उपयोग किया जा सकता है।

सभी स्रोत जनरेटर समान बिल्ड-सिस्टम कार्यक्षमता प्रदान करते हैं। तीन बिल्ड-सिस्टम समर्थित स्रोत-पीढ़ी उपयोग के मामले बाइंडजेन, एआईडीएल इंटरफेस और प्रोटोबफ इंटरफेस का उपयोग करके सी बाइंडिंग उत्पन्न कर रहे हैं।

उत्पन्न स्रोत से टोकरे

स्रोत कोड उत्पन्न करने वाले प्रत्येक रस्ट मॉड्यूल को एक टोकरे के रूप में उपयोग किया जा सकता है, बिल्कुल वैसे ही जैसे कि इसे एक rust_library के रूप में परिभाषित किया गया हो। (इसका मतलब है कि इसे rustlibs , rlibs और dylibs गुणों में निर्भरता के रूप में परिभाषित किया जा सकता है।) प्लेटफ़ॉर्म कोड के लिए सबसे अच्छा उपयोग पैटर्न जेनरेट किए गए स्रोत को क्रेट के रूप में नियोजित करना है। हालाँकि इसमें include! मैक्रो जेनरेट किए गए स्रोत के लिए समर्थित है, इसका प्राथमिक उद्देश्य external/ में मौजूद तृतीय-पक्ष कोड का समर्थन करना है।

ऐसे मामले हैं जहां प्लेटफ़ॉर्म कोड अभी भी include!() मैक्रो के माध्यम से उत्पन्न स्रोत का उपयोग कर सकता है, जैसे कि जब आप एक अनूठे तरीके से स्रोत उत्पन्न करने के लिए genrule मॉड्यूल का उपयोग करते हैं।

उत्पन्न स्रोत को शामिल करने के लिए include!() का उपयोग करें

जेनरेट किए गए स्रोत को क्रेट के रूप में उपयोग करना प्रत्येक विशिष्ट (संबंधित) मॉड्यूल पृष्ठ में उदाहरणों द्वारा कवर किया गया है। यह अनुभाग दिखाता है कि include!() मैक्रो के माध्यम से जेनरेट किए गए स्रोत को कैसे संदर्भित किया जाए। ध्यान दें कि यह प्रक्रिया सभी स्रोत जनरेटर के लिए समान है।

शर्त

यह उदाहरण इस धारणा पर आधारित है कि आपने एक rust_bindgen मॉड्यूल ( libbuzz_bindgen ) को परिभाषित किया है और include!() मैक्रो का उपयोग करने के लिए जेनरेट किए गए स्रोत को शामिल करने के चरणों पर आगे बढ़ सकते हैं। यदि आपने नहीं किया है, तो कृपया डिफाइनिंग अ रस्ट बाइंडजेन मॉड्यूल पर जाएं, libbuzz_bindgen बनाएं, फिर यहां वापस आएं।

ध्यान दें कि इसका बिल्ड-फ़ाइल भाग सभी स्रोत जनरेटर के लिए लागू है।

उत्पन्न स्रोत को शामिल करने के चरण

निम्नलिखित सामग्री के साथ external/rust/hello_bindgen/Android.bp बनाएं:

rust_binary {
   name: "hello_bzip_bindgen_include",
   srcs: [
         // The primary rust source file must come first in this list.
         "src/lib.rs",

         // The module providing the bindgen bindings is
         // included in srcs prepended by ":".
         ":libbuzz_bindgen",
    ],

    // Dependencies need to be redeclared when generated source is used via srcs.
    shared_libs: [
        "libbuzz",
    ],
}

निम्नलिखित सामग्री के साथ external/rust/hello_bindgen/src/bindings.rs बनाएं:

#![allow(clippy::all)]
#![allow(non_upper_case_globals)]
#![allow(non_camel_case_types)]
#![allow(non_snake_case)]
#![allow(unused)]
#![allow(missing_docs)]

// Note that "bzip_bindings.rs" here must match the source_stem property from
// the rust_bindgen module.
include!(concat!(env!("OUT_DIR"), "/bzip_bindings.rs"));

निम्नलिखित सामग्री के साथ external/rust/hello_bindgen/src/lib.rs बनाएं:

mod bindings;

fn main() {
    let mut x = bindings::foo { x: 2 };
    unsafe { bindings::fizz(1, &mut x as *mut bindings::foo) }
}

उत्पन्न स्रोत के लिए क्रेट क्यों

सी/सी++ कंपाइलर्स के विपरीत, rustc केवल एक एकल स्रोत फ़ाइल को स्वीकार करता है जो बाइनरी या लाइब्रेरी में प्रवेश बिंदु का प्रतिनिधित्व करता है। यह अपेक्षा करता है कि स्रोत वृक्ष को ऐसे संरचित किया जाए कि सभी आवश्यक स्रोत फ़ाइलें स्वचालित रूप से खोजी जा सकें। इसका मतलब यह है कि उत्पन्न स्रोत को या तो स्रोत ट्री में रखा जाना चाहिए, या स्रोत में शामिल निर्देश के माध्यम से प्रदान किया जाना चाहिए:

include!("/path/to/hello.rs");

इस अंतर के साथ काम करने के लिए रस्ट समुदाय build.rs स्क्रिप्ट और कार्गो बिल्ड वातावरण के बारे में धारणाओं पर निर्भर करता है। जब यह बनता है, तो cargo कमांड एक OUT_DIR पर्यावरण चर सेट करता है जिसमें build.rs स्क्रिप्ट से जेनरेट किए गए स्रोत कोड को रखने की उम्मीद की जाती है। स्रोत कोड शामिल करने के लिए निम्नलिखित कमांड का उपयोग करें:

include!(concat!(env!("OUT_DIR"), "/hello.rs"));

यह सूंग के लिए एक चुनौती प्रस्तुत करता है क्योंकि प्रत्येक मॉड्यूल के आउटपुट को उनकी अपनी out/ डायरेक्टरी ¹ में रखा जाता है। ऐसा एक भी OUT_DIR नहीं है जहां निर्भरताएँ अपने उत्पन्न स्रोत को आउटपुट करती हैं।

प्लेटफ़ॉर्म कोड के लिए, AOSP कई कारणों से उत्पन्न स्रोत को एक टोकरे में पैक करना पसंद करता है जिसे आयात किया जा सकता है:

• उत्पन्न स्रोत फ़ाइल नामों को टकराने से रोकें।
• पूरे ट्री में चेक-इन किए गए बॉयलरप्लेट कोड को कम करें जिसके रखरखाव की आवश्यकता है। जेनरेट किए गए स्रोत को एक क्रेट में संकलित करने के लिए आवश्यक किसी भी बॉयलरप्लेट को केंद्रीय रूप से बनाए रखा जा सकता है।
• जेनरेट किए गए कोड और आसपास के क्रेट के बीच अंतर्निहित ² इंटरैक्शन से बचें।
• आमतौर पर उपयोग किए जाने वाले जेनरेटेड स्रोतों को गतिशील रूप से लिंक करके मेमोरी और डिस्क पर दबाव कम करें।

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

,

यह पृष्ठ इस बात का उच्च-स्तरीय दृश्य प्रदान करता है कि जेनरेट किए गए स्रोत का समर्थन कैसे किया जाता है और इसे बिल्ड सिस्टम में कैसे उपयोग किया जा सकता है।

सभी स्रोत जनरेटर समान बिल्ड-सिस्टम कार्यक्षमता प्रदान करते हैं। तीन बिल्ड-सिस्टम समर्थित स्रोत-पीढ़ी उपयोग के मामले बाइंडजेन, एआईडीएल इंटरफेस और प्रोटोबफ इंटरफेस का उपयोग करके सी बाइंडिंग उत्पन्न कर रहे हैं।

उत्पन्न स्रोत से टोकरे

स्रोत कोड उत्पन्न करने वाले प्रत्येक रस्ट मॉड्यूल को एक टोकरे के रूप में उपयोग किया जा सकता है, बिल्कुल वैसे ही जैसे कि इसे एक rust_library के रूप में परिभाषित किया गया हो। (इसका मतलब है कि इसे rustlibs , rlibs और dylibs गुणों में निर्भरता के रूप में परिभाषित किया जा सकता है।) प्लेटफ़ॉर्म कोड के लिए सबसे अच्छा उपयोग पैटर्न जेनरेट किए गए स्रोत को क्रेट के रूप में नियोजित करना है। हालाँकि इसमें include! मैक्रो जेनरेट किए गए स्रोत के लिए समर्थित है, इसका प्राथमिक उद्देश्य external/ में मौजूद तृतीय-पक्ष कोड का समर्थन करना है।

ऐसे मामले हैं जहां प्लेटफ़ॉर्म कोड अभी भी include!() मैक्रो के माध्यम से उत्पन्न स्रोत का उपयोग कर सकता है, जैसे कि जब आप एक अनूठे तरीके से स्रोत उत्पन्न करने के लिए genrule मॉड्यूल का उपयोग करते हैं।

उत्पन्न स्रोत को शामिल करने के लिए include!() का उपयोग करें

जेनरेट किए गए स्रोत को क्रेट के रूप में उपयोग करना प्रत्येक विशिष्ट (संबंधित) मॉड्यूल पृष्ठ में उदाहरणों द्वारा कवर किया गया है। यह अनुभाग दिखाता है कि include!() मैक्रो के माध्यम से जेनरेट किए गए स्रोत को कैसे संदर्भित किया जाए। ध्यान दें कि यह प्रक्रिया सभी स्रोत जनरेटर के लिए समान है।

शर्त

यह उदाहरण इस धारणा पर आधारित है कि आपने एक rust_bindgen मॉड्यूल ( libbuzz_bindgen ) को परिभाषित किया है और include!() मैक्रो का उपयोग करने के लिए जेनरेट किए गए स्रोत को शामिल करने के चरणों पर आगे बढ़ सकते हैं। यदि आपने नहीं किया है, तो कृपया डिफाइनिंग अ रस्ट बाइंडजेन मॉड्यूल पर जाएं, libbuzz_bindgen बनाएं, फिर यहां वापस आएं।

ध्यान दें कि इसका बिल्ड-फ़ाइल भाग सभी स्रोत जनरेटर के लिए लागू है।

उत्पन्न स्रोत को शामिल करने के चरण

निम्नलिखित सामग्री के साथ external/rust/hello_bindgen/Android.bp बनाएं:

rust_binary {
   name: "hello_bzip_bindgen_include",
   srcs: [
         // The primary rust source file must come first in this list.
         "src/lib.rs",

         // The module providing the bindgen bindings is
         // included in srcs prepended by ":".
         ":libbuzz_bindgen",
    ],

    // Dependencies need to be redeclared when generated source is used via srcs.
    shared_libs: [
        "libbuzz",
    ],
}

निम्नलिखित सामग्री के साथ external/rust/hello_bindgen/src/bindings.rs बनाएं:

#![allow(clippy::all)]
#![allow(non_upper_case_globals)]
#![allow(non_camel_case_types)]
#![allow(non_snake_case)]
#![allow(unused)]
#![allow(missing_docs)]

// Note that "bzip_bindings.rs" here must match the source_stem property from
// the rust_bindgen module.
include!(concat!(env!("OUT_DIR"), "/bzip_bindings.rs"));

निम्नलिखित सामग्री के साथ external/rust/hello_bindgen/src/lib.rs बनाएं:

mod bindings;

fn main() {
    let mut x = bindings::foo { x: 2 };
    unsafe { bindings::fizz(1, &mut x as *mut bindings::foo) }
}

उत्पन्न स्रोत के लिए क्रेट क्यों

सी/सी++ कंपाइलर्स के विपरीत, rustc केवल एक एकल स्रोत फ़ाइल को स्वीकार करता है जो बाइनरी या लाइब्रेरी में प्रवेश बिंदु का प्रतिनिधित्व करता है। यह अपेक्षा करता है कि स्रोत वृक्ष को ऐसे संरचित किया जाए कि सभी आवश्यक स्रोत फ़ाइलें स्वचालित रूप से खोजी जा सकें। इसका मतलब यह है कि उत्पन्न स्रोत को या तो स्रोत ट्री में रखा जाना चाहिए, या स्रोत में शामिल निर्देश के माध्यम से प्रदान किया जाना चाहिए:

include!("/path/to/hello.rs");

इस अंतर के साथ काम करने के लिए रस्ट समुदाय build.rs स्क्रिप्ट और कार्गो बिल्ड वातावरण के बारे में धारणाओं पर निर्भर करता है। जब यह बनता है, तो cargo कमांड एक OUT_DIR पर्यावरण चर सेट करता है जिसमें build.rs स्क्रिप्ट से जेनरेट किए गए स्रोत कोड को रखने की उम्मीद की जाती है। स्रोत कोड शामिल करने के लिए निम्नलिखित कमांड का उपयोग करें:

include!(concat!(env!("OUT_DIR"), "/hello.rs"));

यह सूंग के लिए एक चुनौती प्रस्तुत करता है क्योंकि प्रत्येक मॉड्यूल के आउटपुट को उनकी अपनी out/ डायरेक्टरी ¹ में रखा जाता है। ऐसा एक भी OUT_DIR नहीं है जहां निर्भरताएँ अपने उत्पन्न स्रोत को आउटपुट करती हैं।

प्लेटफ़ॉर्म कोड के लिए, AOSP कई कारणों से उत्पन्न स्रोत को एक टोकरे में पैक करना पसंद करता है जिसे आयात किया जा सकता है:

• उत्पन्न स्रोत फ़ाइल नामों को टकराने से रोकें।
• पूरे ट्री में चेक-इन किए गए बॉयलरप्लेट कोड को कम करें जिसके रखरखाव की आवश्यकता है। जेनरेट किए गए स्रोत को एक क्रेट में संकलित करने के लिए आवश्यक किसी भी बॉयलरप्लेट को केंद्रीय रूप से बनाए रखा जा सकता है।
• जेनरेट किए गए कोड और आसपास के क्रेट के बीच अंतर्निहित ² इंटरैक्शन से बचें।
• आमतौर पर उपयोग किए जाने वाले जेनरेटेड स्रोतों को गतिशील रूप से लिंक करके मेमोरी और डिस्क पर दबाव कम करें।

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

,

यह पृष्ठ इस बात का उच्च-स्तरीय दृश्य प्रदान करता है कि जेनरेट किए गए स्रोत का समर्थन कैसे किया जाता है और इसे बिल्ड सिस्टम में कैसे उपयोग किया जा सकता है।

सभी स्रोत जनरेटर समान बिल्ड-सिस्टम कार्यक्षमता प्रदान करते हैं। तीन बिल्ड-सिस्टम समर्थित स्रोत-पीढ़ी उपयोग के मामले बाइंडजेन, एआईडीएल इंटरफेस और प्रोटोबफ इंटरफेस का उपयोग करके सी बाइंडिंग उत्पन्न कर रहे हैं।

उत्पन्न स्रोत से टोकरे

स्रोत कोड उत्पन्न करने वाले प्रत्येक रस्ट मॉड्यूल को एक टोकरे के रूप में उपयोग किया जा सकता है, बिल्कुल वैसे ही जैसे कि इसे एक rust_library के रूप में परिभाषित किया गया हो। (इसका मतलब है कि इसे rustlibs , rlibs और dylibs गुणों में निर्भरता के रूप में परिभाषित किया जा सकता है।) प्लेटफ़ॉर्म कोड के लिए सबसे अच्छा उपयोग पैटर्न जेनरेट किए गए स्रोत को क्रेट के रूप में नियोजित करना है। हालाँकि इसमें include! मैक्रो जेनरेट किए गए स्रोत के लिए समर्थित है, इसका प्राथमिक उद्देश्य external/ में मौजूद तृतीय-पक्ष कोड का समर्थन करना है।

ऐसे मामले हैं जहां प्लेटफ़ॉर्म कोड अभी भी include!() मैक्रो के माध्यम से उत्पन्न स्रोत का उपयोग कर सकता है, जैसे कि जब आप एक अनूठे तरीके से स्रोत उत्पन्न करने के लिए genrule मॉड्यूल का उपयोग करते हैं।

उत्पन्न स्रोत को शामिल करने के लिए include!() का उपयोग करें

जेनरेट किए गए स्रोत को क्रेट के रूप में उपयोग करना प्रत्येक विशिष्ट (संबंधित) मॉड्यूल पृष्ठ में उदाहरणों द्वारा कवर किया गया है। यह अनुभाग दिखाता है कि include!() मैक्रो के माध्यम से जेनरेट किए गए स्रोत को कैसे संदर्भित किया जाए। ध्यान दें कि यह प्रक्रिया सभी स्रोत जनरेटर के लिए समान है।

शर्त

यह उदाहरण इस धारणा पर आधारित है कि आपने एक rust_bindgen मॉड्यूल ( libbuzz_bindgen ) को परिभाषित किया है और include!() मैक्रो का उपयोग करने के लिए जेनरेट किए गए स्रोत को शामिल करने के चरणों पर आगे बढ़ सकते हैं। यदि आपने नहीं किया है, तो कृपया डिफाइनिंग अ रस्ट बाइंडजेन मॉड्यूल पर जाएं, libbuzz_bindgen बनाएं, फिर यहां वापस आएं।

ध्यान दें कि इसका बिल्ड-फ़ाइल भाग सभी स्रोत जनरेटर के लिए लागू है।

उत्पन्न स्रोत को शामिल करने के चरण

निम्नलिखित सामग्री के साथ external/rust/hello_bindgen/Android.bp बनाएं:

rust_binary {
   name: "hello_bzip_bindgen_include",
   srcs: [
         // The primary rust source file must come first in this list.
         "src/lib.rs",

         // The module providing the bindgen bindings is
         // included in srcs prepended by ":".
         ":libbuzz_bindgen",
    ],

    // Dependencies need to be redeclared when generated source is used via srcs.
    shared_libs: [
        "libbuzz",
    ],
}

निम्नलिखित सामग्री के साथ external/rust/hello_bindgen/src/bindings.rs बनाएं:

#![allow(clippy::all)]
#![allow(non_upper_case_globals)]
#![allow(non_camel_case_types)]
#![allow(non_snake_case)]
#![allow(unused)]
#![allow(missing_docs)]

// Note that "bzip_bindings.rs" here must match the source_stem property from
// the rust_bindgen module.
include!(concat!(env!("OUT_DIR"), "/bzip_bindings.rs"));

निम्नलिखित सामग्री के साथ external/rust/hello_bindgen/src/lib.rs बनाएं:

mod bindings;

fn main() {
    let mut x = bindings::foo { x: 2 };
    unsafe { bindings::fizz(1, &mut x as *mut bindings::foo) }
}

उत्पन्न स्रोत के लिए क्रेट क्यों

सी/सी++ कंपाइलर्स के विपरीत, rustc केवल एक एकल स्रोत फ़ाइल को स्वीकार करता है जो बाइनरी या लाइब्रेरी में प्रवेश बिंदु का प्रतिनिधित्व करता है। यह अपेक्षा करता है कि स्रोत वृक्ष को ऐसे संरचित किया जाए कि सभी आवश्यक स्रोत फ़ाइलें स्वचालित रूप से खोजी जा सकें। इसका मतलब यह है कि उत्पन्न स्रोत को या तो स्रोत ट्री में रखा जाना चाहिए, या स्रोत में शामिल निर्देश के माध्यम से प्रदान किया जाना चाहिए:

include!("/path/to/hello.rs");

इस अंतर के साथ काम करने के लिए रस्ट समुदाय build.rs स्क्रिप्ट और कार्गो बिल्ड वातावरण के बारे में धारणाओं पर निर्भर करता है। जब यह बनता है, तो cargo कमांड एक OUT_DIR पर्यावरण चर सेट करता है जिसमें build.rs स्क्रिप्ट से जेनरेट किए गए स्रोत कोड को रखने की उम्मीद की जाती है। स्रोत कोड शामिल करने के लिए निम्नलिखित कमांड का उपयोग करें:

include!(concat!(env!("OUT_DIR"), "/hello.rs"));

यह सूंग के लिए एक चुनौती प्रस्तुत करता है क्योंकि प्रत्येक मॉड्यूल के आउटपुट को उनकी अपनी out/ डायरेक्टरी ¹ में रखा जाता है। ऐसा एक भी OUT_DIR नहीं है जहां निर्भरताएँ अपने उत्पन्न स्रोत को आउटपुट करती हैं।

प्लेटफ़ॉर्म कोड के लिए, AOSP कई कारणों से उत्पन्न स्रोत को एक टोकरे में पैक करना पसंद करता है जिसे आयात किया जा सकता है:

• उत्पन्न स्रोत फ़ाइल नामों को टकराने से रोकें।
• पूरे ट्री में चेक-इन किए गए बॉयलरप्लेट कोड को कम करें जिसके रखरखाव की आवश्यकता है। जेनरेट किए गए स्रोत को एक क्रेट में संकलित करने के लिए आवश्यक किसी भी बॉयलरप्लेट को केंद्रीय रूप से बनाए रखा जा सकता है।
• जेनरेट किए गए कोड और आसपास के क्रेट के बीच अंतर्निहित ² इंटरैक्शन से बचें।
• आमतौर पर उपयोग किए जाने वाले जेनरेटेड स्रोतों को गतिशील रूप से लिंक करके मेमोरी और डिस्क पर दबाव कम करें।

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