التوافق مع أحجام الصفحات البالغة 16 كيلوبايت

في السابق، كان نظام التشغيل Android يتيح فقط صفحات الذاكرة بحجم 4 كيلوبايت، ما ساعد في تحسين أداء ذاكرة النظام بما يتناسب مع إجمالي مساحة الذاكرة التي كانت تتوفّر عادةً في أجهزة Android. بدءًا من الإصدار 15 من نظام التشغيل Android، يتيح مشروع Android مفتوح المصدر (AOSP) استخدام الأجهزة التي تم ضبطها لاستخدام حجم صفحة يبلغ 16 كيلوبايت (أجهزة 16 كيلوبايت). إذا كان تطبيقك يستخدم أي مكتبات NDK، سواء بشكل مباشر أو غير مباشر من خلال حزمة تطوير برامج (SDK)، عليك إعادة إنشاء تطبيقك لكي يعمل على هذه الأجهزة التي تستخدم صفحات ذاكرة بحجم 16 كيلوبايت.

مع استمرار الشركات المصنّعة للأجهزة في تصميم أجهزة تتضمّن كميات أكبر من الذاكرة الفعلية (RAM)، ستستخدم العديد من هذه الأجهزة أحجام صفحات تبلغ 16 كيلوبايت (وأكبر في النهاية) لتحسين أداء الجهاز. تتيح إضافة دعم للأجهزة التي تستخدم صفحات بحجم 16 كيلوبايت تشغيل تطبيقك على هذه الأجهزة، كما تساعد تطبيقك في الاستفادة من التحسينات المرتبطة بالأداء. وبدون إعادة تجميع، لن تعمل التطبيقات على الأجهزة التي تستخدم صفحات الذاكرة بحجم 16 كيلوبايت في إصدارات Android المستقبلية.

لمساعدتك في إضافة إمكانية استخدام تطبيقك، قدّمنا إرشادات حول كيفية التحقّق مما إذا كان تطبيقك سيتأثر، وكيفية إعادة إنشاء تطبيقك (إذا كان ذلك منطبقًا)، وكيفية اختبار تطبيقك في بيئة بحجم 16 كيلوبايت باستخدام المحاكيات (بما في ذلك صور نظام Android 15 لمحاكي Android).

متطلبات التوافق مع Google Play

لضمان عمل تطبيقك بشكل صحيح على أحدث إصدارات Android، يجب أن تتوافق جميع التطبيقات التي تستهدف الإصدار Android 15 (مستوى واجهة برمجة التطبيقات 35) والإصدارات الأحدث مع صفحات الذاكرة بحجم 16 كيلوبايت على الأجهزة التي تعمل بنظام 64 بت على Google Play. اعتبارًا من 1 فبراير 2027، إذا كانت تحديثات تطبيقك لا تتوافق مع صفحات الذاكرة بحجم 16 كيلوبايت، فلن يكون بإمكانك طرح هذه التحديثات.

الشكل 1. تحذير بشأن التوافق مع Google Play Console

المزايا وتحسينات الأداء

تستهلك الأجهزة التي تم ضبطها على أحجام صفحات تبلغ 16 كيلوبايت مساحة أكبر قليلاً من الذاكرة في المتوسط، لكنها تُجري أيضًا تحسينات متنوعة في الأداء لكل من النظام والتطبيقات:

• أوقات تشغيل التطبيق أقل عندما يكون النظام تحت ضغط الذاكرة: ‫3.16% انخفاضًا في المتوسط، مع تحسينات أكثر أهمية (تصل إلى %30) لبعض التطبيقات التي اختبرناها
• انخفاض في استهلاك الطاقة أثناء تشغيل التطبيق: انخفاض بنسبة% 4.56 في المتوسّط
• تشغيل أسرع للكاميرا: عمليات تشغيل أسرع بنسبة 4.48% في المتوسط، وعمليات تشغيل على البارد أسرع بنسبة 6.60% في المتوسط
• مدة تشغيل النظام المحسَّنة: تحسّنت بنسبة %8 (950 ملي ثانية تقريبًا) في المتوسّط

تستند هذه التحسينات إلى اختبارنا الأوّلي، ومن المرجّح أن تختلف النتائج على الأجهزة الفعلية. وسنقدّم تحليلاً إضافيًا للفوائد المحتملة للتطبيقات أثناء مواصلة الاختبار.

التأكّد من تأثُّر تطبيقك

