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

   ספריית CC aconfig דומה ליעד של ספריית CC, אבל יש לה אפשרויות כמו vendor_available,‏ product_available,‏ host_supported ו-vndk. אם יעד ה-build שמבוסס על cc_aconfig_library הזה דורש סוג מסוים של וריאנטים, יכול להיות שתצטרכו להוסיף את ההגדרה המתאימה גם ליעד של ספריית CC aconfig. לדוגמה, אם יעד ה-build של ההורה מוגדר ל-vendor_available כ-true, כדאי גם להגדיר את 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 כולל יחסי תלות נוספים שנדרשים בשביל דגלי הגדרה.
   • 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 ויוצר ספריית 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 שצוין בהצהרה.

   לאחר השינוי, הקוד יכול להיות תלוי בספריית חלודה זו.

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

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

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

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