Dukungan Sistem Bangun VNDK

Di Android 8.1 dan yang lebih tinggi, sistem build memiliki dukungan VNDK bawaan. Saat dukungan VNDK diaktifkan, sistem build akan memeriksa dependensi antar modul, membuat varian khusus vendor untuk modul vendor, dan secara otomatis menginstal modul tersebut ke direktori yang ditentukan.

Contoh dukungan pembuatan VNDK

Dalam contoh ini, definisi modul Android.bp mendefinisikan pustaka bernama libexample . Properti vendor_available menunjukkan modul kerangka kerja dan modul vendor mungkin bergantung pada libexample :

libexample vendor_available:true dan vndk.enabled:true

Gambar 1. Dukungan VNDK diaktifkan

Baik kerangka kerja yang dapat dieksekusi /system/bin/foo dan vendor yang dapat dieksekusi /vendor/bin/bar bergantung pada libexample dan memiliki libexample di properti shared_libs mereka.

Jika libexample digunakan oleh modul framework dan modul vendor, dua varian libexample akan dibuat. Varian inti (dinamai libexample ) digunakan oleh modul kerangka kerja dan varian vendor (dinamai libexample.vendor ) digunakan oleh modul vendor. Kedua varian diinstal ke direktori yang berbeda:

  • Varian inti diinstal ke /system/lib[64]/libexample.so .
  • Varian vendor diinstal ke dalam VNDK APEX karena vndk.enabled adalah true .

Untuk detail selengkapnya, lihat Definisi modul .

Mengonfigurasi dukungan build

Untuk mengaktifkan dukungan sistem build penuh untuk perangkat produk, tambahkan BOARD_VNDK_VERSION ke BoardConfig.mk :

BOARD_VNDK_VERSION := current

Pengaturan ini memiliki efek global : Ketika didefinisikan di BoardConfig.mk , semua modul diperiksa. Karena tidak ada mekanisme untuk membuat daftar hitam atau daftar putih modul yang melanggar, Anda harus membersihkan semua dependensi yang tidak perlu sebelum menambahkan BOARD_VNDK_VERSION . Anda dapat menguji dan mengkompilasi modul dengan menyetel BOARD_VNDK_VERSION di variabel lingkungan Anda:

$ BOARD_VNDK_VERSION=current m module_name.vendor

Saat BOARD_VNDK_VERSION diaktifkan, beberapa jalur pencarian tajuk global default akan dihapus . Ini termasuk:

  • frameworks/av/include
  • frameworks/native/include
  • frameworks/native/opengl/include
  • hardware/libhardware/include
  • hardware/libhardware_legacy/include
  • hardware/ril/include
  • libnativehelper/include
  • libnativehelper/include_deprecated
  • system/core/include
  • system/media/audio/include

Jika sebuah modul bergantung pada header dari direktori ini, Anda harus menentukan (secara eksplisit) dependensi dengan header_libs , static_libs , dan/atau shared_libs .

VNDK APEX

Di Android 10 dan yang lebih rendah, modul dengan vndk.enabled dipasang di /system/lib[64]/vndk[-sp]-${VER} . Di Android 11 dan yang lebih tinggi, pustaka VNDK dikemas dalam format APEX dan nama VNDK APEX adalah com.android.vndk.v${VER} . Bergantung pada konfigurasi perangkat, VNDK APEX diratakan atau tidak diratakan dan tersedia dari jalur kanonik /apex/com.android.vndk.v${VER} .

VNDK APEX

Gambar 2. VNDK APEX

Definisi modul

Untuk membangun Android dengan BOARD_VNDK_VERSION , Anda harus merevisi definisi modul di Android.mk atau Android.bp . Bagian ini menjelaskan berbagai jenis definisi modul, beberapa properti modul terkait VNDK, dan pemeriksaan ketergantungan yang diterapkan dalam sistem pembangunan.

Modul vendor

Modul vendor adalah executable khusus vendor atau pustaka bersama yang harus diinstal ke dalam partisi vendor. Dalam file Android.bp , modul vendor harus menyetel properti vendor atau kepemilikan menjadi true . Dalam file Android.mk , modul vendor harus menyetel LOCAL_VENDOR_MODULE atau LOCAL_PROPRIETARY_MODULE ke true .

Jika BOARD_VNDK_VERSION ditentukan, sistem pembangunan tidak mengizinkan dependensi antara modul vendor dan modul kerangka kerja dan mengeluarkan kesalahan jika:

  • modul tanpa vendor:true bergantung pada modul dengan vendor:true , atau
  • modul dengan vendor:true bergantung pada modul non- llndk_library yang tidak memiliki vendor:true atau vendor_available:true .

