ماژول های اندروید Rust

به عنوان یک اصل کلی، تعاریف ماژول rust_* به طور دقیق به کاربرد و انتظارات cc_* پایبند هستند. در زیر مثالی از تعریف ماژول برای فایل باینری Rust آمده است:

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

این صفحه رایج‌ترین ویژگی‌های ماژول‌های rust_* را پوشش می‌دهد. برای اطلاعات بیشتر در مورد انواع ماژول‌های خاص و تعاریف نمونه ماژول، به ماژول‌های دودویی (Binary modules) ، ماژول‌های کتابخانه‌ای (Library modules ) یا ماژول‌های آزمایشی (Test modules) مراجعه کنید.

انواع ماژول‌های پایه

خواص مشترک مهم

این ویژگی‌ها در بین تمام ماژول‌های Rust اندروید مشترک هستند. هرگونه ویژگی اضافی (منحصر به فرد) مرتبط با ماژول‌های Rust در صفحه مربوط به آن ماژول فهرست شده است.

نام

name نام ماژول شماست. مانند سایر ماژول‌های Soong، این نام باید در بین اکثر انواع ماژول Android.bp منحصر به فرد باشد. به طور پیش‌فرض، name به عنوان نام فایل خروجی استفاده می‌شود. اگر نام فایل خروجی باید با نام ماژول متفاوت باشد، از ویژگی stem برای تعریف آن استفاده کنید.

ساقه

stem (اختیاری) کنترل مستقیم بر نام فایل خروجی (به استثنای پسوند فایل و سایر پسوندها) را فراهم می‌کند. برای مثال، یک کتابخانه rust_library_rlib با مقدار stem برابر با libfoo یک فایل libfoo.rlib تولید می‌کند. اگر مقداری برای ویژگی stem ارائه ندهید، نام فایل خروجی به طور پیش‌فرض نام ماژول را اتخاذ می‌کند.

وقتی نمی‌توانید نام ماژول را روی نام فایل خروجی دلخواه تنظیم کنید، از تابع stem استفاده کنید. برای مثال، rust_library برای جعبه‌ی log ، liblog_rust نامگذاری شده است، زیرا یک liblog cc_library از قبل وجود دارد. استفاده از ویژگی stem در این حالت تضمین می‌کند که فایل خروجی به جای liblog.* ، liblog_rust.* نامگذاری شود.

src ها

srcs شامل یک فایل منبع واحد است که نقطه ورود به ماژول شما را نشان می‌دهد (معمولاً main.rs یا lib.rs ). rustc وظیفه تجزیه و تحلیل و کشف سایر فایل‌های منبع مورد نیاز برای کامپایل را بر عهده دارد و این فایل‌ها در فایل deps که تولید می‌شود، فهرست شده‌اند.

در صورت امکان، از این کاربرد برای کد پلتفرم خودداری کنید؛ برای اطلاعات بیشتر به Source Generators مراجعه کنید.

نام جعبه

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 ) الزامی است. این ماژول‌ها الزامات rustc را در رابطه بین crate_name و نام فایل خروجی اعمال می‌کنند. برای اطلاعات بیشتر، به بخش ماژول‌های کتابخانه مراجعه کنید.

پرزها

linter مربوط به rustc به طور پیش‌فرض برای همه انواع ماژول به جز مولدهای منبع اجرا می‌شود. برخی از مجموعه‌های lint تعریف شده و برای اعتبارسنجی منبع ماژول استفاده می‌شوند. مقادیر ممکن برای چنین مجموعه‌های lint به شرح زیر است:

• بسته به موقعیت ماژول، مجموعه پیش‌فرض lintها را default .
• android دقیق‌ترین مجموعه خط تیره که برای تمام کدهای پلتفرم اندروید اعمال می‌شود
• vendor مجموعه‌ای از خطوط ساده که روی کد فروشنده اعمال می‌شود
• none برای نادیده گرفتن همه هشدارها و خطاهای lint

clippy_lints

خط‌کش clippy همچنین به طور پیش‌فرض برای همه انواع ماژول به جز مولدهای منبع اجرا می‌شود. چند مجموعه خط‌کش تعریف شده است که برای اعتبارسنجی منبع ماژول استفاده می‌شوند. اینها برخی از مقادیر ممکن هستند:

• مجموعه default lintها بسته به موقعیت ماژول
• android دقیق‌ترین مجموعه خط تیره که برای تمام کدهای پلتفرم اندروید اعمال می‌شود
• vendor مجموعه‌ای از خطوط ساده که روی کد فروشنده اعمال می‌شود
• none برای نادیده گرفتن همه هشدارها و خطاهای lint

نسخه

edition نسخه Rust مورد استفاده برای کامپایل این کد را تعریف می‌کند. این مشابه نسخه‌های std برای C و C++ است. مقادیر معتبر 2015 ، 2018 و 2021 (پیش‌فرض) هستند.

پرچم‌ها

flags شامل لیستی از رشته‌های flag است که باید در حین کامپایل به rustc منتقل شود.

پرچم‌های ld

