הצהרה על דגל aconfig

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

אפשר להשתמש בדגלי aconfig בקוד Java,‏ C,‏ C++ ו-Rust. מערכת ה-build של AOSP מפעילה כלי שנקרא aconfig, שמשממש ליצירת ספרייה ספציפית לשפה של שיטות שאפשר להשתמש בהן כדי לגשת לערך של כל דגל. לפני שאפשר ליצור בספרייה, צריך להצהיר על דגלים ולהוסיף אותם ל-build.

הצהרה על דגל aconfig עבור Java

כדי להצהיר על דגל aconfig ל-Java:

1. בספרייה שבה קיים הקוד החדש, יוצרים קובץ עם הסיומת .aconfig, למשל, my_new_aconfig_flag_declarations.aconfig. קובץ aconfig הוא קובץ טקסט פרוטו (proto) שמבוסס על סכימה סטנדרטית.

2. מוסיפים הצהרת סימון שדומה לזו:

   package: "com.example.android.aconfig.demo.flags"
   container: "system"
   
   flag {
       name: "my_new_flag"
       namespace: "aconfig_demo_namespace"
       description: "This flag controls untested code"
       bug: "<none>"
   }
   

   איפה:

   • השדה package, בשילוב עם שם הדגל, מספק מפתח ייחודי. ב-Java, אם מגדירים את package לערך foo.bar, תופיע מחלקה שנוצרה באופן אוטומטי בשם foo.bar.Flags. ב-C++, השיטות של רכיב הגישה לדגלים יקבלו שמות foo::bar::"flagname" דגלים באותו קובץ הצהרה שייכים לאותה חבילה, אבל כמה קובצי הצהרה יכולים לתרום דגלים לאותה חבילה.

   • container מגדיר אוסף של קוד שנוצר ונשלח יחד כקובץ בינארי. קונטיינרים חוקיים הם system, vendor, system_ext, product, name.of.apex וגם name.of.apk.

   • השדה name מכיל את שם הדגל, שיכול להכיל רק אותיות קטנות, קווים תחתונים ומספרים.

   • namespace מכיל את מרחב השמות לתרומות. עליכם לפנות למבקר של Google שהוקצה לכם כדי לקבוע את מרחב השמות. אם אתם משתמשים כדי לשמור על היציבות של מראה ה-AOSP שלכם, אתם יכולים להשתמש במרחב שמות איך שרוצים.

   • description מכיל תיאור קצר של התכונה או השינוי מסומנת.

   • bug הוא מספר הבאג שמשויך לקוד החדש שתרמתם. צריך עליך לעבוד עם הבודק של Google שאחראי על החשבון שלך כדי לקבוע את bug. אם אתם משתמשים בדגלים להשקת תכונות כדי לשמור על יציבות במראה ה-AOSP שלכם, תוכלו להשתמש במספר המעקב אחרי הבאגים או ב-<none>.

3. שומרים את הקובץ ויוצאים מהעורך.

הגדרת ה-build

אחרי שמצהירים על הדגל, צריך להגדיר את ה-build כך שיוכל ליצור את קוד הספרייה שמשמש לגישה לערך הדגל.

1. בקובץ ה-build של Android.bp, צריך להוסיף קטע aconfig_declarations כמו:

   aconfig_declarations {
     name: "aconfig_demo_flags",
     package: "com.example.android.aconfig.demo.flags",
     srcs: [
       "my_new_aconfig_flag_declarations.aconfig"
     ],
   }
   

   איפה:

   • השדה name מכיל את שם ההצהרה שמכילה רק את אותיות קטנות, קווים תחתונים ומספרים.
   • שם החבילה package מכיל את אותו שם חבילה שנעשה בו שימוש בהצהרה.
   • srcs מכיל את השם של הקובץ .aconfig שבו הוצהר על הדגל.

2. שומרים את הקובץ ויוצאים מהעורך.

הצהרת דגל aconfig עבור C ו-C++

כדי להצהיר על דגל aconfig עבור C ו-C++:

1. בספרייה שבה נמצא הקוד החדש, יוצרים קובץ עם הסיומת .aconfig, למשל my_new_aconfig_flag_declarations.aconfig. קובץ aconfig הוא קובץ טקסט פרוטו (proto) שמבוסס על סכימה סטנדרטית.

