הצהרה על דגל aconfig

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

הצהרה על דגל aconfig ל-Java

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

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

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. בקובץ הבנייה 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 הוא קובץ פרוטו טקסט שפועל לפי סכימה סטנדרטית.

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. בקובץ הבנייה 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 שבו נעשה שימוש בהצהרה.

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

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

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

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. בקובץ הבנייה 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 עם הקוד שנוצר במהלך זמן הבנייה.

   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",
     ]
   }
   

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

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