إذا كان تطبيقك يستخدم أي رموز برمجية أصلية، عليك إعادة إنشاء تطبيقك ليتوافق مع الأجهزة التي تستخدم صفحات ذاكرة بحجم 16 كيلوبايت. إذا لم تكن متأكدًا مما إذا كان تطبيقك يستخدم رمزًا برمجيًا أصليًا، يمكنك استخدام "أداة تحليل حِزم APK" لتحديد ما إذا كان هناك أي رمز برمجي أصلي، ثم التحقّق من توافق أقسام ELF مع أي مكتبات مشتركة تجدها. يوفّر "استوديو Android" أيضًا ميزات تساعدك في رصد مشاكل المحاذاة تلقائيًا.

إذا كان تطبيقك يستخدم فقط الرموز البرمجية المكتوبة بلغة البرمجة Java أو Kotlin، بما في ذلك جميع المكتبات أو حِزم تطوير البرامج (SDK)، يكون تطبيقك متوافقًا مع الأجهزة التي تبلغ سعتها 16 كيلوبايت. ومع ذلك، ننصحك باختبار تطبيقك في بيئة بحجم 16 كيلوبايت للتأكّد من عدم حدوث أي تراجع غير متوقّع في سلوك التطبيق.

هل يستخدم تطبيقك رمزًا برمجية أصلية؟

يستخدم تطبيقك رمزًا برمجية أصلية إذا كان أيّ مما يلي ينطبق عليه:

• يستخدم تطبيقك أي رمز برمجية أصلية بلغة C أو C++. إذا كان تطبيقك يستخدم Android NDK، فهذا يعني أنّه يستخدم رمزًا برمجية أصلية.
• يربط تطبيقك أي مكتبات أو تبعيات أصلية تابعة لجهات خارجية (مثل حزم SDK) تستخدمها.
• تم إنشاء تطبيقك باستخدام أداة إنشاء تطبيقات تابعة لجهة خارجية تستخدم مكتبات أصلية على الجهاز.

تحديد المكتبات المجمّعة من رموز برمجية أصلية باستخدام أداة تحليل ملفات APK

أداة تحليل ملفات APK هي أداة تتيح لك تقييم جوانب مختلفة من حزمة APK التي تم إنشاؤها. لمعرفة ما إذا كان تطبيقك يستخدم رمزًا برمجية أصلية (بغض النظر عمّا إذا كان متوافقًا مع صفحة الذاكرة بحجم 16 كيلوبايت):

1. افتح استوديو Android، ثم انقر على ملف > فتح واختَر أي مشروع.

2. من شريط القوائم، انقر على إنشاء > تحليل حزمة APK...

   

3. اختَر حزمة APK التي تريد تحليلها.

4. ابحث داخل مجلد lib الذي يحتوي على ملفات الكائنات المشترَكة (.so) إذا كانت أيّ منها متوفّرة. إذا كانت أي ملفات كائنات مشترَكة متوفّرة، فهذا يعني أنّ تطبيقك يستخدم رمزًا برمجية أصلية. يعرض عمود المحاذاة رسائل تحذير لأي ملفات تواجه مشاكل في المحاذاة. إذا لم تكن أي ملفات كائنات مشترَكة متوفّرة أو لم يكن هناك مجلد lib، فهذا يعني أنّ تطبيقك لا يستخدم رمزًا برمجية أصلية.

   

رصد مشاكل المحاذاة من خلال عمليات التحقّق الآلية

يعرض "استوديو Android" تحذيرات بشكل استباقي إذا كانت مكتباتك التي تم إنشاؤها مسبقًا أو حزم APK غير متوافقة مع صفحة الذاكرة بحجم 16 كيلوبايت. استخدِم أداة APK Analyzer لمراجعة المكتبات التي يجب تحديثها أو معرفة ما إذا كانت هناك أي تغييرات مطلوبة في الرمز البرمجي.

<figure>
  <img src="/images/guide/practices/studio-align-warnings.png"
       class="no-filter" width="300"
       alt="Studio warning notifications about alignment issues in a project">
</figure>

تُبرز أداة Lint في "استوديو Android" أيضًا المكتبات الأصلية التي لم تتم محاذاتها بشكل يتوافق مع صفحة الذاكرة بحجم 16 كيلوبايت.

<figure>
  <img src="/images/guide/practices/studio-align-lint.png"
       class="no-filter"
       alt="Studio linter warning about a non-aligned native library">
</figure>

التحقّق من محاذاة أقسام ELF للمكتبات المشترَكة

بالنسبة إلى أي مكتبات مشترَكة، تأكَّد من أنّ أقسام ELF للمكتبات المشترَكة تتم محاذاتها بشكل صحيح باستخدام محاذاة ELF بحجم 16 كيلوبايت. إذا كنت تطوّر على نظام التشغيل Linux أو macOS، يمكنك استخدام النص البرمجي check_elf_alignment.sh كما هو موضّح في القسم التالي. يمكنك أيضًا استخدام أدوات سطر الأوامر مباشرةً.

