فرض واجهات أقسام المنتجات

يفصل Android 11 قسم "product"، ما يجعله بشكل مستقل عن القسمين system وvendor. وفي إطار هذه التغييرات، يمكنك الآن التحكّم في وصول قسم product إلى النسخة الأصلية ولغة Java الواجهات (التي تشبه طريقة عمل فرض الواجهات في vendor الأقسام).

فرض واجهات أصلية

لتفعيل فرض الواجهة الأصلية، يجب ضبط PRODUCT_PRODUCT_VNDK_VERSION إلى current. (يتم ضبط الإصدار تلقائيًا على current عند الشحن مستوى واجهة برمجة التطبيقات المستهدَف أكبر من 29). يتيح قسم التنفيذ ما يلي:

• الوحدات الأصلية في قسم product المطلوب الربط به:
  • بشكل ثابت أو ديناميكي إلى وحدات أخرى في قسم product التي تتضمّن مكتبات ثابتة أو مشتركة أو مكتبات رؤوس
  • ديناميكيًا إلى مكتبات VNDK في القسم system
• مكتبات JNI في حِزم APK غير المجمّعة في قسم product لربطها بمكتبات في /product/lib أو /product/lib64 (بالإضافة إلى مكتبات NDK)

لا يسمح فرض الامتثال بإنشاء روابط أخرى إلى أقسام غير القسم product .

فرض وقت التصميم (Android.bp)

في Android 11، يمكن لوحدات النظام إنشاء منتج. لمتغير الصورة بالإضافة إلى خيارات الصورة الأساسية وصورة المورد. عند تفعيل فرض استخدام واجهة برمجة التطبيقات الأصلية (يتم ضبط PRODUCT_PRODUCT_VNDK_VERSION على current):

• تتوفّر الوحدات الأصلية في قسم product ضمن خيار المنتج بدلاً من ذلك. من السعر المتغير الأساسي

• الوحدات التي تحتوي على product_available: true في ملفات Android.bp هي: المتوفرة لخيار المنتج.

• يمكن للمكتبات أو البرامج الثنائية التي تحدد product_specific: true الارتباط بأخرى المكتبات التي تحدّد product_specific: true أو product_available: true في ملفات Android.bp.

• يجب أن تحتوي مكتبات VNDK على product_available: true في ملفات Android.bp. حتى تتمكن برامج ثنائية product من الارتباط بملفات VNDK libs.

يلخّص الجدول التالي سمات Android.bp المستخدَمة لإنشاء صيغ الصور.

السمات في Android.bp	الأسعار المتغيرة التي تم إنشاؤها
	قبل التنفيذ	بعد التنفيذ
تلقائي (بدون)	الأساسية (تشمل /system و/system_ext /product)	قلب (يشمل /system و/system_ext، ولكن ليس /product)
system_ext_specific: true	الأساسية	قلب
product_specific: true	قلب	المنتج
vendor: true	المُورِّد	المُورِّد
vendor_available: true	أساسي، بائع	أساسي، بائع
product_available: true	لا ينطبق	أساسي، منتج
vendor_available: true وproduct_available: true	لا ينطبق	الأساسية، المنتج، المورّد
system_ext_specific: true وvendor_available: true	الأساسية، المورّد	الأساسية، المورّد
product_specific: true وvendor_available: true	الأساسية، المورّد	منتج، بائع

فرض وقت الإصدار (Android.mk)

عند تفعيل فرض الواجهة الأصلية، يتم تثبيت الوحدات الأصلية على يحتوي قسم "product" على نوع رابط native:product يمكن الربط به فقط. وحدات native:product أو native:vndk الأخرى تؤدي محاولة الربط بأي وحدات أخرى غير هذه الوحدات إلى أن يُنشئ نظام الإنشاء خطأً في التحقّق من نوع الرابط.

فرض بيئة التشغيل

عند تفعيل فرض الواجهات الأصلية، لا تسمح إعدادات الرابط ل رابط Bionic لعمليات النظام باستخدام مكتبات product، وبذلك يتم إنشاء قسم product لعمليات product التي لا يمكنها الربط بمكتبات خارج قسم product (ومع ذلك، يمكن لهذه العمليات الربط بمكتبات VNDK). تتسبب محاولات انتهاك تهيئة رابط بيئة التشغيل في فشل العملية وظهور رسالة الخطأ CANNOT LINK EXECUTABLE.

فرض واجهات Java

