ماژول های اندروید 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	صفحه ماژول های باینری
rust_library	یک کتابخانه Rust تولید می کند و انواع rlib و dylib را ارائه می دهد.	rust_library ، صفحه ماژول های کتابخانه.
rust_ffi	یک کتابخانه Rust C قابل استفاده توسط ماژول‌های cc تولید می‌کند و انواع ثابت و مشترک را ارائه می‌کند.	rust_ffi ، صفحه ماژول های کتابخانه
rust_proc_macro	یک کتابخانه proc-macro Rust تولید می کند. (اینها مشابه افزونه های کامپایلر هستند.)	rust_proc_macro ، صفحه ماژول های کتابخانه ها
rust_test	یک باینری تست Rust تولید می کند که از مهار استاندارد Rust test استفاده می کند.	صفحه ماژول های تست
rust_fuzz	یک libfuzzer باینری Rust fuzz تولید می کند.	نمونه ماژول rust_fuzz
rust_protobuf	منبع تولید می کند و یک کتابخانه Rust تولید می کند که یک رابط برای یک پروتوباف خاص فراهم می کند.	صفحات Protobufs Modules و Source Generators
rust_bindgen	منبع تولید می کند و یک کتابخانه Rust حاوی پیوندهای Rust به کتابخانه های C تولید می کند.	صفحات Bindgen Bindings Modules و Source Generators

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

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

نام

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

ساقه

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

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

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

پرزها

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

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

clippy_lints

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

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

نسخه

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

پرچم ها

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 خواهند بود.

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

نوار

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

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 ، به عنوان بهترین روش، این کار را با استفاده از ویژگی rustlibs به جای rlibs یا dylibs انجام دهید، مگر اینکه دلیل خاصی برای این کار داشته باشید. این به سیستم ساخت اجازه می دهد تا پیوند صحیح را بر اساس آنچه ماژول ریشه نیاز دارد انتخاب کند، و این احتمال را کاهش می دهد که درخت وابستگی شامل هر دو نسخه rlib و dylib یک کتابخانه باشد (که باعث شکست کامپایل می شود).

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

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

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

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

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

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