Menggabungkan beberapa file manifes

File APK atau Android App Bundle hanya dapat berisi satu file AndroidManifest.xml, tetapi project Android Studio dapat berisi beberapa file, yang disediakan oleh set sumber utama, varian build, dan library yang diimpor. Jadi, saat mem-build aplikasi, build Gradle akan menggabungkan semua file manifes ke dalam satu file manifes tunggal yang dikemas ke dalam aplikasi Anda.

Alat penggabung manifes mengombinasikan semua elemen XML dari setiap file dengan mengikuti beberapa heuristik penggabungan dan dengan mematuhi preferensi penggabungan yang telah didefinisikan dengan atribut XML khusus. Halaman ini menjelaskan cara kerja penggabungan manifes dan cara menerapkan preferensi penggabungan untuk mengatasi konflik penggabungan.

Tips: Gunakan tampilan Manifes Gabungan untuk melihat pratinjau hasil manifes yang digabungkan dan menemukan error konflik.

Prioritas penggabungan

Alat penggabung akan mengombinasikan semua file manifes ke dalam satu file dengan menggabungkannya secara berurutan berdasarkan prioritas setiap file manifes. Misalnya, jika Anda memiliki tiga file manifes, manifes berprioritas terendah akan digabungkan ke prioritas tertinggi berikutnya, lalu digabungkan lagi ke dalam manifes berprioritas tertinggi, seperti yang diilustrasikan dalam gambar 1.

Gambar 1. Proses menggabungkan tiga file manifes, prioritas terendah (kiri) ke dalam prioritas tertinggi (kanan)

Ada tiga jenis dasar file manifes yang dapat digabungkan satu sama lain, dan prioritas penggabungannya adalah sebagai berikut (prioritas tertinggi terlebih dahulu):

1. File manifes untuk varian build Anda

   Jika Anda memiliki beberapa set sumber untuk varian, prioritas manifesnya adalah sebagai berikut:

   1. Manifes varian build (seperti src/demoDebug/)
   2. Manifes jenis build (seperti src/debug/)
   3. Manifes ragam produk (seperti src/demo/)

      Jika Anda menggunakan dimensi ragam, prioritas manifes akan menyesuaikan urutan pencantuman setiap dimensi dalam properti flavorDimensions (prioritas tertinggi adalah yang pertama).

2. File manifes utama untuk modul aplikasi
3. File manifes dari library yang disertakan

   Jika Anda memiliki beberapa library, prioritas manifesnya akan dicocokkan dengan urutan dependensinya (urutan kemunculannya dalam blok dependencies Gradle Anda).

Misalnya, sebuah manifes library digabungkan ke dalam manifes utama, lalu manifes utama tersebut digabungkan ke dalam manifes varian build.

Penting: Konfigurasi build dari file build.gradle akan menggantikan setiap atribut yang terkait dalam file manifes gabungan. Misalnya, minSdkVersion dari file build.gradle akan menggantikan atribut yang cocok dalam elemen manifes <uses-sdk>. Untuk mempermudah, sebaiknya biarkan elemen <uses-sdk> dan tentukan properti ini hanya dalam file build.gradle. Untuk detail lebih lanjut, lihat Mengonfigurasi build Anda.

Heuristik konflik penggabungan

Alat penggabung secara logis dapat mencocokkan setiap elemen XML dari satu manifes ke elemen yang terkait di manifes lainnya. (Untuk mengetahui detail tentang cara kerja pencocokan, lihat apendiks tentang kebijakan penggabungan).

Jika elemen dari manifes yang berprioritas lebih rendah tidak cocok dengan elemen apa pun dalam manifes yang berprioritas lebih tinggi, elemen tersebut akan ditambahkan ke manifes gabungan. Namun, jika ada elemen yang cocok, alat penggabung akan mencoba mengombinasikan semua atribut ke dalam satu elemen yang sama. Jika alat ini menemukan bahwa kedua manifes berisi atribut yang sama dengan nilai berbeda, konflik penggabungan akan terjadi.

