Android Rust मॉड्यूल

सामान्य सिद्धांत के तौर पर, rust_* मॉड्यूल की परिभाषाएं cc_* के इस्तेमाल और उससे जुड़ी उम्मीदों का पालन करती हैं. यहां Rust बाइनरी के लिए, मॉड्यूल की परिभाषा का एक उदाहरण दिया गया है:

rust_binary {
    name: "hello_rust",
    crate_name: "hello_rust",
    srcs: ["src/hello_rust.rs"],
    host_supported: true,
}

इस पेज पर rust_* मॉड्यूल की सबसे सामान्य प्रॉपर्टी के बारे में बताया गया है. अलग-अलग तरह के मॉड्यूल और मॉड्यूल की परिभाषाओं के उदाहरण के बारे में ज़्यादा जानने के लिए, बाइनरी मॉड्यूल, लाइब्रेरी मॉड्यूल या टेस्ट मॉड्यूल देखें.

बुनियादी मॉड्यूल टाइप

टाइपपरिभाषाअधिक जानकारी के लिए
rust_binaryरस्ट बाइनरी बाइनरी मॉड्यूल पेज
rust_libraryइससे रस्ट लाइब्रेरी बनती है. साथ ही, इसमें rlib और dylib, दोनों वैरिएंट उपलब्ध होते हैं. rust_library, लाइब्रेरी मॉड्यूल पेज.
rust_ffiयह Rust C लाइब्रेरी बनाता है, जिसका इस्तेमाल cc मॉड्यूल कर सकते हैं. साथ ही, यह स्टैटिक और शेयर किए गए, दोनों वैरिएंट उपलब्ध कराता है. rust_ffi, लाइब्रेरी मॉड्यूल पेज
rust_proc_macroयह proc-macro रस्ट लाइब्रेरी बनाता है. (ये कंपाइलर प्लग इन की तरह ही होते हैं.) rust_proc_macro, लाइब्रेरी मॉड्यूल पेज
rust_testयह Rust टेस्ट बाइनरी बनाता है, जो स्टैंडर्ड Rust टेस्ट हार्नेस का इस्तेमाल करता है. मॉड्यूल की जांच करें पेज
rust_fuzzlibfuzzer का इस्तेमाल करके, रस्ट फ़ज़ बाइनरी बनाता है. rust_fuzz मॉड्यूल का उदाहरण
rust_protobufसोर्स जनरेट करता है और एक रस्ट लाइब्रेरी बनाता है, जो किसी खास प्रोटोबफ़ के लिए इंटरफ़ेस उपलब्ध कराती है. प्रोटोबफ़्स मॉड्यूल और सोर्स जनरेटर पेज
rust_bindgenसोर्स जनरेट करता है और एक ऐसी Rust लाइब्रेरी बनाता है जिसमें C लाइब्रेरी के लिए Rust बाइंडिंग होती हैं. Bindgen Bings मॉड्यूल और सोर्स जनरेटर पेज

अहम सामान्य प्रॉपर्टी

ये प्रॉपर्टी, Android Rust मॉड्यूल में आम तौर पर इस्तेमाल की जाती हैं. अलग-अलग Rust मॉड्यूल से जुड़ी अन्य (यूनीक) प्रॉपर्टी, उस मॉड्यूल के पेज पर दी गई होती हैं.

नाम

name आपके मॉड्यूल का नाम है. अन्य सूंग मॉड्यूल की तरह, यह ज़्यादातर Android.bp मॉड्यूल टाइप में यूनीक होना चाहिए. डिफ़ॉल्ट रूप से, name का इस्तेमाल आउटपुट फ़ाइल के नाम के तौर पर किया जाता है. अगर आउटपुट फ़ाइल का नाम, मॉड्यूल के नाम से अलग होना चाहिए, तो इसकी जानकारी देने के लिए stem प्रॉपर्टी का इस्तेमाल करें.

स्टेम

stem (ज़रूरी नहीं) की मदद से, आउटपुट फ़ाइल के नाम को सीधे तौर पर कंट्रोल किया जा सकता है. हालांकि, इसमें फ़ाइल एक्सटेंशन और अन्य सफ़िक्स शामिल नहीं हैं. उदाहरण के लिए, libfoo की स्टेम वैल्यू वाली rust_library_rlib लाइब्रेरी libfoo.rlib फ़ाइल बनाती है. अगर आपने stem प्रॉपर्टी के लिए कोई वैल्यू नहीं दी है, तो आउटपुट फ़ाइल का नाम डिफ़ॉल्ट रूप से मॉड्यूल के नाम पर सेट हो जाता है.

