Android के लिए रस्ट मॉड्यूल

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

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

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

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

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

सामान्य तौर पर इस्तेमाल होने वाली ज़रूरी प्रॉपर्टी

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

नाम

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

स्टेम

stem (ज़रूरी नहीं) की मदद से, आउटपुट फ़ाइल के नाम को सीधे तौर पर कंट्रोल किया जा सकता है. हालांकि, इसमें फ़ाइल एक्सटेंशन और अन्य सफ़िक्स शामिल नहीं हैं. उदाहरण के लिए, libfoo की स्टेम वैल्यू वाली rust_library_rlib library से 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 लाइब्रेरी (जैसे, rust_library rust_ffi, rust_bindgen, rust_protobuf, और rust_proc_macro) बनाने वाले मॉड्यूल के लिए यह ज़रूरी है. ये मॉड्यूल, crate_name और आउटपुट फ़ाइल के नाम के बीच के संबंध पर rustc की ज़रूरी शर्तों को लागू करते हैं. ज़्यादा जानकारी के लिए, लाइब्रेरी मॉड्यूल सेक्शन देखें.

lints

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

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

clippy_lints

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

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

वर्शन

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

फ़्लैग

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

ld_flags

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

सुविधाएं

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

cfgs

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 पैरामीटर से पता चलता है कि मॉड्यूल को होस्ट वैरिएंट भी देना चाहिए या नहीं.

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

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

प्रॉपर्टी का नाम ब्यौरा
rustlibs rust_library मॉड्यूल की सूची, जो डिपेंडेंसी भी हैं. डिपेंडेंसी का एलान करने के लिए, इस तरीके का इस्तेमाल करें. इससे, बिल्ड सिस्टम को अपनी पसंद का लिंक चुनने में मदद मिलती है. (Rust लाइब्रेरी के साथ लिंक करते समय, नीचे देखें)
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, दोनों वर्शन शामिल हों. ऐसा होने पर, कॉम्पाइलेशन पूरा नहीं हो पाएगा.

ऐसी सुविधाएं जो काम नहीं करतीं और जिनके लिए सीमित सहायता मिलती है

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

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

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

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

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