Tabel 1 menggambarkan kemungkinan hasil ketika alat penggabung mencoba mengombinasikan semua atribut ke dalam elemen yang sama.

Tabel 1. Perilaku penggabungan default untuk nilai atribut

Namun, ada beberapa situasi ketika alat penggabung berperilaku berbeda untuk menghindari konflik penggabungan:

• Atribut dalam elemen <manifest> tidak pernah digabung bersama, hanya atribut dari manifes prioritas tertinggi yang digunakan.
• Atribut android:required dalam elemen <uses-feature> dan <uses-library> menggunakan penggabungan OR, sehingga jika terjadi konflik, "true" akan diterapkan dan fitur atau library yang diperlukan oleh satu manifes akan selalu disertakan.
• Atribut dalam elemen <uses-sdk> selalu menggunakan nilai dari manifes berprioritas lebih tinggi, kecuali dalam situasi berikut:
  • Jika manifes yang berprioritas lebih rendah memiliki nilai minSdkVersion yang lebih tinggi, error akan terjadi kecuali jika Anda menerapkan aturan penggabungan overrideLibrary.
  • Jika manifes yang berprioritas lebih rendah memiliki nilai targetSdkVersion yang lebih rendah, alat penggabung akan menggunakan nilai dari manifes yang berprioritas lebih tinggi, tetapi juga menambahkan izin sistem yang diperlukan untuk memastikan library yang diimpor tetap berfungsi dengan benar (seandainya versi Android yang lebih tinggi telah meningkatkan pembatasan izin). Untuk informasi selengkapnya tentang perilaku ini, lihat bagian tentang izin sistem implisit.
• Elemen <intent-filter> tidak pernah dicocokkan di antara manifest. Masing-masing diperlakukan secara unik dan ditambahkan ke elemen induk biasa di manifes gabungan.

Untuk semua konflik di antara atribut lainnya, Anda akan menerima pesan error dan harus memberi tahu alat penggabung tentang cara mengatasinya dengan menambahkan atribut khusus dalam file manifes yang berprioritas lebih tinggi (lihat bagian berikutnya tentang penanda aturan penggabungan).

Jangan bergantung pada nilai-nilai atribut default. Karena semua atribut unik dikombinasikan ke dalam elemen yang sama, hal ini dapat menyebabkan hasil yang tidak diharapkan jika manifes yang berprioritas lebih tinggi sebenarnya bergantung pada nilai default suatu atribut tanpa mendeklarasikannya. Misalnya, jika manifes yang berprioritas lebih tinggi tidak mendeklarasikan atribut android:launchMode, manifes tersebut akan menggunakan nilai default "standard". Namun, jika manifes yang berprioritas lebih rendah mendeklarasikan atribut ini dengan nilai yang berbeda, nilai tersebut akan diterapkan ke manifes gabungan (yang akan menggantikan nilai default). Oleh karena itu, sebaiknya tentukan setiap atribut secara eksplisit sesuai yang Anda inginkan. (Nilai default untuk setiap atribut didokumentasikan dalam Referensi manifes.)

Penanda aturan penggabungan

Penanda aturan penggabungan adalah atribut XML yang dapat digunakan untuk menyatakan preferensi Anda tentang cara mengatasi konflik penggabungan atau menghapus elemen dan atribut yang tidak diinginkan. Anda dapat menerapkan penanda ke seluruh elemen atau hanya pada atribut tertentu dalam elemen.

Saat menggabungkan dua file manifes, alat penggabung akan mencari penanda ini dalam file manifes yang berprioritas lebih tinggi.

Semua penanda dimiliki oleh namespace tools Android, jadi Anda harus mendeklarasikan namespace ini terlebih dahulu dalam elemen <manifest> seperti yang ditampilkan berikut:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.example.myapp"
    xmlns:tools="http://schemas.android.com/tools">

Penanda node

Untuk menerapkan aturan penggabungan ke seluruh elemen XML (ke semua atribut dalam elemen manifes yang ditentukan dan ke semua tag turunannya), gunakan atribut berikut:

tools:node="merge"

