הצהרה על דגל 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, אתם יכולים להשתמש במרחב השמות (namespace) כרצונכם.

   • 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, אתם יכולים להשתמש במרחב השמות (namespace) כרצונכם.

   • 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 מפעיל את ה-Codegen של C או C++‎, שיוצר ספרייה עם הקוד שנוצר בזמן ה-build.

   ספריית CC aconfig דומה ליעד של ספריית 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. עכשיו אפשר להשתמש בדגלים של aconfig בקוד, אחרי שיוצרים רשומה cc_library עם שם הספרייה הסטטית.

הצהרת דגל 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, אתם יכולים להשתמש במרחב השמות (namespace) כרצונכם.

   • 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 Codegen ויוצר ספריית 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. שומרים את הקובץ ויוצאים מהכלי לעריכה.