Pemeriksaan ketergantungan berlaku untuk header_libs , static_libs , dan shared_libs di Android.bp , dan untuk LOCAL_HEADER_LIBRARIES , LOCAL_STATIC_LIBRARIES dan LOCAL_SHARED_LIBRARIES di Android.mk .

LL-NDK

Pustaka bersama LL-NDK adalah pustaka bersama dengan ABI yang stabil. Baik kerangka kerja dan modul vendor berbagi implementasi yang sama dan terbaru. Untuk setiap pustaka bersama LL-NDK, Android.bp berisi definisi modul llndk_library :

llndk_library {
    name: "libvndksupport",
    symbol_file: "libvndksupport.map.txt",
}

Definisi modul ini menentukan nama modul dan file simbol yang menjelaskan simbol yang terlihat oleh modul vendor. Sebagai contoh:

LIBVNDKSUPPORT {
  global:
    android_load_sphal_library; # llndk
    android_unload_sphal_library; # llndk
  local:
    *;
};

Berdasarkan file simbol, sistem pembangunan menghasilkan pustaka rintisan bersama untuk modul vendor, yang tertaut dengan pustaka ini saat BOARD_VNDK_VERSION diaktifkan. Sebuah simbol disertakan dalam perpustakaan rintisan bersama hanya jika:

  • Tidak didefinisikan di bagian yang diakhiri dengan _PRIVATE atau _PLATFORM ,
  • Tidak memiliki tag #platform-only , dan
  • Tidak memiliki tag #introduce* atau tag sesuai dengan target.

VNDK

Dalam file Android.bp , definisi modul cc_library , cc_library_static , cc_library_shared , dan cc_library_headers mendukung tiga properti terkait VNDK: vendor_available , vndk.enabled , dan vndk.support_system_process .

Jika vendor_available atau vndk.enabled true , dua varian ( core dan vendor ) dapat dibuat. Varian inti harus diperlakukan sebagai modul kerangka kerja dan varian vendor harus diperlakukan sebagai modul vendor. Jika beberapa modul kerangka kerja bergantung pada modul ini, varian inti akan dibuat. Jika beberapa modul vendor bergantung pada modul ini, varian vendor akan dibuat. Sistem build memberlakukan pemeriksaan ketergantungan berikut:

  • Varian inti selalu hanya kerangka kerja dan tidak dapat diakses oleh modul vendor.
  • Varian vendor selalu tidak dapat diakses oleh modul kerangka kerja.
  • Semua dependensi varian vendor, yang ditentukan dalam header_libs , static_libs , dan/atau shared_libs , harus berupa llndk_library atau modul dengan vendor_available atau vndk.enabled .
  • Jika vendor_available true , varian vendor dapat diakses oleh semua modul vendor.
  • Jika vendor_available adalah false , varian vendor hanya dapat diakses oleh modul VNDK atau VNDK-SP lainnya (yaitu, modul dengan vendor:true tidak dapat menautkan modul vendor_available:false ).

Jalur penginstalan default untuk cc_library atau cc_library_shared ditentukan oleh aturan berikut:

  • Varian inti diinstal ke /system/lib[64] .
  • Jalur penginstalan varian vendor dapat bervariasi:
    • Jika vndk.enabled false , varian vendor diinstal ke /vendor/lib[64] .
    • Jika vndk.enabled true , varian vendor diinstal ke VNDK APEX( com.android.vndk.v${VER} ).

Tabel di bawah ini merangkum cara sistem build menangani varian vendor:

vendor_tersedia vndk
diaktifkan
vndk
support_same_process
Deskripsi varian vendor
true false false Varian vendor adalah VND-ONLY . Pustaka bersama diinstal ke /vendor/lib[64] .
true Tidak valid (Build error)
true false Varian vendornya adalah VNDK . Pustaka bersama diinstal ke VNDK APEX.
true Varian vendornya adalah VNDK-SP . Pustaka bersama diinstal ke VNDK APEX.

false

false

false

Tidak ada varian vendor. Modul ini HANYA FWK .

true Tidak valid (Build error)
true false Varian vendor adalah VNDK-Private . Pustaka bersama diinstal ke VNDK APEX. Ini tidak boleh langsung digunakan oleh modul vendor.
true Varian vendornya adalah VNDK-SP-Private . Pustaka bersama diinstal ke VNDK APEX. Ini tidak boleh langsung digunakan oleh modul vendor.