استخدام النص البرمجي check_elf_alignment.sh (على نظام التشغيل Linux أو macOS)

اتّبِع الخطوات التالية للتحقّق من محاذاة أقسام ELF باستخدام النص البرمجي check_elf_alignment.sh:

1. احفظ النص البرمجي check_elf_alignment.sh في ملف.

2. شغِّل النص البرمجي على ملف APK الخاص بتطبيقك:

   check_elf_alignment.sh APK_NAME.apk
   

   يعرض النص البرمجي ALIGNED أو UNALIGNED لجميع المكتبات المشترَكة arm64-v8a.

3. إذا كانت أي مكتبات مشترَكة arm64-v8a أو x86_64 هي UNALIGNED، عليك تعديل عملية التغليف لهذه المكتبات، ثم إعادة تجميع تطبيقك وإعادة اختباره باتّباع الخطوات الواردة في هذا القسم.

استخدام أدوات سطر الأوامر مباشرةً

اتّبِع الخطوات التالية للتحقّق من محاذاة أقسام ELF باستخدام أدوات سطر الأوامر مباشرةً:

1. تأكَّد من تثبيت الإصدار 35.0.0 أو إصدار أحدث من حزمة Android SDK Build-Tools و Android NDK باستخدام SDK Manager في "استوديو Android" أو sdkmanager أداة سطر الأوامر.

2. استخرِج ملف APK الخاص بتطبيقك:

   Linux أو macOS

   unzip APK_NAME.apk -d /tmp/my_apk_out
   

   نظام التشغيل Windows (PowerShell)

   Expand-Archive -Path .\APK_NAME.apk -DestinationPath ~\tmp\my_apk_out
   

3. في الدليل المؤقت الذي استخرجت إليه ملف APK، تحقَّق من محتويات دليل lib بحثًا عن ملفات الكائنات المشترَكة (.so). هذه هي ملفات الكائنات المشترَكة نفسها التي كنت ستراها أثناء تحديد المكتبات المجمّعة من رموز برمجية أصلية باستخدام أداة تحليل ملفات APK. شغِّل الأمر التالي على كل ملف كائن مشترَك:

   Linux أو macOS

   SDK_ROOT_LOCATION/Android/sdk/ndk/NDK_VERSION/toolchains/llvm/prebuilt/darwin-x86_64/bin/llvm-objdump -p SHARED_OBJECT_FILE.so | grep LOAD
   

   نظام التشغيل Windows (PowerShell)

   SDK_ROOT_LOCATION\Android\sdk\ndk\NDK_VERSION\toolchains\llvm\prebuilt\windows-x86_64\bin\llvm-objdump.exe -p SHARED_OBJECT_FILE.so | Select-String -Pattern "LOAD"
   

   حيث SDK_ROOT_LOCATION هو المسار إلى الدليل الذي ثبَّت فيه حزمة Android SDK، وSHARED_OBJECT_FILE هو اسم ملف الكائن المشترَك الذي تتحقّق منه، وNDK_VERSION هو إصدار Android NDK الذي ثبَّته (على سبيل المثال، 28.0.12433566). ستبدو النتائج على النحو التالي لكل ملف تتحقّق منه:

   LOAD off    0x0000000000000000 vaddr 0x0000000000000000 paddr 0x0000000000000000 align 2**14
   LOAD off    0x0000000000042a90 vaddr 0x0000000000043a90 paddr 0x0000000000043a90 align 2**14
   LOAD off    0x0000000000046230 vaddr 0x0000000000048230 paddr 0x0000000000048230 align 2**14
   

4. تحقَّق من أسطر النتائج للتأكّد من أنّ أقسام التحميل لا تحتوي على قيم أقل من 2**14. إذا كانت أي أقسام تحميل هي 2**13 أو 2**12 أو قيم أقل ، عليك تعديل عملية التغليف لهذه المكتبات، ثم إعادة تجميع تطبيقك وإعادة اختباره باتّباع الخطوات الواردة في هذا القسم.