Gabungkan semua atribut dalam tag ini dan semua elemen bertingkat jika tidak ada konflik dengan menggunakan heuristik konflik penggabungan. Ini adalah perilaku default elemen.

Manifes berprioritas rendah:

<activity android:name="com.example.ActivityOne"
    android:windowSoftInputMode="stateUnchanged">
    <intent-filter>
        <action android:name="android.intent.action.SEND" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

Manifes berprioritas tinggi:

<activity android:name="com.example.ActivityOne"
    android:screenOrientation="portrait"
    tools:node="merge">
</activity>

Hasil manifes gabungan:

<activity android:name="com.example.ActivityOne"
    android:screenOrientation="portrait"
    android:windowSoftInputMode="stateUnchanged">
    <intent-filter>
        <action android:name="android.intent.action.SEND" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

tools:node="merge-only-attributes"

Menggabungkan atribut dalam tag ini saja; tidak menggabungkan elemen tersarang.

Manifes berprioritas rendah:

<activity android:name="com.example.ActivityOne"
    android:windowSoftInputMode="stateUnchanged">
    <intent-filter>
        <action android:name="android.intent.action.SEND" />
        <data android:type="image/*" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

Manifes berprioritas tinggi:

<activity android:name="com.example.ActivityOne"
    android:screenOrientation="portrait"
    tools:node="merge-only-attributes">
</activity>

Hasil manifes gabungan:

<activity android:name="com.example.ActivityOne"
    android:screenOrientation="portrait"
    android:windowSoftInputMode="stateUnchanged">
</activity>

tools:node="remove"

Menghapus elemen ini dari manifes gabungan. Meskipun sepertinya Anda hanya perlu menghapus elemen ini, penggunaannya diperlukan jika Anda menemukan elemen di manifes gabungan yang tidak dibutuhkan, dan elemen itu disediakan oleh file manifes yang berprioritas lebih rendah yang berada di luar kendali Anda (seperti library yang diimpor).

Manifes berprioritas rendah:

<activity-alias android:name="com.example.alias">
  <meta-data android:name="cow"
      android:value="@string/moo"/>
  <meta-data android:name="duck"
      android:value="@string/quack"/>
</activity-alias>

Manifes berprioritas tinggi:

<activity-alias android:name="com.example.alias">
  <meta-data android:name="cow"
      tools:node="remove"/>
</activity-alias>

Hasil manifes gabungan:

<activity-alias android:name="com.example.alias">
  <meta-data android:name="duck"
      android:value="@string/quack"/>
</activity-alias>

tools:node="removeAll"

Seperti tools:node="remove", tetapi menghapus semua elemen yang cocok dengan jenis elemen ini (dalam elemen induk yang sama).

Manifes berprioritas rendah:

<activity-alias android:name="com.example.alias">
  <meta-data android:name="cow"
      android:value="@string/moo"/>
  <meta-data android:name="duck"
      android:value="@string/quack"/>
</activity-alias>

Manifes berprioritas tinggi:

<activity-alias android:name="com.example.alias">
  <meta-data tools:node="removeAll"/>
</activity-alias>

Hasil manifes gabungan:

<activity-alias android:name="com.example.alias">
</activity-alias>

tools:node="replace"

Mengganti seluruh elemen yang berprioritas lebih rendah. Artinya, jika ada elemen yang cocok dalam manifes yang berprioritas lebih rendah, abaikan elemen tersebut dan gunakan elemen ini persis sebagaimana munculnya dalam manifes.

Manifes berprioritas rendah:

<activity-alias android:name="com.example.alias">
  <meta-data android:name="cow"
      android:value="@string/moo"/>
  <meta-data android:name="duck"
      android:value="@string/quack"/>
</activity-alias>

Manifes berprioritas tinggi:

<activity-alias android:name="com.example.alias"
    tools:node="replace">
  <meta-data android:name="fox"
      android:value="@string/dingeringeding"/>
</activity-alias>

Hasil manifes gabungan:

<activity-alias android:name="com.example.alias">
  <meta-data android:name="fox"
      android:value="@string/dingeringeding"/>