Ekstensi VNDK

Ekstensi VNDK adalah pustaka bersama VNDK dengan API tambahan. Ekstensi diinstal ke /vendor/lib[64]/vndk[-sp] (tanpa akhiran versi) dan menimpa pustaka bersama VNDK asli saat runtime.

Mendefinisikan ekstensi VNDK

Di Android 9 dan yang lebih tinggi, Android.bp secara native mendukung ekstensi VNDK. Untuk membuat ekstensi VNDK, tentukan modul lain dengan properti vendor:true dan extends :

cc_library {
    name: "libvndk",
    vendor_available: true,
    vndk: {
        enabled: true,
    },
}

cc_library {
    name: "libvndk_ext",
    vendor: true,
    vndk: {
        enabled: true,
        extends: "libvndk",
    },
}

Modul dengan vendor:true , vndk.enabled:true , dan extends properties mendefinisikan ekstensi VNDK:

  • Properti extends harus menentukan nama pustaka bersama VNDK dasar (atau nama pustaka bersama VNDK-SP).
  • Ekstensi VNDK (atau ekstensi VNDK-SP) diberi nama sesuai dengan nama modul dasar yang diperluas. Misalnya, biner keluaran libvndk_ext adalah libvndk.so bukan libvndk_ext.so .
  • Ekstensi VNDK dipasang ke /vendor/lib[64]/vndk .
  • Ekstensi VNDK-SP diinstal ke /vendor/lib[64]/vndk-sp .
  • Pustaka bersama dasar harus memiliki vndk.enabled:true dan vendor_available:true .

Ekstensi VNDK-SP harus diperluas dari pustaka bersama VNDK-SP ( vndk.support_system_process harus sama):

cc_library {
    name: "libvndk_sp",
    vendor_available: true,
    vndk: {
        enabled: true,
        support_system_process: true,
    },
}

cc_library {
    name: "libvndk_sp_ext",
    vendor: true,
    vndk: {
        enabled: true,
        extends: "libvndk_sp",
        support_system_process: true,
    },
}

Ekstensi VNDK (atau ekstensi VNDK-SP) mungkin bergantung pada pustaka bersama vendor lainnya:

cc_library {
    name: "libvndk",
    vendor_available: true,
    vndk: {
        enabled: true,
    },
}

cc_library {
    name: "libvndk_ext",
    vendor: true,
    vndk: {
        enabled: true,
        extends: "libvndk",
    },
    shared_libs: [
        "libvendor",
    ],
}

cc_library {
    name: "libvendor",
    vendor: true,
}

Menggunakan ekstensi VNDK

Jika modul vendor bergantung pada API tambahan yang ditentukan oleh ekstensi VNDK, modul harus menentukan nama ekstensi VNDK di properti shared_libs -nya:

// A vendor shared library example
cc_library {
    name: "libvendor",
    vendor: true,
    shared_libs: [
        "libvndk_ext",
    ],
}

// A vendor executable example
cc_binary {
    name: "vendor-example",
    vendor: true,
    shared_libs: [
        "libvndk_ext",
    ],
}

Jika modul vendor bergantung pada ekstensi VNDK, ekstensi VNDK tersebut diinstal ke /vendor/lib[64]/vndk[-sp] secara otomatis. Jika modul tidak lagi bergantung pada ekstensi VNDK, tambahkan langkah bersih ke CleanSpec.mk untuk menghapus pustaka bersama. Sebagai contoh:

$(call add-clean-step, rm -rf $(TARGET_OUT_VENDOR)/lib/libvndk.so)

kompilasi bersyarat

Bagian ini menjelaskan cara menangani perbedaan halus (misalnya menambahkan atau menghapus fitur dari salah satu varian) antara tiga pustaka bersama VNDK berikut:

  • Varian inti (misalnya /system/lib[64]/libexample.so )
  • Varian vendor (mis /apex/com.android.vndk.v${VER}/lib[64]/libexample.so )
  • Ekstensi VNDK (mis. /vendor/lib[64]/vndk[-sp]/libexample.so )

Bendera kompiler bersyarat

Sistem pembangunan Android mendefinisikan __ANDROID_VNDK__ untuk varian vendor dan ekstensi VNDK secara default. Anda dapat menjaga kode dengan pelindung praprosesor C:

void all() { }

#if !defined(__ANDROID_VNDK__)
void framework_only() { }
#endif

#if defined(__ANDROID_VNDK__)
void vndk_only() { }
#endif