ld-flags شامل یک لیست رشته‌ای از پرچم‌ها است که باید هنگام کامپایل سورس به لینکر ارسال شود. این پرچم‌ها توسط پرچم -C linker-args rustc ارسال می‌شوند. clang به عنوان رابط لینکر استفاده می‌شود و lld برای لینک کردن واقعی فراخوانی می‌کند.

ویژگی‌ها

features یک لیست رشته‌ای از ویژگی‌هایی است که باید در طول کامپایل فعال شوند. این توسط --cfg 'feature="foo"' به rustc ارسال می‌شود. اکثر ویژگی‌ها افزودنی هستند، بنابراین در بسیاری از موارد این شامل مجموعه کامل ویژگی‌های مورد نیاز همه ماژول‌های وابسته است. با این حال، در مواردی که ویژگی‌ها منحصر به یکدیگر هستند، ماژول‌های اضافی را در هر فایل ساختی که ویژگی‌های متناقضی ارائه می‌دهد، تعریف کنید.

سی‌اف‌جی‌ها

cfgs شامل یک لیست رشته‌ای از پرچم‌های cfg است که باید در طول کامپایل فعال شوند. این توسط --cfg foo و --cfg "fizz=buzz" به rustc منتقل می‌شود.

سیستم ساخت به طور خودکار پرچم‌های cfg خاصی را در موقعیت‌های خاص، که در زیر ذکر شده است، تنظیم می‌کند:

• ماژول‌هایی که به صورت dylib ساخته می‌شوند، مجموعه cfg android_dylib را خواهند داشت.

• ماژول‌هایی که از VNDK استفاده می‌کنند، دارای مجموعه cfg مربوط به android_vndk خواهند بود. این مشابه تعریف __ANDROID_VNDK__ برای C++ است.

نوار

strip کنترل می‌کند که آیا فایل خروجی حذف شود و چگونه (در صورت وجود) حذف شود. اگر این گزینه تنظیم نشده باشد، ماژول‌های دستگاه به طور پیش‌فرض همه چیز را به جز mini debuginfo حذف می‌کنند. ماژول‌های میزبان، به طور پیش‌فرض، هیچ نمادی را حذف نمی‌کنند. مقادیر معتبر شامل none برای غیرفعال کردن حذف و all برای حذف همه چیز، از جمله mini debuginfo، هستند. مقادیر اضافی را می‌توانید در Soong Modules Reference بیابید.

میزبان_پشتیبانی‌شده

برای ماژول‌های دستگاه، پارامتر host_supported نشان می‌دهد که آیا ماژول باید یک نوع میزبان نیز ارائه دهد یا خیر.

تعریف وابستگی‌های کتابخانه‌ای

ماژول‌های Rust می‌توانند از طریق ویژگی‌های زیر به کتابخانه‌های CC و Rust وابسته باشند:

هنگام پیوند دادن کتابخانه‌های Rust ، به عنوان بهترین روش، این کار را با استفاده از ویژگی rustlibs به جای rlibs یا dylibs انجام دهید، مگر اینکه دلیل خاصی برای انجام این کار داشته باشید. این به سیستم ساخت اجازه می‌دهد تا پیوند صحیح را بر اساس آنچه ماژول ریشه نیاز دارد انتخاب کند و احتمال اینکه یک درخت وابستگی شامل هر دو نسخه rlib و dylib یک کتابخانه باشد را کاهش می‌دهد (که باعث عدم موفقیت در کامپایل می‌شود).

ویژگی‌های ساخت پشتیبانی نشده و محدود

Rust ِ سونگ پشتیبانی محدودی از تصاویر و اسنپ‌شات‌های vendor و vendor_ramdisk ارائه می‌دهد. با این حال، staticlibs ، cdylibs ، rlibs و binaries پشتیبانی می‌شوند. برای اهداف ساخت تصویر vendor، ویژگی android_vndk cfg تنظیم شده است. در صورت وجود تفاوت بین اهداف سیستم و vendor، می‌توانید از این در کد استفاده کنید. rust_proc_macros به عنوان بخشی از اسنپ‌شات‌های vendor ثبت نمی‌شوند. اگر به این موارد وابسته هستید، مطمئن شوید که آنها را به طور مناسب کنترل نسخه می‌کنید.

تصاویر محصول، VNDK و بازیابی پشتیبانی نمی‌شوند.

ساخت‌های افزایشی

توسعه‌دهندگان می‌توانند با تنظیم متغیر محیطی SOONG_RUSTC_INCREMENTAL روی true کامپایل افزایشی سورس Rust را فعال کنند.

هشدار : تضمینی وجود ندارد که فایل‌های باینری تولید شده با فایل‌های تولید شده توسط buildbots یکسان باشند. آدرس توابع یا داده‌های موجود در فایل‌های شیء ممکن است متفاوت باشند. برای اطمینان از اینکه مصنوعات تولید شده ۱۰۰٪ با مصنوعات ساخته شده توسط زیرساخت EngProd یکسان هستند، این مقدار را بدون تنظیم رها کنید.