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

קל לארגן דפים בעזרת אוספים אפשר לשמור ולסווג תוכן על סמך ההעדפות שלך.

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

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

בדף הזה מפורטים המאפיינים הנפוצים ביותר של מודולים של 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. במודולים שמפיקים ספריות, השם הזה חייב להתאים לשם הצ'רטה הצפוי שמשמש במקור. לדוגמה, אם יש הפניה למודול libfoo_bar במקור כ-extern crate foo_bar, אז חייב להיות crate_name: "foo_bar".

המאפיין הזה משותף לכל המודולים של rust_*, אבל הוא נדרש למודולים שמפיקים ספריות של Rust (כמו rust_libraryrust_ffi,‏ rust_bindgen,‏ rust_protobuf ו-rust_proc_macro). המודולים האלה אוכפים את הדרישות של rustc על הקשר בין crate_name לשם הקובץ של הפלט. מידע נוסף זמין במאמר מודולים של ספרייה .

שגיאות בקוד

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

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

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

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

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

מהדורה

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

דגלים

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

ld_flags

ld-flags מכיל רשימת מחרוזות של דגלים שצריך להעביר למקשר בזמן הידור המקור. הם מועברים באמצעות דגל החלודה -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 כדי להסיר את הכול, כולל את mini debuginfo. ערכים נוספים מופיעים בחומר העזר בנושא מודולים של Soong.

Host_supported

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

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

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

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

תכונות 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. הכתובות של הפונקציות או הנתונים שכלולים קובצי האובייקט עשויים להיות שונים. כדי לוודא שכל פריטי המידע שנוצרו בתהליך הפיתוח (Artifact) שנוצרו עומדים על 100% זהה לגרסאות שפותחו על ידי התשתית EngProd, צריך להשאיר את הערך הזה לא מוגדר.