يحتوي نظام Android الأساسي على عدد كبير من مكتبات Java المشتركة
التي يمكن تضمينها اختياريًا في مسار فئة التطبيقات باستخدام
علامة <uses-library>
في بيان التطبيق. رابط التطبيقات
مقابل هذه المكتبات، لذا تعامل معها كباقي واجهة برمجة تطبيقات Android
من حيث التوافق ومراجعة واجهة برمجة التطبيقات ودعم الأدوات. ومع ذلك، لاحظ أنه
أن معظم المكتبات لا تتضمن هذه الميزات.
يساعد نوع الوحدة java_sdk_library
في إدارة المكتبات.
من هذا النوع. يمكن للشركات المصنّعة للأجهزة استخدام هذه الآلية بأنفسهم
مكتبات Java المشتركة، للحفاظ على التوافق مع الأنظمة القديمة لواجهات برمجة التطبيقات الخاصة بها.
إذا كانت الشركات المصنّعة للأجهزة تستخدم مكتبات Java المشتركة الخاصة بها من خلال
<uses-library>
بدلاً من مسار فئة التشغيل،
بإمكان java_sdk_library
التحقق من أن مكتبات Java هذه
واجهة برمجة تطبيقات ثابتة.
تنفِّذ java_sdk_library
واجهات برمجة تطبيقات اختيارية لحزمة تطوير البرامج (SDK) لاستخدامها من خلال
التطبيقات. المكتبات التي تم تنفيذها من خلال java_sdk_library
في
ملف الإصدار (Android.bp
) بتنفيذ العمليات التالية:
- يتم إنشاء مكتبات الرموز الموجزة لتضمين
stubs
،stubs.system
وstubs.test
هذه عن طريق التعرّف على@hide
، تعليقات@SystemApi
و@TestApi
التوضيحية - يدير
java_sdk_library
ملفات مواصفات واجهة برمجة التطبيقات (مثلcurrent.txt
) في دليل فرعي لواجهة برمجة التطبيقات. هذه الملفات يتم التحقق منها مقابل أحدث رمز للتأكد من أنها الأكثر والإصدارات الحالية. إذا لم تكن كذلك، ستتلقّى رسالة خطأ تفيد ويشرح كيفية تحديثها. مراجعة جميع تغييرات التحديث يدويًا والتأكد من أنها تتوافق مع توقعاتك.
لتحديث جميع واجهات برمجة التطبيقات، استخدِمm update-api
. للتأكّد من أنّ واجهة برمجة التطبيقات محدَّثة، استخدامm checkapi
. - يتم التحقّق من ملفات مواصفات واجهة برمجة التطبيقات بأحدث بيانات
إصدارات Android المنشورة لضمان توافق واجهة برمجة التطبيقات مع الأنظمة القديمة
مع الإصدارات السابقة. تم توفير
java_sdk_library
وحدة. كجزء من AOSP وضع إصداراتهم التي تم إصدارها سابقًا فيprebuilts/sdk/<latest number>
- وفي ما يتعلق بعمليات التحقق من ملفات مواصفات واجهة برمجة التطبيقات، يمكنك إجراء أحد العناصر الثلاثة التالية:
- اسمح بمواصلة عمليات التحقّق. (لا تفعل أي شيء).
- يمكنك إيقاف عمليات التحقق من خلال إضافة ما يلي إلى
java_sdk_library
:
unsafe_ignore_missing_latest_api: true,
- توفير واجهات برمجة تطبيقات فارغة لوحدات
java_sdk_library
الجديدة عن طريق إنشاء ملفات نصية فارغة باسمmodule_name.txt
في دليلversion/scope/api
. - إذا تم تثبيت مكتبة التنفيذ الخاصة ببيئة التشغيل، يتم استخدام ملف XML يتم إنشاؤه وتثبيته.
طريقة عمل java_sdk_library
عنصر java_sdk_library
يسمى X
ينشئ ما يلي:
- نسختان من مكتبة التنفيذ: مكتبة باسم
X
والآخر يسمىX.impl
. تم تثبيت المكتبةX
على الجهاز فقط. تتوفر المكتبةX.impl
فقط في حالة الوصول الصريح إلى مكتبة التنفيذ مطلوبة من قِبل وحدات أخرى، مثل استخدامها في اختبار الفرضية. يُرجى العِلم أنّه نادرًا ما تكون هناك حاجة إلى إذن الوصول الصريح. - يمكن تفعيل النطاقات وإيقافها لتخصيص الوصول. (مماثل لـ Java معدِّلات الوصول إلى الكلمات الرئيسية، فإن النطاق العام يوفر نطاقًا كبيرًا من الوصول؛ CANNOT TRANSLATE يحتوي نطاق الاختبار على واجهات برمجة تطبيقات لا تُستخدم إلا في الاختبار). لكل نطاق مفعَّل ما يلي:
- تستهلك وحدة مصدر التشعّبات (من نوع وحدة
droidstubs
) مصدر التنفيذ، وتُخرج مجموعة من المصادر البديلة إلى جانب ملف مواصفات واجهة برمجة التطبيقات. - مكتبة الأكواد (من نوع وحدة
java_library
) - هي نسخة مجمعة من التنويهات. المكتبات المستخدمة لتجميع هذه ليست هي البيانات نفسها المقدّمة إلىjava_sdk_library
، ما يضمن عدم تسرب تفاصيل التنفيذ إلى حقول واجهة برمجة التطبيقات. - إذا كنت بحاجة إلى مكتبات إضافية لتجميع التنويهات الموجزة، فاستخدم
stub_only_libs
وstub_only_static_libs
الخصائص لعرضها.
إذا كان اسم java_sdk_library
يسمّى "X
"
مجمعة مقابل "X
"، فاشير إليها دائمًا بهذه الطريقة ولا تعدل
بها. سيختار الإصدار مكتبة مناسبة. للتأكد من حصولك على
المكتبة الأنسب لك، وافحص بذور النصوص البرمجية لمعرفة ما إذا كان الإصدار قد تم
الأخطاء. عليك إجراء أي تصحيحات ضرورية باستخدام هذه الإرشادات:
- تحقق من وجود مكتبة مناسبة من خلال البحث في سطر الأوامر وفحص البذور المدرجة هناك لتحديد نطاقك:
- النطاق واسع جدًا: تحتاج المكتبة استنادًا إلى نطاق معين من واجهات برمجة التطبيقات. لَكِنْ ترى واجهات برمجة التطبيقات المضمنة في المكتبة التي تقع خارج هذا النطاق، مثل واجهات برمجة تطبيقات النظام المضمّنة في واجهات برمجة التطبيقات العامة.
- النطاق ضيّق جدًا: لا يمكن للمكتبة التي تعتمد على هذا الوصول إلى جميع المكتبات المطلوبة. على سبيل المثال، تحتاج المكتبة بناءً على ذلك إلى استخدام ولكن تحصل على واجهة برمجة التطبيقات العامة بدلاً من ذلك. يؤدي هذا عادةً إلى حدث خطأ في التحويل البرمجي بسبب عدم توفر واجهات برمجة التطبيقات المطلوبة.
- لإصلاح المكتبة، نفِّذ واحدًا فقط من الإجراءات التالية:
- ويجب تغيير "
sdk_version
" لاختيار الإصدار المطلوب. أو - تحديد المكتبة المناسبة بوضوح، مثل
<X>.stubs
أو<X>.stubs.system
.
استخدام java_sdk_library X
يتم استخدام مكتبة التنفيذ X
عند الإشارة إليها من
apex.java_libs
ومع ذلك، ونظرًا لقيود "سونغ"،
عندما لا تكون المكتبة
تتم الإشارة إلى X
من وحدة java_sdk_library
أخرى.
ضمن مكتبة APEX نفسها، X.impl
بشكل صريح
يجب استخدامه، وليس المكتبة X
.
عند الإشارة إلى java_sdk_library
من مكان آخر، يتم استخدام رمز بديل
استخدام المكتبة. يتم اختيار مكتبة التنويهات الموجزة وفقًا
إعداد خاصية sdk_version
للوحدة. على سبيل المثال، الوحدة التي
يحدد sdk_version: "current"
يستخدم التنويهات العامة، في حين أن
التي تحدد sdk_version: "system_current"
تستخدم
الأجزاء الناقصة للنظام. إذا تعذر العثور على تطابق تام، يتم الحصول على أقرب مكتبة بدائل
استخدام البيانات المختلفة. إنّ java_sdk_library
الذي يوفّر واجهة برمجة تطبيقات عامة فقط
وتوفير التصاريح العامة للجميع.
![إنشاء التدفق باستخدام مكتبة Java SDK](https://source.android.com/static/docs/core/architecture/images/build-flow-java-lib.png?authuser=6&hl=ar)
الأمثلة والمصادر
يجب السمتَين srcs
وapi_packages
.
المشاركة في "java_sdk_library
"
java_sdk_library { name: "com.android.future.usb.accessory", srcs: ["src/**/*.java"], api_packages: ["com.android.future.usb"], }
تقترح "الشريك المعتمد من Google للناشرين" (AOSP) استخدام "java_sdk_library
" الجديد، بدون الحاجة إلى ذلك
على تفعيل نطاقات واجهة برمجة التطبيقات التي يريدون استخدامها. يمكنك أيضًا
(اختياريًا) نقل مثيلات java_sdk_library
الحالية إلى
تفعيل نطاقات واجهة برمجة التطبيقات التي سيستخدمونها بشكل صريح:
java_sdk_library { name: "lib", public: { enabled: true, }, system: { enabled: true, }, … }
لضبط مكتبة impl
المُستخدَمة لبيئة التشغيل، استخدِم الكل
سمات java_library
العادية، مثل hostdex
،
compile_dex
، وerrorprone
.
java_sdk_library { name: "android.test.base", srcs: ["src/**/*.java"], errorprone: { javacflags: ["-Xep:DepAnn:ERROR"], }, hostdex: true, api_packages: [ "android.test", "android.test.suitebuilder.annotation", "com.android.internal.util", "junit.framework", ], compile_dex: true, }
لإعداد مكتبات التنويهات الموجزة، استخدِم السمات التالية:
merge_annotations_dirs
وmerge_inclusion_annotations_dirs
api_srcs
: قائمة بملفات المصدر الاختيارية التي تكون جزءًا من واجهة برمجة التطبيقات ولكن ليس جزءًا من مكتبة بيئة التشغيل.stubs_only_libs
: قائمة مكتبات Java الموجودة في مسار الفئات عند إنشاء البُنى الأساسية.hidden_api_packages
: قائمة بأسماء الحِزم التي يجب أن تكون مخفي من واجهة برمجة التطبيقات.droiddoc_options
: وسيطة إضافية لـ ميتلافاdroiddoc_option_files
: يسرد الملفات التي يمكن الإشارة إليها من داخلdroiddoc_options
باستخدام$(location <label>)
، حيث<file>
هو إدخال في القائمة.annotations_enabled
.
java_sdk_library
هو java_library
، ولكنه ليس
وحدة droidstubs
وبالتالي لا تتوافق مع جميع وحدات droidstubs
المواقع. المثال التالي مأخوذ من
إصدار مكتبة android.test.mock
الملف.
java_sdk_library { name: "android.test.mock", srcs: [":android-test-mock-sources"], api_srcs: [ // Note: The following aren’t APIs of this library. Only APIs under the // android.test.mock package are taken. These do provide private APIs // to which android.test.mock APIs reference. These classes are present // in source code form to access necessary comments that disappear when // the classes are compiled into a Jar library. ":framework-core-sources-for-test-mock", ":framework_native_aidl", ], libs: [ "framework", "framework-annotations-lib", "app-compat-annotations", "Unsupportedappusage", ], api_packages: [ "android.test.mock", ], permitted_packages: [ "android.test.mock", ], compile_dex: true, default_to_stubs: true, }
الحفاظ على التوافق مع الأنظمة القديمة
يتحقّق نظام الإصدار مما إذا كانت واجهات برمجة التطبيقات قد حافظت على الإصدارات القديمة.
من خلال مقارنة أحدث ملفات واجهة برمجة التطبيقات مع الملفات التي تم إنشاؤها،
ملفات واجهة برمجة التطبيقات في وقت الإصدار. ينفذ java_sdk_library
التحقّق من التوافق باستخدام المعلومات المقدَّمة من prebuilt_apis
.
يجب أن تحتوي جميع المكتبات التي تم إنشاؤها باستخدام java_sdk_library
على ملفات واجهة برمجة التطبيقات.
في أحدث إصدار من api_dirs
في prebuilt_apis
.
عند طرح الإصدار، تُدرج واجهة برمجة التطبيقات الملفات والرموز البديلة.
يمكن الحصول على المكتبات باستخدام إصدار Dist باستخدام PRODUCT=sdk_phone_armv7-sdk
.
السمة api_dirs
هي قائمة بأدلة إصدارات واجهة برمجة التطبيقات.
في prebuilt_apis
. يجب أن تكون أدلة إصدار واجهة برمجة التطبيقات
على مستوى دليل Android.bp
.
prebuilt_apis { name: "foo", api_dirs: [ "1", "2", .... "30", "current", ], }
إعداد الأدلة باستخدام version/scope/api/
ضمن الدليل المُنشأ مسبقًا. version
مع مستوى واجهة برمجة التطبيقات ويحدد scope
سواء كان الدليل عامًا أو نظامًا أو اختبارًا.
version/scope
يحتوي على مكتبات Java.- يحتوي
version/scope/api
على واجهة برمجة تطبيقات.txt
ملفًا. إنشاء ملفات نصية فارغة باسمmodule_name.txt
وmodule_name-removed.txt
هنا.├── 30 │ ├── public │ │ ├── api │ │ │ ├── android.test.mock-removed.txt │ │ │ └── android.test.mock.txt │ │ └── android.test.mock.jar │ ├── system │ │ ├── api │ │ │ ├── android.test.mock-removed.txt │ │ │ └── android.test.mock.txt │ │ └── android.test.mock.jar │ └── test │ ├── api │ │ ├── android.test.mock-removed.txt │ │ └── android.test.mock.txt │ └── android.test.mock.jar └── Android.bp