5. بعد ذلك، شغِّل أداة سطر الأوامر zipalign على ملف APK الخاص بتطبيقك:

   Linux أو macOS

   SDK_ROOT_LOCATION/Android/sdk/build-tools/35.0.0/zipalign -v -c -P 16 4 APK_NAME.apk
   

   نظام التشغيل Windows (PowerShell)

   SDK_ROOT_LOCATION\Android\sdk\build-tools\35.0.0\zipalign.exe -v -c -P 16 4 APK_NAME.apk
   

   حيث SDK_ROOT_LOCATION هو المسار إلى الدليل الذي ثبَّت فيه حزمة Android SDK، وAPK_NAME هو اسم ملف APK الخاص بتطبيقك. سيظهر في السطر الأخير من النتائج "تم التحقّق بنجاح" إذا كانت جميع المكتبات المشترَكة تتم محاذاتها بشكل صحيح.

   إذا تعذّر التحقّق، يجب إعادة محاذاة بعض المكتبات المشترَكة، لذا عليك تعديل عملية التغليف لهذه المكتبات، ثم إعادة تجميع تطبيقك وإعادة اختباره باتّباع الخطوات الواردة في هذا القسم.

التحقّق من علامة الأمان RELRO

للتخفيف من الثغرات الأمنية، تستخدم أدوات الربط الحديثة علامة Relocation Read-Only (RELRO) لجعل أقسام النقل في ملف الكائن المشترَك للقراءة فقط بعد التحميل. يؤدي الجمع بين قسم مفعَّل فيه RELRO وقسم غير مفعَّل فيه RELRO (من ملف كائن آخر) على الصفحة نفسها إلى تعطُّل التطبيق.

شغِّل الأمر التالي على كل ملف كائن مشترَك (على نظام التشغيل Linux أو macOS):

SDK_ROOT_LOCATION/Android/sdk/ndk/NDK_VERSION/toolchains/llvm/prebuilt/darwin-x86_64/bin/llvm-readelf -l SHARED_OBJECT_FILE.so | grep RELRO

تحقَّق من نتائج الأمر للتأكّد من طباعة السلسلة GNU_RELRO، ما يؤكّد أنّ ملف .so مفعَّل فيه RELRO.

ملاحظة: عليك إجراء هذا الاختبار لجميع ملفات .so في حزمة APK.

إنشاء تطبيقك ليتوافق مع الأجهزة التي تستخدم صفحات الذاكرة بحجم 16 كيلوبايت

إذا كان تطبيقك يستخدم رمزًا برمجية أصلية، فأكمِل الخطوات الموضّحة في الأقسام التالية للتأكّد من أنّ تطبيقك متوافق مع الأجهزة التي تستخدم صفحات الذاكرة بحجم 16 كيلوبايت:

1. تعديل عملية التغليف للمكتبات المشترَكة
2. تجميع تطبيقك باستخدام محاذاة ELF بحجم 16 كيلوبايت
3. إصلاح الرمز البرمجي وحلّ مشاكل وقت التشغيل
4. التحقّق من حزم SDK لمعرفة ما إذا كانت متوافقة مع صفحة الذاكرة بحجم 16 كيلوبايت

ملاحظة: إذا رقّيت أدواتك إلى أحدث الإصدارات (الإصدار 8.5.1 أو إصدار أحدث من "المكوّن الإضافي لنظام Gradle المتوافق مع Android" والإصدار r28 أو إصدار أحدث من NDK) واستخدمت تبعيات تم إنشاؤها مسبقًا ومتوافقة مع صفحة الذاكرة بحجم 16 كيلوبايت، سيكون تطبيقك متوافقًا مع صفحة الذاكرة بحجم 16 كيلوبايت تلقائيًا ويمكنك الانتقال إلى خطوة إصلاح الرمز البرمجي وحلّ مشاكل وقت التشغيل.

تعديل عملية التغليف للمكتبات المشترَكة

رقِّ إلى الإصدار 8.5.1 أو إصدار أحدث من "المكوّن الإضافي لنظام Gradle المتوافق مع Android" واستخدِم مكتبات مشترَكة غير مضغوطة.

استخدام bundletool للتحقّق من محاذاة ملف ZIP

لمعرفة محاذاة حزمتك، استخدِم:

bundletool dump config --bundle=<my .aab>  | grep alignment

إذا ظهرت لك PAGE_ALIGNMENT_16K، فهذا يعني أنّ حزمتك تطلب محاذاة ملف ZIP بحجم 16 كيلوبايت. إذا ظهرت لك PAGE_ALIGNMENT_4K، فهذا يطلب من حزمة APK التي تم إنشاؤها من حزمة AAB هذه أن تحتوي على ملفات ` .so` تتم محاذاتها بحجم 4 كيلوبايت في ملف ZIP.

الإصدار 8.5.1 أو إصدار أحدث من "المكوّن الإضافي لنظام Gradle المتوافق مع Android"