2. מוסיפים הצהרת סימון שדומה לזו:

   package: "com.example.android.aconfig.demo.flags"
   container: "system"
   
   flag {
       name: "my_new_flag"
       namespace: "aconfig_demo_namespace"
       description: "This flag controls untested code"
       bug: "<none>"
   }
   

   איפה:

   • השדה package, בשילוב עם שם הדגל, מספק מפתח ייחודי. ב-Java, אם מגדירים את package לערך foo.bar, תופיע מחלקה שנוצרה באופן אוטומטי בשם foo.bar.Flags. ב-C++, השיטות של רכיב הגישה לדגלים יקבלו שמות foo::bar::"flagname" דגלים באותו קובץ הצהרה שייכים לאותה חבילה, אבל כמה קובצי הצהרה יכולים לתרום דגלים לאותה חבילה.

   • container מגדיר אוסף של קוד שנוצר ונשלח יחד כקובץ בינארי. קונטיינרים חוקיים הם system, vendor, system_ext, product, name.of.apex וגם name.of.apk.

   • השדה name מכיל את שם הדגל, שיכול להכיל רק אותיות קטנות, קווים תחתונים ומספרים.

   • namespace מכיל את מרחב השמות לתרומות. עליכם לפנות למבקר של Google שהוקצה לכם כדי לקבוע את מרחב השמות. אם אתם משתמשים כדי לשמור על היציבות של מראה ה-AOSP שלכם, אתם יכולים להשתמש במרחב שמות איך שרוצים.

   • description מכיל תיאור קצר של התכונה או השינוי מסומנת.

   • bug הוא מספר הבאג שמשויך לקוד החדש שתרמתם. צריך עליך לעבוד עם הבודק של Google שאחראי על החשבון שלך כדי לקבוע את bug. אם אתם משתמשים בדגלים להשקת תכונות כדי לשמור על יציבות במראה ה-AOSP שלכם, תוכלו להשתמש במספר המעקב אחרי הבאגים או ב-<none>.

3. שומרים את הקובץ ויוצאים מהעורך.

הגדרת ה-build

אחרי שמצהירים על הדגל, צריך להגדיר את ה-build כך שיוכל ליצור את קוד הספרייה שמשמש לגישה לערך הדגל.

1. בקובץ ה-build‏ Android.bp, מוסיפים קטע aconfig_declarations שדומה לקטע הבא:

   aconfig_declarations {
     name: "aconfig_demo_flags",
     package: "com.example.android.aconfig.demo.flags",
     srcs: [
       "my_new_aconfig_flag_declarations.aconfig"
     ],
   }
   

   איפה:

   • השדה name מכיל את שם ההצהרה שמכילה רק את אותיות קטנות, קווים תחתונים ומספרים.
   • השדה package מכיל את אותו שם חבילה שצוין בהצהרה.
   • srcs מכיל את השם של קובץ aconfig שבו הדגל מוצהר.

2. באותו קובץ, יוצרים יעד cc_aconfig_library שדומה לזה:

   cc_aconfig_library {
       name: "aconfig_demo_flags_c_lib",
       aconfig_declarations: "aconfig_demo_flags",
   }
   

   איפה:

   • name מכיל את שם הספרייה שמכילה רק אותיות קטנות, קווים תחתונים ומספרים.
   • השדה aconfig_declarations מכיל את אותו ערך מסוג name שנעשה בו שימוש בהצהרה.

   היעד של גרסת ה-build של cc_aconfig_library מפעיל את הקוד C או C++ , ספרייה עם הקוד שנוצר בזמן ה-build.

   ספריית ה-CC של ספריית ה-CC דומה לטירגוט של ספריית CC, אבל אפשרויות כמו vendor_available, product_available, host_supported ו vndk אם יעד ה-build שמבוסס על cc_aconfig_library הזה דורש סוג מסוים של וריאנטים, יכול להיות שתצטרכו להוסיף את ההגדרה המתאימה גם ליעד של ספריית CC aconfig. לדוגמה, אם הערך של vendor_available הוא true ביעד ה-build של ההורה, כדאי להגדיר את vendor_available גם לערך true ביעד cc_aconfig_library הזה.

   אחרי הוספת יעד ה-build הזה, לקוד שלך תהיה גישה לספרייה הזו. שלך יכול לכלול את הספרייה הזו באמצעות static_lib או תחביר shared_lib. הערה: אם רוצים להוסיף את הספרייה הזו כ-static_lib, צריך להוסיף תלות shared_lib ב-server_configurable_flags. בשלב 3 מוסבר איך לכלול את ספריית הדגלים שנוצרה בקוד ב-libexample_cpp_lib.

3. יוצרים יעד שמשתמש בדגלי aconfig, כמו בדוגמה הבאהcc_library:

   cc_library {
       name: "libexample_cpp_lib",
       srcs: ["src/example_cpp_lib.cc"],
       double_loadable: true,
       cflags: [
           "-Wall",
           "-Werror",
           "-Wno-unused-function",
           "-Wno-unused-parameter",
       ],
       header_libs: [
           "jni_headers",
       ],
       shared_libs: [
           "server_configurable_flags",
       ],
       static_libs: [
           "aconfig_demo_flags_c_lib",
       ],
       export_include_dirs: ["src/include"],
   }
   

   איפה:

   • shared_libs כולל יחסי תלות נוספים שנדרשים לדגלי aconfig.
   • static_libs הוא שם הספרייה שנוצרת על ידי ה-build בהתאם לשדה cc_aconfig_library name בשלב 2. על ידי יצירה של רשומת cc_library בשם הספרייה הסטטית, תוכלו עכשיו להשתמש בדגלי aconfig בקוד.