لتفعيل فرض واجهة Java، اضبط PRODUCT_ENFORCE_PRODUCT_PARTITION_INTERFACE على true. (يتم ضبط القيمة تلقائيًا على true عندما يكون مستوى Shipping API للهدف أكبر من 29.) عند تفعيل هذا الخيار، يسمح إجراء التنفيذ بما يلي أو لا يسمح به: الوصول:

واجهة برمجة التطبيقات	/system	/system_ext	/product	/vendor	/data
واجهة برمجة التطبيقات العامة
@SystemApi
@hide API

كما هو الحال في القسم vendor، يُسمح للتطبيق أو مكتبة Java في القسم product باستخدام واجهات برمجة التطبيقات العامة وواجهات برمجة تطبيقات النظام فقط، ولا يُسمح بالربط بمكتبة تستخدم واجهات برمجة تطبيقات مخفية. يشمل ذلك الربط عند الإصدار. الوقت والانعكاس في وقت التشغيل

فرض وقت الإصدار

في وقت الإنشاء، يتحقّق كلّ من Make وSoong من أنّ وحدات Java في القسم product لا تستخدم واجهات برمجة تطبيقات مخفية من خلال التحقّق من الحقلين platform_apis و sdk_version. يجب ملء الحقل sdk_version للتطبيقات في القسم product بـ current أو system_current أو إصدار رقمي لواجهة برمجة التطبيقات، ويجب أن يكون الحقل platform_apis فارغًا.

فرض قيود وقت التشغيل

يتحقّق نظام التشغيل Android من أنّ التطبيقات في القسم product لا تستخدم واجهات برمجة تطبيقات مخفية، بما في ذلك ميزة "العرض المرجعي". لمعرفة التفاصيل، يمكنك الرجوع إلى المقالة القيود المفروضة على ليس حزمة SDK الواجهات.

تفعيل فرض واجهة المنتج

استخدِم الخطوات الواردة في هذا القسم لتفعيل فرض واجهة المنتج.

الخطوة	المهمة	مطلوب
1	حدِّد ملف make الخاص بالنظام الذي يحدِّد الحِزم للقسيمة system، ثم اضبط عملية التحقّق من متطلبات مسار العناصر في device.mk (لمنع تثبيت وحدات غير نظامية على قسم system).	N
2	تنظيف القائمة المسموح بها	N
3	فرض الواجهات الأصلية وتحديد حالات تعذُّر ربط وقت التشغيل (يمكن تشغيله في موازاةً مع فرض Java)	Y
4	فرض واجهات Java والتحقق من سلوك بيئة التشغيل (يمكن أن يتم التشغيل بالتوازي من خلال فرض الإعلانات المدمجة مع المحتوى).	Y
5	يمكنك التحقّق من سلوكيات بيئة التشغيل.	Y
6	تعديل device.mk مع فرض واجهة المنتج	Y

الخطوة 1: إنشاء ملف makefile وتفعيل التحقُّق من مسار العناصر

في هذه الخطوة، يمكنك تحديد ملف system makefile.

1. أنشئ ملف makefile يحدّد الحِزم لقسيمة system. على سبيل المثال، أنشئ ملف oem_system.mk يتضمّن ما يلي:

   $(call inherit-product, $(SRC_TARGET_DIR)/product/handheld_system.mk)
   $(call inherit-product, $(SRC_TARGET_DIR)/product/telephony_system.mk)
   
   # Applications
   PRODUCT_PACKAGES += \
       CommonSystemApp1 \
       CommonSystemApp2 \
       CommonSystemApp3 \
   
   # Binaries
   PRODUCT_PACKAGES += \
       CommonSystemBin1 \
       CommonSystemBin2 \
       CommonSystemBin3 \
   
   # Libraries
   PRODUCT_PACKAGES += \
       CommonSystemLib1 \
       CommonSystemLib2 \
       CommonSystemLib3 \
   
   PRODUCT_SYSTEM_NAME := oem_system
   PRODUCT_SYSTEM_BRAND := Android
   PRODUCT_SYSTEM_MANUFACTURER := Android
   PRODUCT_SYSTEM_MODEL := oem_system
   PRODUCT_SYSTEM_DEVICE := generic
   
   # For system-as-root devices, system.img should be mounted at /, so we
   # include ROOT here.
   _my_paths := \
    $(TARGET_COPY_OUT_ROOT)/ \
    $(TARGET_COPY_OUT_SYSTEM)/ \
   
   $(call require-artifacts-in-path, $(_my_paths),)
   

