הצהרה על דגל 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 כך שיוכל ליצור את קוד הספרייה שמשמש לגישה לערך של הדגל.

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 כך שיוכל ליצור את קוד הספרייה שמשמש לגישה לערך של הדגל.

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

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

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

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