</activity-alias>

tools:node="strict"

Hasilkan kegagalan build setiap kali elemen dalam manifes yang berprioritas lebih rendah tidak sama persis dengan elemen dalam manifes yang berprioritas lebih tinggi (kecuali jika telah ditangani oleh penanda aturan penggabungan lainnya). Ini akan menggantikan heuristik konflik penggabungan. Misalnya, jika manifes yang berprioritas lebih rendah hanya menyertakan atribut tambahan, build akan gagal (sedangkan perilaku default akan menambahkan atribut tambahan ke manifes gabungan).

Manifes berprioritas rendah:

<activity android:name="com.example.ActivityOne"
    android:windowSoftInputMode="stateUnchanged">
    <intent-filter>
        <action android:name="android.intent.action.SEND" />
        <category android:name="android.intent.category.DEFAULT" />
    </intent-filter>
</activity>

Manifes berprioritas tinggi:

<activity android:name="com.example.ActivityOne"
    android:screenOrientation="portrait"
    tools:node="strict">
</activity>

Kode ini akan mengakibatkan error penggabungan manifes. Kedua elemen manifes tidak dapat dibedakan sama sekali di mode ketat. Jadi, Anda harus menerapkan penanda aturan penggabungan lain untuk mengatasi perbedaan ini. (Biasanya, keduanya dapat digabungkan dengan baik seperti yang ditunjukkan dalam contoh untuk tools:node="merge" di atas.)

Penanda atribut

Untuk menerapkan aturan penggabungan hanya pada atribut tertentu di tag manifes, gunakan atribut berikut. Setiap atribut menerima satu atau beberapa nama atribut (termasuk namespace atribut), yang dipisah dengan koma.

tools:remove="attr, ..."

Menghapus atribut yang ditentukan dari manifes gabungan. Meskipun sepertinya Anda cukup menghapus atribut ini, Anda perlu menggunakannya ketika file manifes yang berprioritas lebih rendah menyertakan atribut ini dan Anda ingin memastikan atribut ini tidak disertakan ke manifes gabungan.

Manifes berprioritas rendah:

<activity android:name="com.example.ActivityOne"
    android:windowSoftInputMode="stateUnchanged">

Manifes berprioritas tinggi:

<activity android:name="com.example.ActivityOne"
    android:screenOrientation="portrait"
    tools:remove="android:windowSoftInputMode">

Hasil manifes gabungan:

<activity android:name="com.example.ActivityOne"
    android:screenOrientation="portrait">

tools:replace="attr, ..."

Mengganti atribut yang ditetapkan dalam manifes yang berprioritas lebih rendah dengan atribut dari manifes ini. Dengan kata lain, selalu mempertahankan nilai manifes yang berprioritas lebih tinggi.

Manifes berprioritas rendah:

<activity android:name="com.example.ActivityOne"
    android:theme="@oldtheme"
    android:exported="false"
    android:windowSoftInputMode="stateUnchanged">

Manifes berprioritas tinggi:

<activity android:name="com.example.ActivityOne"
    android:theme="@newtheme"
    android:exported="true"
    android:screenOrientation="portrait"
    tools:replace="android:theme,android:exported">

Hasil manifes gabungan:

<activity android:name="com.example.ActivityOne"
    android:theme="@newtheme"
    android:exported="true"
    android:screenOrientation="portrait"
    android:windowSoftInputMode="stateUnchanged">

tools:strict="attr, ..."

Hasilkan kegagalan build setiap kali atribut dalam manifes yang berprioritas lebih rendah ini tidak sama persis dengan atribut dalam manifes yang berprioritas lebih tinggi. Ini adalah perilaku default untuk semua atribut, kecuali yang memiliki perilaku khusus seperti yang dijelaskan dalam heuristik konflik penggabungan.

Manifes berprioritas rendah:

<activity android:name="com.example.ActivityOne"
    android:screenOrientation="landscape">
</activity>

Manifes berprioritas tinggi:

<activity android:name="com.example.ActivityOne"
    android:screenOrientation="portrait"
    tools:strict="android:screenOrientation">