2. في ملف device.mk، عليك اكتساب ملف العلامة التجارية الشائع لـ system. عملية التقسيم وتفعيل التحقق من متطلبات مسار العناصر. مثلاً:

   $(call inherit-product, $(SRC_TARGET_DIR)/product/oem_system.mk)
   
   # Enable artifact path requirements checking
   PRODUCT_ENFORCE_ARTIFACT_PATH_REQUIREMENTS := strict
   

لمحة عن متطلبات مسار العنصر

عند ضبط PRODUCT_ENFORCE_ARTIFACT_PATH_REQUIREMENTS على true أو strict، يمنع نظام الإصدار تثبيت الحِزم المحددة في ملفات Makefiles أخرى المسارات المحددة في require-artifacts-in-path و تمنع الحِزم محددة في ملف Makefile الحالي من تثبيت العناصر خارج المسارات محددة في require-artifacts-in-path.

في المثال أعلاه، عند ضبط PRODUCT_ENFORCE_ARTIFACT_PATH_REQUIREMENTS على strict، لا يمكن أن تتضمّن ملفات الإنشاء خارج oem_system.mk وحدات تم تثبيتها في القسم root أو system. لتضمين هذه الوحدات، يجب عليك يُرجى تحديدها في ملف oem_system.mk نفسه أو في ملف makefile مضمَّن. تؤدي محاولات تثبيت وحدات لمسارات غير مسموح بها إلى حدوث فواصل تصميم. لحلّ المشكلة الفواصل الإعلانية، يمكنك تنفيذ أحد الإجراءات التالية:

• الخيار 1: تضمين وحدة النظام في ملفات makefiles المضمّنة في oem_system.mk. يؤدي ذلك إلى استيفاء متطلبات مسار العنصر (بما أنّه تتوفر الوحدات الآن في ملف makefile مضمّن)، وبالتالي يسمح بالتثبيت في مجموعة المسارات في require-artifacts-in-path.

• الخيار 2: تثبيت الوحدات في القسم system_ext أو product (و عدم تثبيت الوحدات في قسم system).

• الخيار 3: إضافة وحدات إلى PRODUCT_ARTIFACT_PATH_REQUIREMENT_ALLOWED_LIST تعرض هذه القائمة الوحدات المسموح بها لتثبيتها.

الخطوة 2: إفراغ القائمة المسموح بها

في هذه الخطوة، يمكنك إجراء PRODUCT_ARTIFACT_PATH_REQUIREMENT_ALLOWED_LIST. فارغة، لذا يمكن لجميع الأجهزة التي تشارك oem_system.mk أن تشارك أيضًا system واحدًا . لإفراغ القائمة المسموح بها، انقل أي وحدات في القائمة إلى عليك إضافة system_ext أو product إلى قسم "إنشاء ملفات" في system. هذا النمط هذه الخطوة اختيارية لأنّ تحديد صورة system شائعة ليس مطلوبًا. تفعيل فرض واجهة المنتج. ومع ذلك، فإن إفراغ القائمة المسموح بها مفيدة في تحديد حدود system باستخدام system_ext.

الخطوة 3: فرض الواجهات الأصلية

في هذه الخطوة، قمت بتعيين PRODUCT_PRODUCT_VNDK_VERSION := current، ثم البحث للتعرّف على أخطاء الإصدار والتشغيل وحلّها للتحقّق من عملية تشغيل الجهاز والسجلّات وتحديد أخطاء ربط وقت التشغيل وإصلاحها:

1. ضبط PRODUCT_PRODUCT_VNDK_VERSION := current

2. أنشئ الجهاز وابحث عن أخطاء الإنشاء. من المحتمل أن تظهر لك بعض أخطاء التكامل في حال عدم توفّر خيارات المنتج أو خيارات المنتج الأساسية. الفواصل الشائعة تشمل:

   • لن تكون أي وحدة hidl_interface تحتوي على product_specific: true متوفرة لوحدات النظام. لحلّ هذه المشكلة، يُرجى استبدال "product_specific: true". مع system_ext_specific: true.
   • قد لا تتضمّن الوحدات خيار المنتج المطلوب للمنتج الوحدات. لحلّ هذه المشكلة، اجعل هذه الوحدة متاحة لقسم product من خلال ضبط product_available: true أو نقل الوحدة إلى product من خلال تعيين product_specific: true.

3. حلّ أخطاء الإنشاء والتأكّد من نجاح عملية إنشاء الجهاز