Selain __ANDROID_VNDK__ , cflags atau cppflags yang berbeda dapat ditentukan di Android.bp . cflags atau cppflags ditentukan dalam target.vendor khusus untuk varian vendor.

Misalnya, Android.bp berikut mendefinisikan libexample dan libexample_ext :

cc_library {
    name: "libexample",
    srcs: ["src/example.c"],
    vendor_available: true,
    vndk: {
        enabled: true,
    },
    target: {
        vendor: {
            cflags: ["-DLIBEXAMPLE_ENABLE_VNDK=1"],
        },
    },
}

cc_library {
    name: "libexample_ext",
    srcs: ["src/example.c"],
    vendor: true,
    vndk: {
        enabled: true,
        extends: "libexample",
    },
    cflags: [
        "-DLIBEXAMPLE_ENABLE_VNDK=1",
        "-DLIBEXAMPLE_ENABLE_VNDK_EXT=1",
    ],
}

Dan ini adalah daftar kode dari src/example.c :

void all() { }

#if !defined(LIBEXAMPLE_ENABLE_VNDK)
void framework_only() { }
#endif

#if defined(LIBEXAMPLE_ENABLE_VNDK)
void vndk() { }
#endif

#if defined(LIBEXAMPLE_ENABLE_VNDK_EXT)
void vndk_ext() { }
#endif

Menurut dua file ini, sistem build menghasilkan pustaka bersama dengan simbol yang diekspor berikut:

Jalur instalasi Simbol yang diekspor
/system/lib[64]/libexample.so all , framework_only
/apex/com.android.vndk.v${VER}/lib[64]/libexample.so all , vndk
/vendor/lib[64]/vndk/libexample.so all , vndk , vndk_ext

Persyaratan pada simbol yang diekspor

Pemeriksa ABI VNDK membandingkan ABI varian vendor VNDK dan ekstensi VNDK dengan dump ABI referensi di bawah prebuilts/abi-dumps/vndk .

  • Simbol yang diekspor oleh varian vendor VNDK (mis /apex/com.android.vndk.v${VER}/lib[64]/libexample.so ) harus identik dengan (bukan superset dari) simbol yang ditentukan di dump ABI.
  • Simbol yang diekspor oleh ekstensi VNDK (mis. /vendor/lib[64]/vndk/libexample.so ) harus berupa superset dari simbol yang ditentukan dalam dump ABI.

Jika varian vendor VNDK atau ekstensi VNDK gagal mengikuti persyaratan di atas, pemeriksa ABI VNDK mengeluarkan kesalahan build dan menghentikan build.

Tidak termasuk file sumber atau pustaka bersama dari varian vendor

Untuk mengecualikan file sumber dari varian vendor, tambahkan file tersebut ke properti exclude_srcs . Demikian pula, untuk memastikan pustaka bersama tidak ditautkan dengan varian vendor, tambahkan pustaka tersebut ke properti exclude_shared_libs . Sebagai contoh:

cc_library {
    name: "libexample_cond_exclude",
    srcs: ["fwk.c", "both.c"],
    shared_libs: ["libfwk_only", "libboth"],
    vendor_available: true,
    target: {
        vendor: {
            exclude_srcs: ["fwk.c"],
            exclude_shared_libs: ["libfwk_only"],
        },
    },
}

Dalam contoh ini, varian inti dari libexample_cond_exclude menyertakan kode dari fwk.c dan both.c dan bergantung pada pustaka bersama libfwk_only dan libboth . Varian vendor dari libexample_cond_exclude hanya menyertakan kode dari both.c karena fwk.c dikecualikan oleh properti exclude_srcs . Demikian pula, itu hanya bergantung pada libboth perpustakaan bersama karena libfwk_only dikecualikan oleh properti exclude_shared_libs .

Ekspor tajuk dari ekstensi VNDK

Ekstensi VNDK dapat menambahkan kelas baru atau fungsi baru ke pustaka bersama VNDK. Disarankan untuk menyimpan deklarasi tersebut di header independen dan menghindari mengubah header yang ada.

Misalnya, file header baru include-ext/example/ext/feature_name.h dibuat untuk ekstensi libexample_ext :

  • Android.bp
  • include-ext/example/ext/feature_name.h
  • sertakan/contoh/contoh.h
  • src/contoh.c
  • src/ext/feature_name.c

Di Android.bp berikut, ekspor libexample hanya include , sedangkan libexample_ext mengekspor include dan include-ext . Ini memastikan feature_name.h tidak akan salah dimasukkan oleh pengguna libexample :

