מודולים של Android Rust

באופן כללי, ההגדרות של מודול rust_* פועלות בהתאם שימוש של cc_* וציפיות. הדוגמה הבאה היא למודול להגדרה הבינארית של חלודה:

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

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

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

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

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

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

שם

name הוא שם המודול. כמו מודולים אחרים של Soundg, הם חייבים להיות ייחודיים ברוב 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 מכיל קובץ מקור יחיד שמייצג את נקודת הכניסה אל (בדרך כלל main.rs או lib.rs). rustc מטפל בפתרון את כל קובצי המקור האחרים שנדרשים להידור, שנספר בקובץ deps שהופק.

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

שם_crate_name

crate_name קובע את המטא-נתונים של שם הארגז באמצעות --crate_name rustc לסמן. במודולים שיוצרים ספריות, הערך חייב להיות תואם לערך שם של ארגז שימוש במקור. לדוגמה, אם יש הפניה למודול 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 קבוצת השגיאות המחמירה ביותר שחלה על כל הקוד של פלטפורמת Android
  • vendor קבוצה רגועה של שגיאות בקוד שהוחלו על קוד הספק
  • none כדי להתעלם מכל האזהרות והשגיאות של איתור שגיאות בקוד

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

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

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

מהדורה

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

דגלים

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

ld_flags

ld-flags מכיל רשימת מחרוזות של דגלים שצריך להעביר ל-linker במהלך הידור. מקור. הם מועברים באמצעות דגל החלודה -C linker-args. 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 קובע אם קובץ הפלט יוסר ובאיזה אופן (אם רלוונטי). אם המדיניות הזו לא מוגדרת, המודולים של המכשיר מסירים כברירת מחדל את כל הנתונים חוץ ממידע מיני על תוצאות ניפוי הבאגים. כברירת מחדל, המודולים של המארח לא מסירים סמלים. הערכים החוקיים כוללים: none כדי להשבית את הפשטה ו-all כדי להסיר הכל, כולל המידע המיני של ניפוי הבאגים. אפשר למצוא ערכים נוספים בקטע חומר עזר בנושא מודולים של Soong.

Host_supported

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

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

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

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

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

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

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

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

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

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