מודולים של Rust ל-Android

באופן כללי, הגדרות המודול של rust_* תואמות מאוד לשימוש ולציפיות של cc_*. זו דוגמה להגדרת מודול לקובץ בינארי של Rust:

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

בדף הזה מפורטים המאפיינים הנפוצים ביותר של מודולים של rust_*. למידע נוסף על סוגי מודולים ספציפיים ועל הגדרות לדוגמה של מודולים, ראו מודולים בינאריים, מודולים של ספריות או מודולים לבדיקה.

סוגי מודולים בסיסיים

סוגהגדרהלמידע נוסף
rust_binaryקובץ בינארי של Rust הדף Binary Modules
rust_libraryיוצרת ספריית Rust ומספקת וריאנטים של rlib ושל dylib. rust_library, בדף Library Modules (מודולים בספרייה).
rust_ffiהכלי יוצר ספריית C ב-Rust שמודולים של cc יכולים להשתמש בה, ומספק וריאנטים סטטיים ומשותפים. rust_ffi, דף המודולים בספרייה
rust_proc_macroיצירת ספריית proc-macro Rust. (הם דומים לפלאגינים של מהדרים). rust_proc_macro, דף המודולים של הספריות
rust_testיוצר קובץ בינארי לבדיקה של Rust שמשתמש במערך הבדיקה הסטנדרטי של Rust. הדף Test Modules (מודולים לבדיקה)
rust_fuzzיצירת קובץ בינארי של fuzz ב-Rust שמשתמש ב-libfuzzer. דוגמה למודול rust_fuzz
rust_protobufהכלי יוצר מקור וספריית Rust שמספקת ממשק ל-protobuf מסוים. הדפים Protobufs Modules ו-Source Generators
rust_bindgenהכלי יוצר מקור ויוצר ספריית Rust שמכילה קישורי Rust לספריות C. הדפים מודולים של קישורים ל-Bindgen וגנרטורים של מקורות קוד

מאפיינים נפוצים וחשובים

המאפיינים האלה משותפים לכל המודולים של Rust ל-Android. נכסים נוספים (ייחודיים) שמשויכים למודולים נפרדים של Rust מפורטים בדף של אותו מודול.

שם

name הוא השם של המודול. כמו מודולים אחרים של Soong, השם הזה צריך להיות ייחודי ברוב סוגי המודולים של Android.bp. כברירת מחדל, השם name משמש בתור שם הקובץ של הפלט. אם שם הקובץ של הפלט צריך להיות שונה משם המודול, צריך להשתמש במאפיין stem כדי להגדיר אותו.

גבעול

stem (אופציונלי) מאפשר שליטה ישירה על שם הקובץ של הפלט (לא כולל סיומת הקובץ וסיומת אחרות). לדוגמה, ספריית rust_library_rlib עם ערך גזע של libfoo יוצרת קובץ libfoo.rlib. אם לא תספקו ערך למאפיין stem, שם הקובץ של הפלט יהיה שם המודול כברירת מחדל.

משתמשים בפונקציה stem כשאי אפשר להגדיר את שם המודול בתור שם הקובץ הרצוי של הפלט. לדוגמה, ה-rust_library של תיבת ה-crate log נקרא liblog_rust, כי כבר קיים liblog cc_library. במקרה כזה, השימוש במאפיין stem מבטיח שהשם של קובץ הפלט יהיה liblog.* במקום liblog_rust.*.

srcs

srcs מכיל קובץ מקור יחיד שמייצג את נקודת הכניסה למודול (בדרך כלל main.rs או lib.rs). rustc מטפל בהתאמת נתונים (resolve) ובגילוי של כל קובצי המקור האחרים הנדרשים לצורך הידור, והם מפורטים בקובץ deps שנוצר.

כשהדבר אפשרי, כדאי להימנע משימוש כזה בקוד הפלטפורמה. מידע נוסף זמין במאמר מחוללי מקורות.

crate_name

crate_name מגדיר את המטא-נתונים של שם ה-crate באמצעות הדגל rustc --crate_name. במודולים שמפיקים ספריות, השם הזה חייב להתאים לשם הצפוי של ה-crate שמשמש במקור. לדוגמה, אם המודול 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 פועל בכל סוגי המודולים, מלבד גנרטורים של מקורות. חלק מקבוצות ה-lint מוגדרות ומשמשות לאימות המקור של המודול. הערכים האפשריים של קבוצות איתור שגיאות כאלה הם:

  • default קבוצת ברירת המחדל של בדיקות איתור שגיאות בקוד, בהתאם למיקום המודול
  • android קבוצת ה-lint המחמירה ביותר שחלה על כל הקוד בפלטפורמת Android
  • vendor קבוצה פחות מחמירה של בדיקות איתור שגיאות בקוד (lint) שחלות על קוד של ספקים
  • none כדי להתעלם מכל האזהרות והשגיאות של איתור שגיאות בקוד