cc_library {
    name: "libexample",
    srcs: ["src/example.c"],
    export_include_dirs: ["include"],
    vendor_available: true,
    vndk: {
        enabled: true,
    },
}

cc_library {
    name: "libexample_ext",
    srcs: [
        "src/example.c",
        "src/ext/feature_name.c",
    ],
    export_include_dirs: [
        "include",
        "include-ext",
    ],
    vendor: true,
    vndk: {
        enabled: true,
        extends: "libexample",
    },
}

Jika memisahkan ekstensi ke file header independen tidak memungkinkan, alternatifnya adalah menambahkan pelindung #ifdef . Namun, pastikan bahwa semua pengguna ekstensi VNDK menambahkan flag yang ditentukan. Anda dapat mendefinisikan cc_defaults untuk menambahkan flag define ke cflags dan menautkan pustaka bersama dengan shared_libs .

Misalnya, untuk menambahkan fungsi anggota baru Example2::get_b() ke ekstensi libexample2_ext , Anda harus memodifikasi file header yang ada dan menambahkan #ifdef guard:

#ifndef LIBEXAMPLE2_EXAMPLE_H_
#define LIBEXAMPLE2_EXAMPLE_H_

class Example2 {
 public:
  Example2();

  void get_a();

#ifdef LIBEXAMPLE2_ENABLE_VNDK_EXT
  void get_b();
#endif

 private:
  void *impl_;
};

#endif  // LIBEXAMPLE2_EXAMPLE_H_

Sebuah cc_defaults bernama libexample2_ext_defaults didefinisikan untuk pengguna libexample2_ext :

cc_library {
    name: "libexample2",
    srcs: ["src/example2.cpp"],
    export_include_dirs: ["include"],
    vendor_available: true,
    vndk: {
        enabled: true,
    },
}

cc_library {
    name: "libexample2_ext",
    srcs: ["src/example2.cpp"],
    export_include_dirs: ["include"],
    vendor: true,
    vndk: {
        enabled: true,
        extends: "libexample2",
    },
    cflags: [
        "-DLIBEXAMPLE2_ENABLE_VNDK_EXT=1",
    ],
}

cc_defaults {
    name: "libexample2_ext_defaults",
    shared_libs: [
        "libexample2_ext",
    ],
    cflags: [
        "-DLIBEXAMPLE2_ENABLE_VNDK_EXT=1",
    ],
}

Pengguna libexample2_ext cukup menyertakan libexample2_ext_defaults di properti defaults mereka:

cc_binary {
    name: "example2_user_executable",
    defaults: ["libexample2_ext_defaults"],
    vendor: true,
}

Paket produk

Dalam sistem pembangunan Android, variabel PRODUCT_PACKAGES menentukan file yang dapat dieksekusi, pustaka bersama, atau paket yang harus dipasang ke perangkat. Dependensi transitif dari modul yang ditentukan juga diinstal secara implisit ke dalam perangkat.

Jika BOARD_VNDK_VERSION diaktifkan, modul dengan vendor_available atau vndk.enabled mendapatkan perlakuan khusus. Jika modul kerangka kerja bergantung pada modul dengan vendor_available atau vndk.enabled , varian inti disertakan dalam set penginstalan transitif. Jika modul vendor bergantung pada modul dengan vendor_available , varian vendor disertakan dalam set penginstalan transitif. Namun, varian vendor modul dengan vndk.enabled diinstal baik digunakan oleh modul vendor atau tidak.

Ketika dependensi tidak terlihat oleh sistem pembangunan (misalnya pustaka bersama yang dapat dibuka dengan dlopen() pada waktu proses), Anda harus menentukan nama modul di PRODUCT_PACKAGES untuk menginstal modul tersebut secara eksplisit.

Jika modul memiliki vendor_available atau vndk.enabled , nama modul mewakili varian intinya. Untuk secara eksplisit menentukan varian vendor di PRODUCT_PACKAGES , tambahkan akhiran .vendor ke nama modul. Sebagai contoh:

cc_library {
    name: "libexample",
    srcs: ["example.c"],
    vendor_available: true,
}

Dalam contoh ini, libexample adalah singkatan dari /system/lib[64]/libexample.so dan libexample.vendor adalah singkatan dari /vendor/lib[64]/libexample.so . Untuk menginstal /vendor/lib[64]/libexample.so , tambahkan libexample.vendor ke PRODUCT_PACKAGES :

PRODUCT_PACKAGES += libexample.vendor