מודולים של Protobuf

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

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

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

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

בדוגמה הבאה מוגדר מודול protobuf, והמודול הזה משמש כארגז. פרטים נוספים על מאפיינים חשובים ועל אופן השימוש בהם מופיעים בקטע הגדרת 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"],
}

מבנה ה-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_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 bindings, גם כאן זמין סט מלא של מאפייני ספרייה לשליטה בהידור הספרייה, אם כי בדרך כלל אין צורך להגדיר או לשנות אותם.