מודולים של Android 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 הדף Binary Modules (מודולים בינאריים)
rust_libraryיוצרת ספריית Rust ומספקת וריאנטים של rlib ושל dylib. rust_library, הדף 'מודולים של ספרייה'.
rust_ffiיוצרת ספריית Rust שאפשר להשתמש בה באמצעות מודולים של cc, וכוללת גם וריאנטים סטטיים וגם וריאנטים משותפים. rust_ffi, הדף 'מודולים של ספריות'
rust_proc_macroיוצרת ספריית Rust של proc-macro. (הפלאגינים האלה דומים לפלאגינים של מהדרים). rust_proc_macro, הדף Libraries Modules (מודולים של ספריות)
rust_testיוצרת קובץ בינארי של בדיקת חלודה שמשתמש ברצועת הבדיקה הרגילה של Rust. הדף מודולים לבדיקה
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 מכיל קובץ מקור אחד שמייצג את נקודת הכניסה למודול (בדרך כלל main.rs או lib.rs). rustc מטפל בהתאמת נתונים (resolve) ובזיהוי של כל קובצי המקור האחרים הנדרשים לצורך הידור, והם מפורטים בקובץ 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 לשם קובץ הפלט. מידע נוסף זמין בקטע מודולים של ספריות.

שגיאות בקוד

איתור השגיאות בקוד מופעל כברירת מחדל לכל סוגי המודולים, מלבד מחוללי מקור. חלק מקבוצות השגיאות בקוד מוגדרות ומשמשות לאימות מקור המודול. הערכים האפשריים של קבוצות איתור שגיאות כאלה הם:

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

שגיאות קליפים

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

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

מהדורה

השדה edition מגדיר את מהדורת Rust שבה צריך להשתמש להרכבת הקוד. גרסה זו דומה לגרסאות std של C ו-C++. הערכים החוקיים הם 2015 ו-2018 (ברירת המחדל).

דגלים

flags מכילה רשימת מחרוזות של דגלים שצריך להעביר ל-rustc במהלך הידור.

ld_flags

ld-flags מכיל רשימת מחרוזות של דגלים שצריך להעביר למקשר בזמן הידור המקור. הם מועברים על ידי הדגל -C linker-args של rustc. clang משמש כממשק הקצה של המקשר, ומפעיל את lld לקישור עצמו.

תכונות

features היא רשימת מחרוזות של תכונות שצריך להפעיל במהלך הידור. הערך מועבר לחלודה על ידי --cfg 'feature="foo"'. רוב התכונות הן מצטברות, ולכן במקרים רבים הקבוצה הזו מורכבת מקבוצת התכונות המלאה שנדרשת לכל המודולים התלויים. עם זאת, במקרים שבהם תכונות הן בלעדיות זו לזו, צריך להגדיר מודולים נוספים בכל קובץ build שמספק תכונות סותרות.

cfgs

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

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

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

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

רצועה

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

host_supported

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

מגדירים יחסי תלות של ספריות

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

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

כשמקשרים לספריות חלודה, השיטה המומלצת היא להשתמש בנכס rustlibs במקום ב-rlibs או ב-dylibs, אלא אם יש לכם סיבה ספציפית לעשות זאת. כך מערכת ה-build יכולה לבחור את הקישור הנכון על סמך הדרישות של מודול השורש, וזה יפחית את הסיכוי שעץ תלות יכיל את הגרסה rlib ו-dylib של הספרייה (מה שיגרום להיכשל ההידור).

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

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

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

פיתוחים מצטברים

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

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