הצהרת דגל aconfig ל-Rust

כדי להצהיר על דגל aconfig ב-Rust:

1. בספרייה שבה קיים הקוד החדש, יוצרים קובץ עם הסיומת .aconfig, למשל, my_new_aconfig_flag_declarations.aconfig. קובץ aconfig הוא קובץ טקסט proto שתואם לסכימה רגילה.

2. מוסיפים הצהרת סימון שדומה לזו:

   package: "com.example.android.aconfig.demo.flags"
   container: "system"
   
   flag {
       name: "my_new_flag"
       namespace: "aconfig_demo_namespace"
       description: "This flag controls untested code"
       bug: "<none>"
   }
   

   איפה:

   • השדה package, בשילוב עם שם הדגל, מספק מפתח ייחודי. ב-Java, אם מגדירים את package לערך foo.bar, תופיע מחלקה שנוצרה באופן אוטומטי בשם foo.bar.Flags. ב-C++, השיטות של רכיב הגישה לדגלים יקבלו שמות foo::bar::"flagname" דגלים באותו קובץ הצהרה שייכים לאותה חבילה, אבל כמה קובצי הצהרה יכולים לתרום דגלים לאותה חבילה.

   • container מגדיר אוסף של קוד שנוצר ונשלח יחד כקובץ בינארי. קונטיינרים חוקיים הם system, vendor, system_ext, product, name.of.apex וגם name.of.apk.

   • השדה name מכיל את שם הדגל, שיכול להכיל רק אותיות קטנות, קווים תחתונים ומספרים.

   • namespace מכיל את מרחב השמות לתרומות. עליכם לפנות למבקר של Google שהוקצה לכם כדי לקבוע את מרחב השמות. אם אתם משתמשים כדי לשמור על היציבות של מראה ה-AOSP שלכם, אתם יכולים להשתמש במרחב שמות איך שרוצים.

   • description מכיל תיאור קצר של התכונה או השינוי מסומנת.

   • bug הוא מספר הבאג שמשויך לקוד החדש שתרמתם. צריך עליך לעבוד עם הבודק של Google שאחראי על החשבון שלך כדי לקבוע את bug. אם אתם משתמשים בדגלים להשקת תכונות כדי לשמור על יציבות במראה ה-AOSP שלכם, תוכלו להשתמש במספר המעקב אחרי הבאגים או ב-<none>.

3. שומרים את הקובץ ויוצאים מהעורך.

הגדרת ה-build

אחרי שמצהירים על הדגל, מגדירים את ה-build כדי שהוא יוכל ליצור את קוד הספרייה המשמש לגישה לערך הדגל.

1. בקובץ ה-build‏ Android.bp, מוסיפים קטע aconfig_declarations שדומה לזה:

   aconfig_declarations {
     name: "aconfig_demo_flags",
     package: "com.example.android.aconfig.demo.flags",
     srcs: [
       "my_new_aconfig_flag_declarations.aconfig"
     ],
   }
   

   איפה:

   • השדה name מכיל את שם ההצהרה שמכילה רק את אותיות קטנות, קווים תחתונים ומספרים.
   • השדה package מכיל את אותו שם חבילה שצוין בהצהרה.
   • srcs מכיל את השם של קובץ ה-aconfig שבו הדגל מוצהר.

2. יוצרים יעד rust_aconfig_library שדומה לדוגמה הבאה. הזה היעד מפעיל קודן Rust ויוצר ספריית חלודה באמצעות הקוד שנוצר בזמן ה-build.

   rust_aconfig_library {
     name: "libaconfig_demo_flags_rust",
     crate_name: "aconfig_demo_flags_rust",
     aconfig_declarations: "aconfig_demo_flags",
   }
   

   איפה:

   • השדה name מכיל את שם ההצהרה שמכילה רק את אותיות קטנות, קווים תחתונים ומספרים.
   • השדה crate_name מכיל את אותו שם חבילה שצוין בהצהרה.
   • השדה aconfig_declarations מכיל את אותו ערך מסוג name שנעשה בו שימוש בהצהרה.

   בעקבות השינוי הזה, הקוד שלכם יכול להסתמך על ספריית Rust הזו.

3. באותו קובץ, יוצרים רשומה rust_library שדומה לזו:

   rust_library {
     name: "libexample_lib",
     rustlibs: [
         "libaconfig_demo_flags_rust",
     ]
   }
   

   הדוגמה הזו מאפשרת להגדיר את יעדי ה-build של קוד המקור libexample_demo_flags_rust כדי לכלול את ספריית הדגלים שנוצרה באמצעות הקוד.

4. שומרים את הקובץ ויוצאים מהעורך.