जब मॉड्यूल के नाम को मनचाहे आउटपुट फ़ाइल नाम पर सेट नहीं हो पा रहा हो, तब stem फ़ंक्शन का इस्तेमाल करें. उदाहरण के लिए, log क्रेट के लिए rust_library का नाम liblog_rust रखा गया है, क्योंकि liblog cc_library पहले से मौजूद है. इस मामले में stem प्रॉपर्टी का इस्तेमाल करने से यह पक्का होता है कि आउटपुट फ़ाइल का नाम liblog_rust.* के बजाय liblog.* हो.

srcs

srcs में एक सोर्स फ़ाइल होती है, जो आपके मॉड्यूल के एंट्री पॉइंट (आम तौर पर main.rs या lib.rs) को दिखाती है. rustc, कंपाइलेशन के लिए ज़रूरी सभी अन्य सोर्स फ़ाइलों को रिज़ॉल्व और डिस्कवर करता है. इन फ़ाइलों को जनरेट की गई deps फ़ाइल में शामिल किया जाता है.

जब हो सके, प्लैटफ़ॉर्म कोड के लिए इसका इस्तेमाल न करें. ज़्यादा जानकारी के लिए, सोर्स जनरेटर देखें.

crate_name

crate_name, rustc --crate_name फ़्लैग की मदद से, क्रेट के नाम का मेटाडेटा सेट करता है. लाइब्रेरी बनाने वाले मॉड्यूल के लिए, यह नाम सोर्स में इस्तेमाल किए गए क्रेट के नाम से मैच करना चाहिए. उदाहरण के लिए, अगर सोर्स में libfoo_bar मॉड्यूल का रेफ़रंस extern crate foo_bar के तौर पर दिया गया है, तो यह Crate_name: "foo_bar" ज़रूरी है.

यह प्रॉपर्टी सभी rust_* मॉड्यूल के लिए सामान्य है, लेकिन यह ऐसे मॉड्यूल के लिए ज़रूरी है जो रस्ट लाइब्रेरी (जैसे कि rust_library rust_ffi, rust_bindgen, rust_protobuf, और rust_proc_macro) बनाते हैं. ये मॉड्यूल crate_name और आउटपुट फ़ाइल नाम के बीच के संबंध पर rustc की ज़रूरी शर्तें लागू करते हैं. ज़्यादा जानकारी के लिए, लाइब्रेरी मॉड्यूल सेक्शन देखें.

लिंट

rustc linter, सोर्स जनरेटर को छोड़कर सभी तरह के मॉड्यूल के लिए डिफ़ॉल्ट रूप से चलता है. कुछ लिंट सेट तय किए जाते हैं और उनका इस्तेमाल, मॉड्यूल सोर्स की पुष्टि करने के लिए किया जाता है. ऐसे लिंट सेट के लिए ये वैल्यू हो सकती हैं:

  • मॉड्यूल की जगह के आधार पर, लिंट का डिफ़ॉल्ट सेट default
  • android सबसे सख्त लिंट सेट है, जो सभी Android प्लैटफ़ॉर्म कोड पर लागू होता है
  • vendor वेंडर कोड पर लागू किए गए लिंट का आरामदेह सेट
  • none, सभी लिंट चेतावनियों और गड़बड़ियों को अनदेखा करने के लिए

clippy_lints

सोर्स जनरेटर के अलावा, सभी तरह के मॉड्यूल के लिए clippy linter भी डिफ़ॉल्ट रूप से चलता है. लिंट के कुछ सेट तय किए गए हैं, जिनका इस्तेमाल मॉड्यूल सोर्स की पुष्टि करने के लिए किया जाता है. ये कुछ संभावित मान हैं:

  • default मॉड्यूल की जगह के आधार पर, लिंट का डिफ़ॉल्ट सेट
  • android सबसे सख्त लिंट सेट, जो Android प्लैटफ़ॉर्म के सभी कोड पर लागू होता है
  • vendor वेंडर कोड पर लागू किए गए लिंट का आरामदेह सेट
  • लिंट से जुड़ी सभी चेतावनियों और गड़बड़ियों को अनदेखा करने के लिए, none