</activity>

Kode ini akan mengakibatkan error penggabungan manifes. Anda harus menerapkan penanda aturan penggabungan lain untuk mengatasi konflik. (Perlu diingat bahwa ini adalah perilaku default, jadi contoh di atas memiliki hasil yang sama jika Anda menghapus tools:strict="screenOrientation".)

Anda juga bisa menerapkan beberapa penanda ke satu elemen seperti berikut.

<activity android:name="com.example.ActivityOne"
    android:theme="@oldtheme"
    android:exported="false"
    android:allowTaskReparenting="true"
    android:windowSoftInputMode="stateUnchanged">

<activity android:name="com.example.ActivityOne"
    android:theme="@newtheme"
    android:exported="true"
    android:screenOrientation="portrait"
    tools:replace="android:theme,android:exported"
    tools:remove="android:windowSoftInputMode">

Hasil manifes gabungan:

<activity android:name="com.example.ActivityOne"
    android:theme="@newtheme"
    android:exported="true"
    android:allowTaskReparenting="true"
    android:screenOrientation="portrait">

Pemilih penanda

Jika hanya Anda ingin menerapkan penanda aturan penggabungan ke suatu library yang diimpor, tambahkan atribut tools:selector dengan nama paket library.

Misalnya, dengan manifes berikut, aturan penggabungan remove hanya diterapkan jika file manifes yang berprioritas lebih rendah berasal dari library com.example.lib1.

<permission android:name="permissionOne"
    tools:node="remove"
    tools:selector="com.example.lib1">

Jika manifes yang berprioritas lebih rendah berasal dari sumber lain, aturan penggabungan remove akan diabaikan.

Catatan: Jika Anda menggunakan aturan ini dengan salah satu penanda atribut, aturan ini akan diterapkan ke semua atribut yang ditetapkan dalam penanda.

Mengganti <uses-sdk> untuk library yang diimpor

Secara default, saat mengimpor library minSdkVersion dengan nilai yang lebih tinggi dari file manifes utama project, akan terjadi error dan library tidak dapat diimpor. Agar alat penggabung mengabaikan konflik ini dan mengimpor library sekaligus mempertahankan nilai minSdkVersion yang lebih rendah di aplikasi Anda, tambahkan atribut overrideLibrary ke tag <uses-sdk>. Nilai atribut dapat berupa satu atau beberapa nama paket library (yang dipisahkan koma), menunjukkan library yang dapat menggantikan minSdkVersion manifes utama.

Misalnya, jika manifes utama aplikasi Anda menerapkan overrideLibrary seperti ini:

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          package="com.example.app"
          xmlns:tools="http://schemas.android.com/tools">
  <uses-sdk tools:overrideLibrary="com.example.lib1, com.example.lib2"/>
...

Manifes berikut dapat digabungkan tanpa error yang terkait dengan tag <uses-sdk>, dan manifes gabungan akan mempertahankan minSdkVersion="2" dari manifes aplikasi.

<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          package="com.example.lib1">
   <uses-sdk android:minSdkVersion="4" />
...

Izin sistem implisit

Beberapa Android API yang semula bebas diakses oleh aplikasi kini dibatasi oleh izin sistem di versi terbaru Android. Agar tidak mengganggu fungsi aplikasi yang meminta akses ke API ini, versi terbaru Android mengizinkan aplikasi terus mengakses API tersebut tanpa izin jika telah menetapkan targetSdkVersion ke nilai yang lebih rendah dari versi yang telah ditambahkan pembatasan. Perilaku ini secara efektif memberi aplikasi izin implisit untuk mengizinkan akses ke API tersebut. Oleh karena itu, perilaku ini dapat memengaruhi manifes gabungan yang memiliki nilai berbeda untuk targetSdkVersion dengan cara berikut.

Jika file manifes yang berprioritas lebih rendah memiliki nilai yang lebih rendah untuk targetSdkVersion yang memberinya izin implisit, dan manifes yang berprioritas lebih tinggi tidak memiliki izin implisit yang sama (karena targetSdkVersion miliknya sama dengan atau lebih tinggi dari versi yang telah ditambahkan pembatasan), maka alat penggabung secara eksplisit akan menambahkan izin sistem ke manifes gabungan.