تتطلب الأجهزة التي تستخدم صفحات الذاكرة بحجم 16 كيلوبايت أن تتم محاذاة التطبيقات التي تتضمّن مكتبات مشترَكة غير مضغوطة على حدّ تتم محاذاته بحجم 16 كيلوبايت في ملف ZIP. لإجراء ذلك، عليك الترقية إلى الإصدار 8.5.1 أو إصدار أحدث من "المكوّن الإضافي لنظام Gradle المتوافق مع Android". يُرجى الرجوع إلى قسم "مساعد ترقية المكوّن الإضافي لنظام Gradle المتوافق مع Android" للحصول على تفاصيل عن عملية الترقية.

الإصدار 8.5 أو إصدار أقدم من "المكوّن الإضافي لنظام Gradle المتوافق مع Android"

ملاحظة: في الإصدارات من 8.3 إلى 8.5 من "المكوّن الإضافي لنظام Gradle المتوافق مع Android"، تتم محاذاة التطبيقات بشكل يتوافق مع صفحة الذاكرة بحجم 16 كيلوبايت تلقائيًا. ومع ذلك، لا تقوم أداة bundletool بمحاذاة ملفات APK باستخدام zipalign تلقائيًا. لذا، قد يبدو أنّ التطبيق يعمل، ولكن عند إنشائه من حزمة في Play، لن يتم تثبيته.

إذا تعذّر عليك ترقية "المكوّن الإضافي لنظام Gradle المتوافق مع Android" إلى الإصدار 8.5.1 أو إصدار أحدث، فالبديل هو التبديل إلى استخدام مكتبات مشترَكة مضغوطة. عدِّل إعدادات Gradle لكي يضغط Gradle مكتباتك المشترَكة عند تغليف تطبيقك لتجنُّب مشاكل تثبيت التطبيق مع المكتبات المشترَكة غير المحاذية.

أنيق

في ملف build.gradle، أضِف الخيار التالي:

android {
  ...
  packagingOptions {
      jniLibs {
        useLegacyPackaging true
      }
  }
}

Kotlin

في ملف build.gradle.kts، أضِف الخيار التالي:

android {
  ...
  packagingOptions {
      jniLibs {
        useLegacyPackaging = true
      }
  }
}

الإصدار 8.0 أو إصدار أقدم من "المكوّن الإضافي لنظام Gradle المتوافق مع Android"

إذا كنت تستخدم إصدارًا من "المكوّن الإضافي لنظام Gradle المتوافق مع Android" هو الإصدار 8.0 أو إصدار أقدم، عليك أيضًا إيقاف خيار المكتبة المجمّعة من رموز برمجية أصلية غير المضغوطة لحزم التطبيقات في ملف gradle.properties:

android.bundle.enableUncompressedNativeLibs=false

تحذير: عند استخدام مكتبات مشترَكة مضغوطة، يشغل تطبيقك مساحة أكبر عند تثبيته، لأنّه يتم استخراج المكتبات من حزمة APK ونسخها على القرص. قد يتعذّر تثبيت تطبيقك بشكل متكرّر أكثر لأنّ هذه الزيادة في استخدام مساحة القرص تعني أنّ المساحة المتبقية على الجهاز أقل. لتجنُّب ذلك، رقِّ إلى الإصدار 8.5.1 أو إصدار أحدث من "المكوّن الإضافي لنظام Gradle المتوافق مع Android".

تجميع تطبيقك باستخدام محاذاة ELF بحجم 16 كيلوبايت

تتطلب الأجهزة التي تستخدم صفحات الذاكرة بحجم 16 كيلوبايت أن تتم محاذاة أقسام ELF للمكتبات المشترَكة بشكل صحيح باستخدام محاذاة ELF بحجم 16 كيلوبايت لكي يتم تشغيل تطبيقك.

بالنسبة إلى مطوّري الألعاب، إذا كانت لعبتك تعمل على محرّك ألعاب Unity، يُرجى الرجوع إلى دليل Unity. إذا كانت لعبتك تعمل على محرّك ألعاب Unreal، يُرجى الرجوع إلى دليل Unreal. بالنسبة إلى محرّكات الألعاب الأصلية، تابِع هذا الدليل.

ملاحظة: إذا كان تطبيقك لا يستخرج المكتبات المجمّعة من رموز برمجية أصلية إلى نظام الملفات (extractNativeLibs تم ضبطه على false)، فمن المحتمل أن تلاحظ زيادة طفيفة في حجم البرنامج الثنائي لتطبيقك بعد التجميع باستخدام محاذاة ELF بحجم 16 كيلوبايت. تُبطل التحسينات التي تم إجراؤها على مدير الحزم في Android 15 تكاليف وقت التشغيل الناتجة عن هذه الزيادة.