वर्शन

edition, इस कोड को संकलित करने के लिए इस्तेमाल किए जाने वाले Rust वर्शन के बारे में बताता है. यह C और C++ के लिए एसटीडी वर्शन की तरह है. मान्य वैल्यू 2015 और 2018 (डिफ़ॉल्ट) हैं.

फ़्लैग

flags में, कंपाइलेशन के दौरान rustc को पास किए जाने वाले फ़्लैग की स्ट्रिंग की सूची मौजूद होती है.

ld_flags

ld-flags में, सोर्स को कॉम्पाइल करते समय लिंकर को पास करने के लिए, फ़्लैग की स्ट्रिंग सूची होती है. इन्हें -C linker-args के रस्ट फ़्लैग से पास किया जाता है. clang का इस्तेमाल लिंकर के फ़्रंट-एंड के तौर पर किया जाता है. यह असल लिंकिंग के लिए lld को कॉल करता है.

को प्रीफ़िक्स करें.

सुविधाएं

features उन सुविधाओं की स्ट्रिंग सूची है जिन्हें कंपाइलेशन के दौरान चालू करना ज़रूरी है. इसे --cfg 'feature="foo"' के ज़रिए rustc को भेजा जाता है. ज़्यादातर सुविधाएं जोड़ी जाती हैं. इसलिए, कई मामलों में इसमें उन सभी मॉड्यूल के लिए ज़रूरी सभी सुविधाओं का सेट शामिल होता है जिन पर यह निर्भर करता है. हालांकि, अगर सुविधाएं एक-दूसरे से अलग हैं, तो ऐसी सभी बिल्ड फ़ाइलों में अतिरिक्त मॉड्यूल तय करें जिनमें अलग-अलग सुविधाएं मिलती हैं.

सीएफ़जीएस

cfgs में cfg फ़्लैग की स्ट्रिंग सूची होती है, जिसे कंपाइलेशन के दौरान चालू किया जाना होता है. इसे --cfg foo और --cfg "fizz=buzz", rustc को भेजते हैं.

बिल्ड सिस्टम, कुछ खास स्थितियों में अपने-आप कुछ cfg फ़्लैग सेट करता है. इन स्थितियों के बारे में यहां बताया गया है:

  • dylib के तौर पर बनाए गए मॉड्यूल में android_dylib cfg सेट होगा.

  • वीएनडीके का इस्तेमाल करने वाले मॉड्यूल में android_vndk cfg सेट होगा. यह C++ की __ANDROID_VNDK__ परिभाषा से मिलता-जुलता है.

स्ट्रिप

strip यह कंट्रोल करता है कि आउटपुट फ़ाइल को हटाया जाए या नहीं (अगर लागू हो). अगर इसे सेट नहीं किया जाता है, तो डिवाइस मॉड्यूल डिफ़ॉल्ट रूप से, मिनी डीबगइफ़ो के अलावा बाकी सभी चीज़ों को हटा देते हैं. डिफ़ॉल्ट रूप से, होस्ट मॉड्यूल किसी भी सिंबल को नहीं हटाते हैं. मान्य वैल्यू में ये शामिल हैं: स्ट्रिपिंग बंद करने के लिए, none और मिनी डीबगइंफ़ो सहित सब कुछ हटाने के लिए all. Soong मॉड्यूल के रेफ़रंस में, इस बारे में ज़्यादा जानकारी मिल सकती है.

host_supported

डिवाइस मॉड्यूल के लिए, host_supported पैरामीटर से पता चलता है कि मॉड्यूल को होस्ट के लिए वैरिएंट भी उपलब्ध कराना चाहिए या नहीं.

लाइब्रेरी डिपेंडेंसी तय करना

रस्ट मॉड्यूल, इन प्रॉपर्टी के ज़रिए CC और Rust लाइब्रेरी, दोनों पर निर्भर हो सकते हैं:

