מודולים של Protobuf

מערכת ה-build תומכת ביצירת ממשקי protobuf באמצעות סוג המודול rust_protobuf.

יצירת קוד בסיסי של protobuf מתבצעת באמצעות תיבת הכלים rust-protobuf. כדי לראות מאמרי עזרה על השימוש הזה, אפשר לעיין בדף הפרויקט ב-GitHub עם דוגמאות תואמות של protobuf.

יש תמיכה גם ב-protobufs של gRPC, והיצירה מתבצעת על ידי תיבת הכלים grpc-rs. כדי לעיין במסמכי התיעוד בנושא השימוש הזה, אפשר לעבור אל מסמכי התיעוד בדף הפרויקט התואם של gRPC ב-GitHub.

שימוש בסיסי ב-rust_protobuf build

בדוגמה הבאה מוגדר מודול protobuf, והמודול הזה משמש כ-crate. פרטים נוספים על מאפיינים חשובים ועל אופן השימוש בהם מופיעים בקטע הגדרת rust_protobuf.

אם אתם צריכים להשתמש בקוד שנוצר על ידי protobuf באמצעות מאקרו include!(), למשל עבור קוד של צד שלישי, תוכלו לראות דוגמה בדף מחוללי מקורות. (בדוגמה נעשה שימוש במודול rust_bindgen, אבל האופן שבו המקור נכלל זהה לכל מחוללי המקור).

הגדרת מודול rust_protobuf ב-Android.bp

נניח שיש קובץ proto בנתיב src/protos/my.proto ביחס לקובץ Android.bp. הגדרת המודול תהיה כזו:

rust_protobuf {
    name: "libmy_proto",

    // Crate name that's used to generate the rust_library variants.
    crate_name: "my_proto",

    // Relative paths to the protobuf source files
    protos: ["src/protos/my.proto"],

    // If protobufs define gRPCs, then they should go in grpc_protos
    // instead.
    // grpc_protos: ["src/protos/my.proto"],

    // 'source_stem' controls the output filename.
    // This is the filename that's used in an include! macro.
    source_stem: "my_proto_source",
}

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

rust_binary {
    name: "hello_rust_proto",
    srcs: ["src/main.rs"],
    rustlibs: ["libmy_proto"],
}

מבנה ה-Crate של מודולים של rust_protobuf

כל קובץ protobuf מאורגן כמודול משלו בתוך ה-crate, והשם שלו זהה לשם של קובץ ה-protobuf. כלומר, כל שמות הקבצים הבסיסיים של פרוטו חייבים להיות ייחודיים. לדוגמה, ניקח את rust_protobuf שמוגדר כך:

rust_protobuf {
    name: "libfoo",
    crate_name: "foo",
    protos: ["a.proto", "b.proto"],
    grpc_protos: ["c.proto"],
    source_stem: "my_proto_source",
}

כך ניגשים לפרוטוקולים השונים בתיבת הכלים הזו:

// use <crate_name>::<proto_filename>
use foo::a; // protobuf interface defined in a.proto
use foo::b; // protobuf interface defined in b.proto
use foo::c; // protobuf interface defined in c.proto
use foo::c_grpc; // grpc interface defined in c.proto

מאפיינים חשובים של rust_protobuf

המאפיינים שמוגדרים בהמשך הם בנוסף למאפיינים משותפים חשובים שחלים על כל המודולים. הן חשובות במיוחד למודולי Rust protobuf, או שהן מציגות התנהגות ייחודית שספציפית לrust_protobufסוג המודול.

stem, name, crate_name

‫rust_protobuf יוצר וריאציות של ספריות, ולכן יש דרישות זהות לשלושת המאפיינים האלה כמו למודולים של rust_protobuf.rust_library פרטים נוספים מופיעים במאמר בנושא מאפייני rust_library.

protos

זוהי רשימה של נתיבים יחסיים לקובצי ה-protobuf כדי ליצור את ממשק ה-protobuf. שמות קובצי הבסיס צריכים להיות ייחודיים ב-protos וב-grpc_protos.

grpc_protos

השדה grpc_protos מכיל רשימה של נתיבים יחסיים לקובצי ה-protobuf שמגדירים את grpcs כדי ליצור את ממשק ה-protobuf. שמות קבצי הבסיס צריכים להיות ייחודיים ב-protos וב-grpc_protos.

source_stem

‫source_stem הוא שם הקובץ של קובץ המקור שנוצר שאפשר לכלול. זו הגדרה נדרשת של שדה, גם אם משתמשים ב-bindings כ-crate, כי המאפיין stem שולט רק בשם קובץ הפלט של הווריאציות של הספריות שנוצרו. בשונה ממחוללי מקורות אחרים, שם הקובץ מקבל קידומת mod_‎, כך ששם הקובץ הסופי הוא mod_<stem>‎. כך נמנעות התנגשויות בשמות עם מקורות שנוצרו מכל פרוטו.

בנוסף, כמו במודול הכריכות bindgen, גם כאן זמין סט מלא של מאפייני ספרייה לשליטה בהידור הספרייה, אם כי בדרך כלל אין צורך להגדיר או לשנות אותם.