מודולים של Protobuf

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

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

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

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

שימוש בסיסי ב-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",
}

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

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

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

כל קובץ protobuf מאורגן כמודול משלו בתוך ה-crate, עם השם של קובץ ה-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

המאפיינים שמפורטים בהמשך הם בנוסף למאפיינים משותפים חשובים שחלים על כל המודולים. הם חשובים במיוחד למודולים של protobuf ב-Rust, או שהם מציגים התנהגות ייחודית ספציפית לסוג המודול 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>. כך אפשר למנוע התנגשויות בשמות עם מקורות שנוצרו מכל proto.

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