प्रॉपर्टी का नाम ब्यौरा
rustlibs rust_library मॉड्यूल की सूची, जो डिपेंडेंसी भी हैं. डिपेंडेंसी का एलान करने के लिए, इस तरीके का इस्तेमाल करें. इससे, बिल्ड सिस्टम को अपनी पसंद का लिंक चुनने में मदद मिलती है. (रस्ट लाइब्रेरी के ख़िलाफ़ लिंक करने पर, नीचे दी गई टेबल देखें)
rlibs ऐसे rust_library मॉड्यूल की सूची जिन्हें rlibs के तौर पर स्टैटिक रूप से लिंक किया जाना चाहिए. (इस्तेमाल करते समय सावधानी बरतें; नीचे Rust लाइब्रेरी के साथ लिंक करते समय देखें.)
shared_libs cc_library मॉड्यूल की सूची, जिन्हें शेयर की गई लाइब्रेरी के तौर पर डाइनैमिक तौर पर लिंक किया जाना चाहिए.
static_libs ऐसे cc_library मॉड्यूल की सूची जिन्हें स्टैटिक लाइब्रेरी के तौर पर लिंक किया जाना चाहिए.
whole_static_libs cc_library मॉड्यूल की सूची, जिन्हें स्टैटिक लाइब्रेरी के तौर पर स्टैटिक तौर पर लिंक किया जाना चाहिए और पूरी लाइब्रेरी में शामिल किया जाना चाहिए. rust_ffi_static वैरिएंट के लिए, whole_static_libraries को स्टैटिक लाइब्रेरी के संग्रह में शामिल किया जाएगा. rust_library_rlib वैरिएंट के लिए, whole_static_libraries लाइब्रेरी को rlib लाइब्रेरी में बंडल किया जाएगा.

Rust लाइब्रेरी के साथ लिंक करते समय, सबसे सही तरीका यह है कि rlibs या dylibs के बजाय rustlibs प्रॉपर्टी का इस्तेमाल करें. ऐसा तब तक करें, जब तक आपके पास ऐसा करने की कोई खास वजह न हो. इससे बिल्ड सिस्टम को रूट मॉड्यूल की ज़रूरत के आधार पर सही लिंकेज चुनने में मदद मिलती है. साथ ही, इस बात की संभावना कम हो जाती है कि डिपेंडेंसी ट्री में किसी लाइब्रेरी के rlib और dylib, दोनों वर्शन शामिल हों. ऐसा होने पर, कॉम्पाइलेशन पूरा नहीं हो पाएगा.

काम न करने वाली और सीमित सहायता के लिए बिल्ड सुविधाएं

सूंग के रस्ट पेज पर, vendor और vendor_ramdisk इमेज और स्नैपशॉट के लिए सीमित सहायता मिलती है. हालांकि, staticlibs, cdylibs, rlibs, और binaries का इस्तेमाल किया जा सकता है. वेंडर इमेज बिल्ड टारगेट के लिए, android_vndk cfg प्रॉपर्टी सेट की गई है. अगर सिस्टम और वेंडर टारगेट के बीच अंतर है, तो कोड में इसका इस्तेमाल किया जा सकता है. rust_proc_macros को वेंडर स्नैपशॉट के तौर पर कैप्चर नहीं किया जाता. अगर ये इस पर निर्भर हैं, तो पक्का करें कि आपने वर्शन को सही तरीके से कंट्रोल किया हो.

प्रॉडक्ट, VNDK, और रिकवरी इमेज का इस्तेमाल नहीं किया जा सकता.

इंक्रीमेंटल बिल्ड

डेवलपर, SOONG_RUSTC_INCREMENTAL एनवायरमेंट वैरिएबल को true पर सेट करके, Rust सोर्स के इंक्रीमेंटल कंपाइलेशन को चालू कर सकते हैं.

चेतावनी: इससे इस बात की कोई गारंटी नहीं है कि बिल्डबॉट से जनरेट की गई बाइनरी जैसी बाइनरी बनेगी. ऑब्जेक्ट फ़ाइलों में मौजूद फ़ंक्शन या डेटा के पते अलग-अलग हो सकते हैं. यह पक्का करने के लिए कि जनरेट किए गए आर्टफ़ैक्ट, EngProd इन्फ़्रास्ट्रक्चर के बनाए हुए आर्टफ़ैक्ट से 100% एक जैसे हों. इसके लिए, इस वैल्यू को सेट न करें.