מודולים של Protobuf

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

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

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

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

בדוגמה הבאה מוסבר איך מגדירים מודול 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",
}

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

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

מבנה הארגז של מודולים של rust_protobuf

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

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

הגישה לפרוטוקולים השונים בתוך ה-crate תתבצע באופן הבא:

// 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_library. פרטים נוספים זמינים במאמר בנושא המאפיינים rust_library.

protos

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

grpc_protos

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

source_stem

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

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