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

יש שני סוגים של מודולים של ספריות Rust, אחד שמייצר ספריות Rust ואחד שמייצר ספריות שתואמות ל-C. בנוסף, למטרות של מערכת בנייה, אפשר להתייחס לפקודות מאקרו פרוצדורליות של Rust‏ (proc-macros) כאל סוג מיוחד של ספריות.

rust_library

מודול rust_library יוצר ספריות Rust לשימוש של מודולי Rust אחרים.

בנוסף לגרסאות של _host, לספריות Rust יש סוגי מודולים ששולטים בקישור הזמין.

Rust Library Module Type	הגדרה
rust_library	הספרייה מספקת את שני סוגי הווריאציות, rlib ו-dylib. ‫AOSP ממליצה על סוג המודול הזה לספריות Rust, כי הוא מאפשר למודולים לפעול בצורה תקינה כשהם מופיעים כמאפיין תלותי בקטע rustlibs
rust_library_rlib	מספק רק את הווריאציה rlib של ספריית Rust; אי אפשר להבטיח שמודולים שמספקים רק וריאציות rlib יפעלו עם המאפיין rustlibs.
rust_library_dylib	מספק רק את הווריאציה dylib של ספריית Rust. אי אפשר להבטיח שמודולים שמספקים רק וריאציות dylib יפעלו עם המאפיין rustlibs.

rust_ffi

מודול rust_ffi יוצר ספריות שתואמות ל-C כדי לאפשר פעולה הדדית עם מודולים של CC.

בנוסף ל_host variants, לספריות Rust FFI יש סוגי מודולים ששולטים בקישור הזמין, כמו שמוצג בטבלה הבאה.

סוג מודול של ספריית Rust FFI	הגדרה
rust_ffi	הספרייה מספקת שני סוגים של ספריות C: סטטית ומשותפת.
rust_ffi_shared	מספק רק את הגרסה של הספרייה המשותפת C.
rust_ffi_static	מספק רק את הגרסה של ספריית C סטטית.

דוגמה בסיסית לשימוש ב-rust_ffi לקריאה ל-Rust מ-C מופיעה בדף Android Rust Patterns.

מידע על שימוש מתקדם יותר זמין במאמרי העזרה הרשמיים של Rust.

rust_proc_macro

פקודות מאקרו פרוצדורליות (proc-macros) של Rust יכולות להיות שימושיות להרחבת הקומפיילר כדי לבצע טרנספורמציות של קוד מקור או לספק מאפיינים חדשים. מידע נוסף זמין בדף Procedural Macros במסמכי התיעוד הרשמיים של Rust.

לצורך מערכת הבנייה, המודול rust_proc_macro פועל באופן דומה למודולים rust_library. במודולים שתלויים ב-rust_proc_macros, צריך להוסיף את שם המודול למאפיין proc_macros.

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

מאפיינים בולטים של ספריות Rust

המאפיינים שמוגדרים בטבלה שלמטה הם בנוסף למאפיינים משותפים חשובים שרלוונטיים לכל המודולים. הם חשובים במיוחד למודולים של ספריות Rust, או שהם מציגים התנהגות ייחודית שספציפית לסוג המודול rust_library.

מאפייני ספריית Rust	הגדרה
stem / name	המאפיין stem קובע את שם הקובץ של ספריית הפלט, שאם לא מציינים אותו, ברירת המחדל היא name. קומפיילר Rust מטיל דרישות מסוימות על שמות קבצים של ספריות, וכתוצאה מכך מערכת ה-Build אוכפת את הדרישות האלה כדי למנוע בעיות קומפילציה. שם קובץ הפלט צריך להיות בפורמט lib<crate_name><suffix>. (יש כאן תלות במאפיין crate_name).
crate_name	זהו מאפיין חובה למודולים שמפיקים ספריות; יש לו גם קשר לשם קובץ הפלט. (ראו את ההגדרה של stem).
export_include_dirs	במודולים מסוג rust_ffi, המאפיין הזה מגדיר רשימה של מחרוזות שמייצגות נתיבי include יחסיים: נתיבים שמכילים כותרות שבהן יכולים להשתמש מודולים תלויים מסוג cc.

קישור של rust_library או rust_ffi

כברירת מחדל, מודולים של ספריות Rust שמיועדים למכשירים תמיד מקושרים באופן דינמי ל-libstd. עם זאת, מודולים של מארחים תמיד מקושרים באופן סטטי ל-libstd.

הקישור שמשמש לתלות של rustlibs תלוי בהעדפות הקישור של מודול הבסיס. (לדוגמה, rust_binary עם prefer_rlib: true ישתמש בווריאציות של ספריית Rust שמקשרות rustlibs בתור rlibs).

כדי לאפשר יצירה של מודולים של תלות ברמה הבסיסית שלא מסתמכים על ספריות דינמיות של Rust (כמו קובצי הפעלה סטטיים), rlibs מספקת וריאציות של קישור דינמי וסטטי של libstd. הווריאציה הנכונה מקושרת אוטומטית על ידי Soong.