Misalnya, jika aplikasi Anda menyetel targetSdkVersion ke 4 atau yang lebih tinggi dan mengimpor library dengan targetSdkVersion yang disetel ke 3 atau lebih rendah, alat penggabung akan menambahkan izin WRITE_EXTERNAL_STORAGE ke manifes gabungan. Tabel 2 mencantumkan semua izin yang dapat ditambahkan ke manifes gabungan.

Tabel 2. Daftar izin yang dapat ditambahkan oleh alat penggabung ke manifes gabungan

Memeriksa manifes gabungan dan menemukan konflik

Bahkan sebelum mem-build aplikasi, Anda dapat melihat pratinjau tampilan manifes gabungan dengan membuka file AndroidManifest.xml di Android Studio, lalu mengklik tab Merged Manifest di bagian bawah editor.

Tampilan Manifes Gabungan menampilkan hasil manifes gabungan di sebelah kiri dan informasi tentang setiap file manifes gabungan di sebelah kanan, seperti yang ditampilkan pada gambar 2. Elemen yang digabungkan dari file manifes yang berprioritas lebih rendah ditandai dengan warna yang berbeda di sebelah kiri. Kunci untuk setiap warna ditetapkan pada bagian Manifest Sources di sebelah kanan.

Gambar 2. Tampilan Manifes Gabungan

File manifes yang merupakan bagian dari build tetapi tidak menyumbangkan elemen atau atribut dicantumkan dalam Other Manifest Files di sebelah kanan.

Untuk melihat informasi tentang asal elemen, klik elemen tersebut di sebelah kiri dan detailnya akan muncul dalam Merging Log di sebelah kanan.

Jika terjadi konflik, detailnya akan muncul dalam Merging Errors di sebelah kanan dengan rekomendasi tentang cara mengatasinya menggunakan penanda aturan penggabungan. Error ini juga dicantumkan di jendela Event Log (pilih View > Tool Windows > Event Log).

Jika ingin melihat log lengkap tentang hierarki keputusan penggabungan, temukan file log dalam direktori build/outputs/logs/ modul Anda, yang bernama manifest-merger-buildVariant-report.txt.

Apendiks: Kebijakan penggabungan

Alat penggabung manifes secara logis dapat mencocokkan setiap elemen XML dari satu file manifes ke elemen yang terkait di file lainnya. Penggabung akan mencocokkan setiap elemen menggunakan "kunci pencocokkan": berupa nilai atribut untuk (misalnya android:name) atau sifat unik alami dari tag tersebut (misalnya, hanya boleh ada satu elemen <supports-screen>). Jika dua manifes memiliki elemen XML yang sama, alat penggabung akan menggabungkan kedua elemen dengan menggunakan salah satu dari tiga kebijakan penggabungan:

Gabungkan

Mengombinasikan semua atribut yang tidak berkonflik ke dalam tag yang sama dan menggabungkan elemen turunan sesuai kebijakan penggabungannya masing-masing. Jika terdapat atribut yang saling bertentangan, gabungkan dengan penanda aturan penggabungan.

Gabungkan hanya turunan

Tidak mengombinasikan atau menggabungkan atribut (hanya mempertahankan atribut yang disediakan oleh file manifes yang berprioritas tertinggi) dan menggabungkan elemen turunan sesuai kebijakan penggabungannya.

Pertahankan

Membiarkan elemen "apa adanya" dan menambahkannya ke elemen induk biasa dalam file gabungan. Kebijakan ini hanya digunakan jika sejumlah deklarasi elemen yang sama diperbolehkan.

Tabel 1 mencantumkan setiap tipe elemen, tipe kebijakan penggabungan yang digunakan, dan kunci yang digunakan untuk menentukan elemen yang cocok di antara kedua manifes.

Tabel 3. Kebijakan penggabungan elemen manifes dan kunci pencocokan