تحديد علامة aconfig

يمكنك استخدام علامات aconfig في رموز Java وC وC++ وRust البرمجية. يُشغِّل نظام التصميم في مشروع Android المفتوح المصدر (AOSP) أداة تُعرف باسم aconfig تُستخدَم لإنشاء مكتبة خاصة باللغة تتضمّن طرقًا يمكنك استخدامها للوصول إلى قيمة كل علامة. قبل أن تتمكّن من إنشاء المكتبة، عليك الإعلان عن العلامات وإضافتها إلى الإصدار.

الإعلان عن علامة 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. احفظ الملف واخرج من المحرّر.

إعداد الإصدار

بعد الإعلان عن علامتك، اضبط الإصدار ليتمكّن من إنشاء رمز المكتبة المستخدَم للوصول إلى قيمة العلامة.

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 هو ملف نصي بتنسيق 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. احفظ الملف واخرج من المحرّر.

إعداد الإصدار

بعد الإعلان عن علامتك، اضبط الإصدار ليتمكّن من إنشاء رمز المكتبة المستخدَم للوصول إلى قيمة العلامة.

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 أداة C أو C++ Codegen، التي تنشئ مكتبة تتضمّن الرمز البرمجي الذي تم إنشاؤه في مدّة التصميم.

   تشبه مكتبة aconfig لـ CC هدف مكتبة CC، ولكنها تتضمّن خيارات مثل vendor_available وproduct_available وhost_supported وvndk. إذا كان هدف الإصدار الذي يعتمد على cc_aconfig_library هذا يتطلّب نوعًا معيّنًا من المتغيّرات، قد تحتاج أيضًا إلى إضافة الإعداد المقابل في هدف مكتبة aconfig لـ 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 هو اسم المكتبة التي ينشئها الإصدار لكل حقل name في cc_aconfig_library في الخطوة 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. احفظ الملف واخرج من المحرّر.

إعداد الإصدار

بعد الإعلان عن علامتك، اضبط الإصدار ليتمكّن من إنشاء رمز المكتبة المستخدَم للوصول إلى قيمة العلامة.

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. احفظ الملف واخرج من المحرّر.