لتجميع تطبيقك باستخدام محاذاة ELF بحجم 16 كيلوبايت، أكمِل الخطوات الواردة في أحد الأقسام التالية استنادًا إلى إصدار Android NDK الذي تستخدمه.

**ملاحظة مهمة:** إذا كان تطبيقك يستخدم أي مكتبات مشترَكة تم إنشاؤها مسبقًا، عليك أيضًا إعادة تجميعها بالطريقة نفسها وإعادة استيراد المكتبات التي تمت محاذاتها بحجم 16 كيلوبايت إلى تطبيقك.

الإصدار r28 والإصدارات الأحدث من Android NDK

يُجمِّع الإصدار r28 والإصدارات الأحدث من NDK المكتبات التي تمت محاذاتها بحجم 16 كيلوبايت تلقائيًا.

الإصدار r27 والإصدارات الأقدم من Android NDK

لتوفير إمكانية تجميع المكتبات المشترَكة التي تمت محاذاتها بحجم 16 كيلوبايت باستخدام الإصدار r27 أو إصدار أقدم من Android NDK، استخدِم علامات الرابط التالية:

-Wl,-z,max-page-size=16384
-Wl,-z,common-page-size=16384

في ما يلي كيفية تعديل ملفات إعداد نظام التصميم:

ndk-build

إذا كنت تستخدم ndk-build، عدِّل ملف Android.mk لتفعيل محاذاة ELF بحجم 16 كيلوبايت:

LOCAL_LDFLAGS += -Wl,-z,max-page-size=16384 -Wl,-z,common-page-size=16384

CMake

إذا كنت تستخدم CMake، عدِّل ملف CMakeLists.txt لتفعيل محاذاة ELF بحجم 16 كيلوبايت:

target_link_options(${CMAKE_PROJECT_NAME} PRIVATE
    "-Wl,-z,max-page-size=16384"
    "-Wl,-z,common-page-size=16384"
)

ملاحظة: حتى إذا كان تطبيقك يرتبط ديناميكيًا بالمكتبة العادية للغة C++ (libc++_shared.so) من الإصدار r26 والإصدارات الأقدم من NDK، والتي لا يتضمّن بعضها 16 كيلوبايت تمت محاذاته بحجم libc++_shared.so، عليك مع ذلك تعديل المحاذاة لجميع المكتبات الأخرى هنا، وعليك تعديل الرمز البرمجي لتجنُّب الاعتماد على PAGE_SIZE. لاختبار هذه الإصدارات الأقدم من NDK على الأجهزة التي تستخدم صفحات الذاكرة بحجم 16 كيلوبايت، تتوفّر إصدارات Canary من الإصدارَين r23 وr25 من إصدارات NDK ذات الدعم الطويل الأمد (LTS) على Android CI مع مكتبات تمت محاذاتها بحجم 16 كيلوبايت.libc++_shared.so

ملاحظة: إذا تعذّر عليك الانتقال إلى الإصدار الأحدث من Android NDK، قد تتمكّن من تعديل تطبيقك لتجميع المكتبة العادية للغة C++ بشكل ثابت في مكتبتك المشترَكة. يُرجى الرجوع إلى قسم "دعم مكتبة C++" للحصول على تفاصيل عن الربط الثابت بالمكتبة العادية للغة C++، وعليك قراءة قسم "اعتبارات مهمة".

إصلاح الرمز البرمجي وحلّ مشاكل وقت التشغيل

حتى إذا تمت محاذاة تطبيقك بشكل يتوافق مع صفحة الذاكرة بحجم 16 كيلوبايت، يمكن أن يواجه التطبيق أخطاء إذا كانت مواضع في الرمز البرمجي تفترض أنّ الجهاز يستخدم حجم صفحة معيّنًا. لتجنُّب ذلك، أكمِل الخطوات التالية:

1. أزِل أي تبعيات مبرمَجة بشكل ثابت تشير إلى الث0}PAGE_SIZE ثابت أو أي حالات في منطق الرمز البرمجي تفترض أنّ حجم صفحة الجهاز هو 4 كيلوبايت (4096).

   استخدِم getpagesize() أو sysconf(_SC_PAGESIZE) بدلاً من ذلك.

2. ابحث عن استخدامات mmap() وواجهات برمجة التطبيقات الأخرى التي تتطلب وسيطات تتم محاذاتها على مستوى الصفحة واستبدِلها ببدائل عند الضرورة.