4. وضِّع الصورة البرمجية وابحث عن أخطاء وقت التشغيل في عملية تشغيل الجهاز وسجلاته.

   • إذا كانت العلامة linker من سجلّ حالات الاختبار تعرض CANNOT LINK EXECUTABLE فإن ملف التصميم يفتقد تبعية (ولم يتم التقاطها في وقت الإصدار).
   • للتحقّق من ذلك من نظام الإنشاء، أضِف المكتبة المطلوبة إلى الحقل shared_libs: أو required:.

5. حلّ المشاكل المتعلّقة بالموارد الاعتمادية غير المثبَّتة باستخدام الإرشادات الواردة أعلاه

الخطوة 4: فرض واجهات Java

في هذه الخطوة، يتم إعداد PRODUCT_ENFORCE_PRODUCT_PARTITION_INTERFACE := true، ثم البحث عن أخطاء الإصدار الناتجة وإصلاحها. ابحث عن نوعَين محدّدَين من الأخطاء:

• أخطاء نوع الرابط: يشير هذا الخطأ إلى أنّ أحد التطبيقات يرتبط بوحدات Java التي لها sdk_version أوسع نطاقًا. لحلّ هذه المشكلة، يمكنك توسيع نطاق sdk_version التطبيق أو تقييد sdk_version المكتبة. مثال على الخطأ:

  error: frameworks/base/packages/SystemUI/Android.bp:138:1: module "SystemUI" variant "android_common": compiles against system API, but dependency "telephony-common" is compiling against private API.Adjust sdk_version: property of the source or target module so that target module is built with the same or smaller API set than the source.
  

• أخطاء الرموز: يشير هذا الخطأ إلى أنه لا يمكن العثور على رمز بسبب في واجهة برمجة تطبيقات مخفية. لحلّ هذه المشكلة، استخدِم واجهة برمجة تطبيقات مرئية (غير مخفية) أو ابحث عن بديل. مثال على الخطأ:

  frameworks/opt/net/voip/src/java/com/android/server/sip/SipSessionGroup.java:1051: error: cannot find symbol
              ProxyAuthenticate proxyAuth = (ProxyAuthenticate)response.getHeader(
                                             ^
    symbol:   class ProxyAuthenticate
    location: class SipSessionGroup.SipSessionImpl
  

الخطوة 5: التحقّق من سلوكيات بيئة التشغيل

في هذه الخطوة، عليك التأكّد من أنّ سلوكيات وقت التشغيل على النحو المتوقّع. بالنسبة إلى التطبيقات التي يمكن debugging لها، يمكنك تتبُّع استخدام واجهة برمجة التطبيقات المخفية من خلال السجلّ باستخدام StrictMode.detectNonSdkApiUsage (الذي ينشئ سجلّاً عندما يستخدم التطبيق واجهة برمجة التطبيقات المخفية). بدلاً من ذلك، يمكنك استخدام أداة التحليل الثابت veridex للحصول على نوع الاستخدام (الربط أو الانعكاس) ومستوى القيود ومجموعة استدعاء الدوال البرمجية.

• بناء جملة Veridex:

  ./art/tools/veridex/appcompat.sh --dex-file={apk file}

• مثال على نتيجة Veridex:

  #1: Linking greylist-max-o Landroid/animation/AnimationHandler;-><init>()V use(s):
         Lcom/android/systemui/pip/phone/PipMotionHelper;-><init>(Landroid/content/Context;Landroid/app/IActivityManager;Landroid/app/IActivityTaskManager;Lcom/android/systemui/pip/phone/PipMenuActivityController;Lcom/android/internal/policy/PipSnapAlgorithm;Lcom/android/systemui/statusbar/FlingAnimationUtils;)V
  
  #1332: Reflection greylist Landroid/app/Activity;->mMainThread use(s):
         Landroidx/core/app/ActivityRecreator;->getMainThreadField()Ljava/lang/reflect/Field;
  

لمعرفة تفاصيل عن استخدام veridex، يُرجى الرجوع إلى مقالة الاختبار باستخدام أداة veridex.

الخطوة 6: تحديث device.mk

بعد إصلاح جميع حالات تعذُّر الإنشاء ووقت التشغيل والتأكّد من أنّ سلوكيات وقت التشغيل على النحو المتوقّع، اضبط ما يلي في device.mk:

• PRODUCT_PRODUCT_VNDK_VERSION := current
• PRODUCT_ENFORCE_PRODUCT_PARTITION_INTERFACE := true