Platform Android berisi sejumlah besar library Java bersama yang secara opsional dapat disertakan dalam classpath aplikasi dengan <uses-library>
dalam manifes aplikasi. Aplikasi tertaut ke pustaka ini, jadi perlakukan mereka seperti API Android lainnya dalam hal kompatibilitas, tinjauan API, dan dukungan alat. Namun, perhatikan bahwa sebagian besar perpustakaan tidak memiliki fitur ini.
Jenis modul java_sdk_library
membantu mengelola perpustakaan semacam ini. Produsen perangkat dapat menggunakan mekanisme ini untuk perpustakaan Java bersama mereka sendiri, untuk mempertahankan kompatibilitas mundur untuk API mereka. Jika produsen perangkat menggunakan pustaka Java bersama mereka sendiri melalui <uses-library>
alih-alih jalur bootclass, java_sdk_library
dapat memverifikasi bahwa pustaka Java tersebut adalah API-stabil.
java_sdk_library
mengimplementasikan API SDK opsional untuk digunakan oleh aplikasi. Library yang diimplementasikan melalui java_sdk_library
di file build Anda ( Android.bp
) melakukan operasi berikut:
- Pustaka stub dibuat untuk menyertakan
stubs
,stubs.system
, danstubs.test
. Pustaka rintisan ini dibuat dengan mengenali@hide
,@SystemApi
, dan@TestApi
. -
java_sdk_library
mengelola file spesifikasi API (seperticurrent.txt
) di subdirektori API. File-file ini diperiksa dengan kode terbaru untuk memastikan bahwa itu adalah versi terbaru. Jika tidak, Anda menerima pesan galat yang menjelaskan cara memperbaruinya. Tinjau semua perubahan pembaruan secara manual untuk memastikan bahwa perubahan tersebut sesuai dengan harapan Anda.
Untuk memperbarui semua API, gunakanm update-api
. Untuk memverifikasi bahwa API terbaru, gunakanm checkapi
. - File spesifikasi API diperiksa terhadap versi Android terbaru yang diterbitkan untuk memastikan bahwa API kompatibel dengan rilis sebelumnya. Modul
java_sdk_library
yang disediakan sebagai bagian dari AOSP menempatkan versi yang dirilis sebelumnya diprebuilts/sdk/<latest number>
. - Sehubungan dengan pemeriksaan file spesifikasi API, Anda dapat melakukan salah satu dari tiga hal berikut:
- Izinkan pemeriksaan untuk melanjutkan. (Jangan lakukan apapun.)
- Nonaktifkan pemeriksaan dengan menambahkan yang berikut ini ke
java_sdk_library
:
unsafe_ignore_missing_latest_api: true,
- Sediakan API kosong untuk modul
java_sdk_library
baru dengan membuat file teks kosong bernamamodule_name.txt
di direktoriversion/scope/api
. - Jika pustaka implementasi untuk waktu proses diinstal, file XML akan dibuat dan diinstal.
Cara kerja java_sdk_library
java_sdk_library
bernama X
membuat yang berikut:
- Dua salinan dari library implementasi: satu library bernama
X
dan lainnya bernamaX.impl
. LibraryX
diinstal pada perangkat. LibraryX.impl
hanya ada jika akses eksplisit ke library implementasi diperlukan oleh modul lain, seperti untuk digunakan dalam pengujian. Perhatikan bahwa akses eksplisit jarang diperlukan. - Cakupan dapat diaktifkan dan dinonaktifkan untuk menyesuaikan akses. (Mirip dengan pengubah akses kata kunci Java, ruang lingkup publik menyediakan berbagai akses; ruang lingkup pengujian berisi API yang hanya digunakan dalam pengujian.) Untuk setiap cakupan yang diaktifkan, perpustakaan membuat hal berikut:
- Modul sumber stub (dari tipe modul
droidstubs
) - menggunakan sumber implementasi dan mengeluarkan satu set sumber rintisan bersama dengan file spesifikasi API. - Pustaka stub (dari tipe modul
java_library
) - adalah versi kompilasi dari stub. Lib yang digunakan untuk mengompilasi ini tidak sama dengan yang dipasok kejava_sdk_library
, yang memastikan detail implementasi tidak bocor ke stub API. - Jika Anda memerlukan pustaka tambahan untuk mengompilasi stub, gunakan properti
stub_only_libs
danstub_only_static_libs
untuk menyediakannya.
Jika java_sdk_library
disebut “ X
”, dan sedang dikompilasi sebagai “ X
”, selalu rujuk seperti itu dan jangan ubah. Build akan memilih perpustakaan yang sesuai. Untuk memastikan bahwa Anda memiliki pustaka yang paling sesuai, periksa stub Anda untuk melihat apakah build menimbulkan kesalahan. Lakukan koreksi yang diperlukan dengan menggunakan panduan ini:
- Pastikan Anda memiliki pustaka yang sesuai dengan melihat baris perintah dan memeriksa rintisan mana yang terdaftar di sana untuk menentukan cakupan Anda:
- Cakupan terlalu luas: Pustaka bergantung memerlukan cakupan API tertentu. Namun Anda melihat API yang disertakan dalam pustaka yang berada di luar cakupan itu, seperti API sistem yang disertakan dengan API publik.
- Cakupan terlalu sempit: Pustaka yang bergantung tidak memiliki akses ke semua pustaka yang diperlukan. Misalnya, perpustakaan dependen perlu menggunakan API sistem tetapi mendapatkan API publik sebagai gantinya. Ini biasanya menghasilkan kesalahan kompilasi karena API yang diperlukan tidak ada.
- Untuk memperbaiki perpustakaan, lakukan hanya salah satu hal berikut ini:
- Ubah
sdk_version
untuk memilih versi yang Anda butuhkan. ATAU - Tentukan pustaka yang sesuai secara eksplisit, seperti
<X>.stubs
atau<X>.stubs.system
.
penggunaan java_sdk_library X
Pustaka implementasi X
digunakan saat dirujuk dari apex.java_libs
. Namun, karena keterbatasan Soong, ketika library X
direferensikan dari modul java_sdk_library
lain dalam library APEX yang sama , X.impl
secara eksplisit harus digunakan, bukan library X
.
Ketika java_sdk_library
dirujuk dari tempat lain, pustaka stub digunakan. Pustaka rintisan dipilih sesuai dengan pengaturan properti sdk_version
modul tergantung. Misalnya, modul yang menentukan sdk_version: "current"
menggunakan stub publik, sedangkan modul yang menentukan sdk_version: "system_current"
menggunakan stub sistem. Jika kecocokan persis tidak dapat ditemukan, perpustakaan rintisan terdekat akan digunakan. java_sdk_library
yang hanya menyediakan API publik akan menyediakan rintisan publik untuk semua orang.
![Bangun alur dengan pustaka Java SDK](https://source.android.com/static/devices/architecture/images/build-flow-java-lib.png?authuser=6&hl=id)
Contoh dan sumber
Properti srcs
dan api_packages
harus ada di java_sdk_library
.
java_sdk_library { name: "com.android.future.usb.accessory", srcs: ["src/**/*.java"], api_packages: ["com.android.future.usb"], }
AOSP merekomendasikan (tetapi tidak mengharuskan) bahwa instance java_sdk_library
baru secara eksplisit mengaktifkan cakupan API yang ingin mereka gunakan. Anda juga dapat (secara opsional) memigrasikan instance java_sdk_library
yang ada untuk secara eksplisit mengaktifkan cakupan API yang akan mereka gunakan:
java_sdk_library { name: "lib", public: { enabled: true, }, system: { enabled: true, }, … }
Untuk mengonfigurasi pustaka impl
yang digunakan untuk runtime, gunakan semua properti java_library
normal, seperti hostdex
, compile_dex
, dan 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, }
Untuk mengonfigurasi pustaka rintisan, gunakan properti berikut:
-
merge_annotations_dirs
danmerge_inclusion_annotations_dirs
. -
api_srcs
: Daftar file sumber opsional yang merupakan bagian dari API tetapi bukan bagian dari perpustakaan runtime. -
stubs_only_libs
: Daftar library Java yang ada di classpath saat membuat stub. -
hidden_api_packages
: Daftar nama paket yang harus disembunyikan dari API. -
droiddoc_options
: Argumen tambahan untuk metalava . -
droiddoc_option_files
: Daftar file yang dapat dirujuk dari dalamdroiddoc_options
menggunakan$(location <label>)
, di mana<file>
adalah entri dalam daftar. -
annotations_enabled
.
java_sdk_library
adalah java_library
, tetapi ini bukan modul droidstubs
sehingga tidak mendukung semua properti droidstubs
. Contoh berikut diambil dari file build library 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, }
Mempertahankan kompatibilitas mundur
Sistem build memeriksa apakah API telah mempertahankan kompatibilitas mundur dengan membandingkan file API terbaru dengan file API yang dihasilkan pada waktu build. java_sdk_library
melakukan pemeriksaan kompatibilitas menggunakan informasi yang disediakan oleh prebuilt_apis
. Semua perpustakaan yang dibangun dengan java_sdk_library
harus memiliki file API dalam versi terbaru api_dirs
di prebuilt_apis
. Saat Anda merilis versi, file daftar API dan pustaka stub dapat diperoleh dengan dist build dengan PRODUCT=sdk_phone_armv7-sdk
.
Properti api_dirs
adalah daftar direktori versi API di prebuilt_apis
. Direktori versi API harus berada di tingkat direktori Android.bp
.
prebuilt_apis { name: "foo", api_dirs: [ "1", "2", .... "30", "current", ], }
Konfigurasikan direktori dengan struktur version / scope /api/
di bawah direktori prebuilts. version
sesuai dengan level API dan scope
menentukan apakah direktori tersebut publik, sistem, atau pengujian.
-
version / scope
berisi perpustakaan Java. -
version / scope /api
berisi file API.txt
. Buat file teks kosong bernamamodule_name .txt
danmodule_name -removed.txt
di sini.├── 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