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

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

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

این صفحه رایج ترین ویژگی های ماژول های rust_* را پوشش می دهد. برای اطلاعات بیشتر در مورد انواع ماژول های خاص و تعاریف نمونه ماژول، ماژول های باینری ، ماژول های کتابخانه ، یا ماژول های تست را ببینید.

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

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

این ویژگی ها در همه ماژول های 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 و 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 خواهند بود.

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

نوار

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

host_supported

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

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

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

هنگام پیوند در برابر کتابخانه های 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 یکسان هستند، این مقدار را تنظیم نشده بگذارید.