في بعض الحالات، إذا كان تطبيقك يستخدم PAGE_SIZE كقيمة مناسبة غير مرتبطة بحجم الصفحة الأساسي، فلن يؤدي ذلك إلى تعطُّل تطبيقك عند استخدامه في وضع 16 كيلوبايت. ومع ذلك، إذا تم تمرير هذه القيمة إلى النواة باستخدام mmap بدون MAP_FIXED، ستظل النواة تستخدم صفحة كاملة، ما يؤدي إلى إهدار بعض الذاكرة. لهذه الأسباب، تكون PAGE_SIZE غير محدّدة عند تفعيل وضع 16 كيلوبايت على الإصدار r27 والإصدارات الأحدث من NDK.

إذا كان تطبيقك يستخدم PAGE_SIZE بهذه الطريقة ولا يمرِّر هذه القيمة مباشرةً إلى النواة، فبدلاً من استخدام PAGE_SIZE، أنشئ متغيّرًا جديدًا باسم جديد للإشارة إلى أنّه يُستخدم لأغراض أخرى ولا يعكس صفحة ذاكرة حقيقية.

التحقّق من حزم SDK لمعرفة ما إذا كانت متوافقة مع صفحة الذاكرة بحجم 16 كيلوبايت

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

اختبار تطبيقك في بيئة تتضمن صفحات ذاكرة بحجم 16 كيلوبايت

بعد إنشاء تطبيقك ليتوافق مع الأجهزة التي تستخدم صفحات الذاكرة بحجم 16 كيلوبايت، عليك اختباره في بيئة تتضمن صفحات ذاكرة بحجم 16 كيلوبايت لمعرفة ما إذا كان تطبيقك يواجه أي مشاكل. لإجراء هذا، اتبع هذه الخطوات:

1. إعداد حزمة Android 15 SDK أو إصدار أحدث

2. إعداد إحدى بيئات الاختبار التالية:

   • إعداد Android Emulator باستخدام صورة نظام Android 15 تستند إلى 16 كيلوبايت
     • استخدام Cuttlefish مع حجم صفحة 16 كيلوبايت على ARM64
   • محاكاة Cuttlefish مع حجم صفحة 16 كيلوبايت على x86-64
   • تفعيل وضع 16 كيلوبايت على جهاز باستخدام خيارات المطوّرين
   • استخدام Samsung Remote Test Lab على الأجهزة المتوافقة مع صفحة الذاكرة بحجم 16 كيلوبايت

3. ابدأ تشغيل جهاز الاختبار، ثم شغِّل الأمر التالي للتأكّد من أنّه يستخدم بيئة تتضمن صفحات ذاكرة بحجم 16 كيلوبايت:

   adb shell getconf PAGE_SIZE
   

   يجب أن يعرض الأمر القيمة 16384.

4. شغِّل أمر zipalign التالي للتأكّد من أنّ تطبيقك تمت محاذاته بشكل يتوافق مع صفحة الذاكرة بحجم 16 كيلوبايت، حيث APK_NAME هو اسم ملف APK الخاص بتطبيقك:

   zipalign -c -P 16 -v 4 APK_NAME.apk
   

5. اختبِر تطبيقك بدقة، مع التركيز على أي مناطق قد تتأثر ب تغيير حالات الرمز البرمجي التي تشير إلى أحجام صفحات معيّنة.

إعداد Android Emulator باستخدام صورة نظام تستند إلى 16 كيلوبايت

لإعداد بيئة تتضمن صفحات ذاكرة بحجم 16 كيلوبايت باستخدام Android Emulator، اتّبِع الخطوات التالية:

1. في "استوديو Android"، انقر على الأدوات > SDK Manager.

2. في علامة التبويب SDK Platforms ، ضَع علامة في المربّع Show Package Details، ثم وسِّع قسم Android VanillaIceCream أو إصدار أحدث واختَر إحدى صور نظام المحاكي أو كلتيهما، استنادًا إلى الأجهزة الافتراضية التي تريد إنشاءها:

   • Google APIs Experimental 16 KB Page Size ARM 64 v8a System Image
   • Google APIs Experimental 16 KB Page Size Intel x86_64 Atom System Image
   ملاحظة: إذا كنت تخطط لـ محاكاة جهاز Google Pixel متوافق، فلن تحتاج إلا إلى صورة نظام ARM 64 v8a.

   

3. انقر على تطبيق > حسنًا لتنزيل أي صور نظام اخترتها.

4. اتّبِع خطوات إعداد جهاز افتراضي لنظام Android 15، وعندما يُطلب منك اختيار صورة نظام، اختَر صورة نظام 16 كيلوبايت التي نزّلتها. إذا لم يتم اقتراحها تلقائيًا، يمكنك العثور على صورة نظام 16 كيلوبايت في علامة التبويب صور أخرى.

   