clippy_lints

כלי האיתור של שגיאות בקוד (linter) של Clippy פועל גם כברירת מחדל לכל סוגי המודולים, מלבד לגנרטורים של מקורות קוד. מוגדרות כמה קבוצות של בדיקות איתור שגיאות בקוד (lints) שמשמשות לאימות מקור המודול. אלה כמה ערכים אפשריים:

  • default קבוצת ברירת המחדל של בדיקות איתור שגיאות בקוד, בהתאם למיקום המודול
  • android קבוצת ה-lint המחמירה ביותר שחלה על כל הקוד בפלטפורמת Android
  • vendor קבוצה פחות מחמירה של בדיקות איתור שגיאות בקוד (lint) שחלות על קוד של ספקים
  • 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. רוב התכונות הן מצטברות, ולכן במקרים רבים היא מורכבת מקבוצת התכונות המלאה שנדרשת לכל המודולים התלויים. עם זאת, במקרים שבהם תכונות הן בלעדיות זו לזו, צריך להגדיר מודולים נוספים בכל קובץ build שמספק תכונות סותרות.

cfgs

cfgs מכילה רשימת מחרוזות של דגלים של cfg שצריך להפעיל במהלך הידור. הערך הזה מועבר אל rustc על ידי --cfg foo ו---cfg "fizz=buzz".

מערכת ה-build מגדירה באופן אוטומטי דגלים מסוימים של cfg במצבים מסוימים, שמפורטים בהמשך:

  • במודולים שנוצרו כ-dylib, ההגדרה cfg תהיה android_dylib.

  • במודולים שישתמשו ב-VNDK תהיה הגדרת cfg של android_vndk. ההגדרה הזו דומה להגדרה של __ANDROID_VNDK__ ב-C++‎.

רצועה

strip קובע אם קובץ הפלט יוסר (אם רלוונטי) ואיך הוא יוסר. אם לא מגדירים את הערך הזה, ברירת המחדל של מודולי המכשיר היא להסיר הכול מלבד mini debuginfo. כברירת מחדל, מודולים מארחים לא מסירים סמלים. הערכים התקפים הם none כדי להשבית את הסרת הקוד, ו-all כדי להסיר את הכול, כולל את mini debuginfo. ערכים נוספים מופיעים בחומר העזר בנושא מודולים של Soong.

host_supported

במודולים של מכשירים, הפרמטר host_supported מציין אם המודולים צריכים לספק גם וריאנט מארח.

הגדרת יחסי תלות בספרייה

מודולים של Rust יכולים להסתמך גם על ספריות CC וגם על ספריות Rust באמצעות המאפיינים הבאים:

שם הנכס תיאור
rustlibs רשימה של מודולים של rust_library שגם הם תלויים במודול. מומלץ להשתמש באפשרות הזו כדי להצהיר על יחסי תלות, כי היא מאפשרת למערכת ה-build לבחור את הקישור המועדף. (ראו כשמקשרים לספריות 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, אלא אם יש לכם סיבה ספציפית לעשות זאת. כך מערכת ה-build יכולה לבחור את הקישור הנכון על סמך הצורך של מודול הבסיס, וגם לצמצם את הסיכוי שציר התלות יכיל גם את הגרסה rlib וגם את הגרסה dylib של הספרייה (מצב שגורם לכשל בתהליך ה-compilation).

תכונות build שלא נתמכות ותכונות build עם תמיכה מוגבלת

ב-Rust של Soong יש תמיכה מוגבלת בתמונות ובקובצי snapshot של vendor ו-vendor_ramdisk. עם זאת, יש תמיכה ב-staticlibs, ב-cdylibs, ב-rlibs וב-binaries. ליעדים של build של קובצי אימג' של ספקים, מוגדר המאפיין android_vndk cfg. אפשר להשתמש בקוד הזה אם יש הבדלים בין היעדים של המערכת לבין היעדים של הספק. rust_proc_macros לא מתועדים כחלק מתמונות מצב של ספקים. אם יש לכם תלות בקבצים האלה, חשוב לוודא שאתם מבצעים בקרת גרסאות עליהם בצורה מתאימה.

אין תמיכה בתמונות של מוצרים, ב-VNDK ובתמונות שחזור.

גרסאות build מצטברות

מפתחים יכולים להפעיל את הידור המקור המצטבר של Rust על ידי הגדרת משתנה הסביבה SOONG_RUSTC_INCREMENTAL לערך true.

אזהרה: לא מובטח שהפעולה הזו תיצור קובצי בינארי זהים לאלה שנוצרו על ידי buildbots. יכול להיות שהכתובות של פונקציות או נתונים שמכילים קובצי האובייקטים יהיו שונות. כדי לוודא שהארטיפקטים שנוצרים זהים לחלוטין לאלה שנוצרו על ידי התשתית של EngProd, משאירים את הערך הזה ללא הגדרה.