تشغيل المحاكي

بعد الانتهاء من إعداد Android Emulator والأجهزة الافتراضية، شغِّل المحاكي من قائمة الجهاز المستهدَف، أو من سطر الأوامر.

تفعيل الوضع 16 كيلوبايت على جهاز باستخدام خيارات المطوّرين

فعِّل خيار المطوّر التشغيل مع صفحات حجمها 16 كيلوبايت لتشغيل الجهاز في وضع 16 كيلوبايت.

في إصدارات QPR من نظام التشغيل Android 15، يمكنك استخدام خيار المطوّرين المتاح على أجهزة معيّنة لإعادة تشغيل الجهاز في وضع 16 كيلوبايت وإجراء اختبار على الجهاز فقط. قبل استخدام خيار المطوّرين، انتقِل إلى الإعدادات > النظام > تحديثات البرامج وطبِّق أي تحديثات متوفّرة.

يتوفّر خيار المطوّرين هذا على الأجهزة التالية:

• ‫Pixel 8 وPixel 8 Pro (مع الإصدار 1 من حزمة إصلاح الأخطاء في نظام Android 15 أو إصدار أحدث)

• ‫Pixel 8a (مع الإصدار 1 من حزمة إصلاح الأخطاء في نظام Android 15 أو إصدار أحدث)

• ‫Pixel 9 و‎9 Pro و‎9 Pro XL (مع الإصدار الثاني من حزمة Android 15 QPR أو إصدار أحدث)

• ‫Pixel 9a (مع نظام التشغيل Android 16 أو إصدار أحدث)

وضع التوافق مع الإصدارات السابقة بحجم 16 كيلوبايت

تحذير في وضع التوافق مع حجم الصفحة

يتوفّر خيار التوافق مع الإصدارات السابقة بحجم 16 كيلوبايت عندما يعمل الجهاز بنواة 16 كيلوبايت. يشغِّل مدير الحزم تطبيقًا في وضع التوافق مع الإصدارات السابقة بحجم 16 كيلوبايت عند استيفاء الشروط التالية:

• إذا كان التطبيق يحتوي على ملفات ELF (بالامتداد .so) مع محاذاة قسم LOAD بحجم 4 كيلوبايت.
• إذا كانت حزمة APK المضغوطة تحتوي على ملفات ELF غير مضغوطة تتم محاذاتها بحجم 4 كيلوبايت في ملف ZIP.

إذا فعَّل مدير الحزم وضع التوافق مع الإصدارات السابقة بحجم 16 كيلوبايت لتطبيق، يعرض التطبيق تحذيرًا عند تشغيله لأول مرة يشير إلى أنّه يعمل في وضع التوافق مع الإصدارات السابقة بحجم 16 كيلوبايت.

يسمح وضع التوافق مع الإصدارات السابقة بحجم 16 كيلوبايت لبعض التطبيقات بالعمل، ولكن للحصول على أفضل موثوقية واستقرار، يجب أن تتم محاذاة التطبيقات بشكل يتوافق مع صفحة الذاكرة بحجم 16 كيلوبايت.

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

إعداد وضع التوافق مع حجم الصفحة

لفرض تفعيل وضع التوافق مع الإصدارات السابقة بحجم 16 كيلوبايت لكل تطبيق على الجهاز:

adb shell setprop bionic.linker.16kb.app_compat.enabled true
adb shell setprop pm.16kb.app_compat.disabled false

لفرض إيقاف وضع التوافق مع الإصدارات السابقة بحجم 16 كيلوبايت لكل تطبيق على الجهاز:

adb shell setprop bionic.linker.16kb.app_compat.enabled false
adb shell setprop pm.16kb.app_compat.disabled true

في Android 17، يمكنك أيضًا فرض إيقاف وضع التوافق مع الإصدارات السابقة بحجم 16 كيلوبايت لكل تطبيق والتسبب في إيقاف أي ملف ثنائي غير متوافق على الفور:

    adb shell setprop bionic.linker.16kb.app_compat.enabled fatal
    adb shell setprop pm.16kb.app_compat.disabled true

اضبط السمة android:pageSizeCompat على مفعَّلة أو غير مفعَّلة لتفعيل وضع التوافق مع الإصدارات السابقة أو إيقافه لتطبيق معيّن في ملف AndroidManifest.xml. عند ضبط هذه السمة، لن يعرض التطبيق تحذيرات وضع التوافق مع الإصدارات السابقة عند تشغيله.