Combinar vários arquivos de manifesto

O arquivo APK pode conter apenas um AndroidManifest.xml, mas o projeto do Android Studio pode conter vários, disponibilizados pelo conjunto de origem principal ou por variantes de compilação e bibliotecas importadas. Ao compilar o app, a compilação do Gradle combina todos os arquivos de manifesto em um único arquivo, empacotado com o APK.

A ferramenta de combinação de manifestos combina todos os elementos XML de cada arquivo seguindo algumas heurísticas de combinação e obedecendo a preferências definidas com atributos XML especiais. Esta página descreve como funciona a combinação de manifestos e como é possível aplicar preferências para resolver conflitos.

Dica: use a visualização Merged Manifest para ver os resultados do manifesto combinado e encontrar erros de conflito.

Prioridades de combinação

A ferramenta de combinação une todos os arquivos de manifesto em um único arquivo, combinando-os sequencialmente de acordo com a prioridade de cada um deles. Por exemplo, se você tem três arquivos de manifesto, o de prioridade mais baixa será combinado ao próximo manifesto de maior prioridade. Por sua vez, esse resultado será combinado ao próximo manifesto de maior prioridade, como mostrado na figura 1.

Figura 1. Processo de combinação de três arquivos de manifesto, da prioridade mais baixa (esquerda) à mais alta (direita)

Há três tipos básicos de arquivos de manifesto que podem ser combinados entre si, com as seguintes prioridades de combinação (prioridade mais alta primeiro):

  1. Arquivo de manifesto para a variante de compilação

    Se você tiver vários conjuntos de origem para sua variante, as prioridades dos manifestos serão as seguintes:

    1. Manifesto da variante de compilação (como src/demoDebug/)
    2. Manifesto do tipo de compilação (como src/debug/)
    3. Manifesto do tipo de produto (como src/demo/)

      Se você estiver usando dimensões de variações, as prioridades dos manifestos corresponderão à ordem em que cada dimensão é listada na propriedade flavorDimensions (a primeira é a mais alta).

  2. Arquivo de manifesto principal para o módulo de app
  3. Arquivo de manifesto de uma biblioteca incluída

    Se você tiver várias bibliotecas, as prioridades dos manifestos corresponderão à ordem das dependências (a ordem em que aparecem no bloco dependencies do Gradle).

Por exemplo, um manifesto de biblioteca é combinado ao manifesto principal. Em seguida, o manifesto principal é combinado ao manifesto da variante de compilação.

Importante: as configurações de compilação do arquivo build.gradle modificam todos os atributos correspondentes no arquivo de manifesto combinado. Por exemplo, a minSdkVersion do arquivo build.gradle modifica o atributo correspondente no elemento de manifesto <uses-sdk>. Para evitar confusão, basta não usar o elemento <uses-sdk> e definir essas propriedades apenas no arquivo build.gradle. Para ver mais detalhes, consulte Configurar sua compilação.

Heurística de conflitos de combinação

A ferramenta de combinação pode associar logicamente cada elemento XML de um manifesto a um elemento correspondente em outro manifesto.(Para saber mais sobre como essa correspondência funciona, consulte o apêndice sobre políticas de combinação).

Se um elemento do manifesto de menor prioridade não corresponder a nenhum elemento no manifesto de maior prioridade, ele será adicionado ao manifesto combinado. Entretanto, se houver um elemento correspondente, a ferramenta de combinação tentará combinar todos os atributos de cada um no mesmo elemento. Se a ferramenta constatar que os dois manifestos contêm o mesmo atributo com valores diferentes, ocorrerá um conflito de combinação.

A tabela 1 mostra os resultados possíveis quando a ferramenta de combinação tenta combinar todos os atributos no mesmo elemento.

Tabela 1. Comportamento padrão de combinação para valores de atributo

Atributo de alta prioridade Atributo de baixa prioridade Resultado combinado do atributo
Nenhum valor Nenhum valor Nenhum valor (usar o valor padrão)
Valor B Valor B
Valor A Nenhum valor Valor A
Valor A Valor A
Valor B Erro de conflito: adicione um marcador de regra de combinação

No entanto, há algumas situações em que a ferramenta de combinação se comporta de maneira diferente para evitar conflitos:

  • Atributos no elemento <manifest> nunca são combinados. Apenas os atributos do manifesto de maior prioridade são usados.
  • O atributo android:required nos elementos <uses-feature> e <uses-library> usa uma combinação OR. Ou seja, se houver um conflito, "true" será aplicado, e o recurso ou biblioteca exigido por um manifesto será sempre incluído.
  • Atributos no elemento <uses-sdk> sempre usam o valor do manifesto de maior prioridade, exceto nas seguintes situações:
    • Quando o manifesto de menor prioridade tem um valor de minSdkVersion maior, ocorre um erro, a menos que você aplique a regra de combinação overrideLibrary.
    • Quando o manifesto de menor prioridade tem um valor de targetSdkVersion menor, a ferramenta de combinação usa o valor do manifesto de maior prioridade, mas também adiciona as permissões de sistema necessárias para o funcionamento correto da biblioteca importada (para casos em que a versão mais recente do Android tenha restrições de permissão mais rígidas). Para saber mais sobre esse comportamento, consulte a seção sobre permissões de sistema implícitas.
  • O elemento <intent-filter> nunca é correspondido entre manifestos. Cada elemento é tratado como único e adicionado ao elemento pai comum no manifesto combinado.

Para todos os outros conflitos entre atributos, você receberá um erro e precisará instruir a ferramenta de combinação sobre a resolução. Para isso, adicione um atributo especial no arquivo de manifesto de maior prioridade (consulte a próxima seção sobre marcadores de regra de combinação).

Não confie nos valores padrão dos atributos. Como todos os atributos únicos são combinados no mesmo elemento, isso poderá gerar resultados inesperados se o manifesto de maior prioridade depender realmente do valor padrão de um atributo sem declará-lo. Por exemplo, se o manifesto de maior prioridade não declarar o atributo android:launchMode, o valor padrão "standard" será utilizado. No entanto, se o manifesto de menor prioridade declarar esse atributo com um valor diferente, esse valor será aplicado ao manifesto combinado (substituindo o valor padrão). Portanto, defina explicitamente cada atributo com o valor adequado. (Os valores padrão de cada atributo estão documentados na Referência de manifestos.)

Marcadores de regra de combinação

Um marcador de regra de combinação é um atributo XML que pode ser usado para indicar sua preferência sobre como resolver conflitos de combinação ou remover elementos e atributos inadequados. O marcador pode ser aplicado a todo um elemento ou apenas a atributos específicos de um elemento.

Na combinação de dois arquivos de manifesto, a ferramenta de combinação procura esses marcadores nos arquivos de manifesto de maior prioridade.

Todos os marcadores pertencem ao namespace tools do Android. Portanto, é necessário declarar primeiro esse namespace no elemento <manifest> da seguinte forma:

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

Marcadores de nó

Para aplicar uma regra de combinação a todo um elemento XML (a todos os atributos de um determinado elemento de manifesto e a todas as tags filhas correspondentes), use os seguintes atributos:

tools:node="merge"
Combinar todos os atributos nessa tag e todos os elementos aninhados quando não há conflitos usando a heurística de conflitos de combinação. Esse é o comportamento padrão para elementos.

Manifesto de baixa prioridade:

    <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>
    

Manifesto de alta prioridade:

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

Resultado do manifesto combinado:

    <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"
Combinar atributos somente nessa tag. Não combinar elementos aninhados.

Manifesto de baixa prioridade:

    <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>
    

Manifesto de alta prioridade:

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

Resultado do manifesto combinado:

    <activity android:name="com.example.ActivityOne"
        android:screenOrientation="portrait"
        android:windowSoftInputMode="stateUnchanged">
    </activity>
    
tools:node="remove"
Remover esse elemento do manifesto combinado. Embora possa parecer que você precise simplesmente excluir esse elemento, é preciso usar esse atributo quando você descobre um elemento desnecessário no manifesto combinado, disponibilizado por um arquivo de manifesto de menor prioridade que está fora do seu controle (como uma biblioteca importada).

Manifesto de baixa prioridade:

    <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>
    

Manifesto de alta prioridade:

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

Resultado do manifesto combinado:

    <activity-alias android:name="com.example.alias">
      <meta-data android:name="duck"
          android:value="@string/quack"/>
    </activity-alias>
    
tools:node="removeAll"
Semelhante a tools:node="remove", mas remove todos os elementos correspondentes a esse tipo de elemento (dentro do mesmo elemento pai).

Manifesto de baixa prioridade:

    <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>
    

Manifesto de alta prioridade:

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

Resultado do manifesto combinado:

    <activity-alias android:name="com.example.alias">
    </activity-alias>
    
tools:node="replace"
Substituir completamente o elemento de menor prioridade. Ou seja, se existir um elemento correspondente no manifesto de menor prioridade, ele será ignorado e o elemento será usado exatamente como aparece neste manifesto.

Manifesto de baixa prioridade:

    <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>
    

Manifesto de alta prioridade:

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

Resultado do manifesto combinado:

    <activity-alias android:name="com.example.alias">
      <meta-data android:name="fox"
          android:value="@string/dingeringeding"/>
    </activity-alias>
    
tools:node="strict"
Gerar um erro de compilação todas as vezes que este elemento no manifesto de menor prioridade não corresponder exatamente ao elemento no manifesto de maior prioridade (a menos que resolvido por outros marcadores de regra de combinação). Isso modifica a heurística de conflitos de combinação. Por exemplo, se o manifesto de menor prioridade simplesmente incluir um atributo extra, a compilação falhará (enquanto que o comportamento padrão adicionará o atributo extra ao manifesto combinado).

Manifesto de baixa prioridade:

    <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>
    

Manifesto de alta prioridade:

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

Isso cria um erro de combinação de manifesto. No modo rígido, os dois elementos de manifesto não podem ter qualquer diferença. Portanto, é necessário aplicar outros marcadores de regra de combinação para resolver essas diferenças. (Normalmente, os dois elementos são combinados sem problemas, como mostrado no exemplo de tools:node="merge" acima.)

Marcadores de atributo

Para aplicar uma regra de combinação apenas a atributos específicos de uma tag de manifesto, use os atributos a seguir. Cada atributo aceita um ou mais nomes (incluindo o namespace do atributo), separados por vírgulas.

tools:remove="attr, ..."
Remover os atributos especificados do manifesto combinado. Embora pareça ser possível simplesmente excluir esses atributos, é necessário usar esse atributo quando o arquivo de manifesto de menor prioridade inclui esses atributos e você quer garantir que eles não entrem no manifesto combinado.

Manifesto de baixa prioridade:

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

Manifesto de alta prioridade:

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

Resultado do manifesto combinado:

    <activity android:name="com.example.ActivityOne"
        android:screenOrientation="portrait">
    
tools:replace="attr, ..."
Substituir os atributos especificados no manifesto de menor prioridade por aqueles deste manifesto. Em outras palavras, manter sempre os valores do manifesto de maior prioridade.

Manifesto de baixa prioridade:

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

Manifesto de alta prioridade:

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

Resultado do manifesto combinado:

    <activity android:name="com.example.ActivityOne"
        android:theme="@newtheme"
        android:exported="true"
        android:screenOrientation="portrait"
        android:windowSoftInputMode="stateUnchanged">
    
tools:strict="attr, ..."
Gerar um erro de compilação sempre que esses atributos no manifesto de menor prioridade não corresponderem exatamente aos do manifesto de maior prioridade. Esse é o comportamento padrão para todos os atributos, exceto os que têm comportamentos especiais, conforme descrito na heurística de conflitos de combinação.

Manifesto de baixa prioridade:

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

Manifesto de alta prioridade:

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

Isso cria um erro de combinação de manifesto. Aplique outros marcadores de regra de combinação para resolver o conflito. Lembre-se de que esse é o comportamento padrão, então o exemplo acima tem o mesmo resultado se você remover tools:strict="screenOrientation".

Também é possível aplicar vários marcadores a um elemento da seguinte maneira:

Manifesto de baixa prioridade:

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

Manifesto de alta prioridade:

    <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">
    

Resultado do manifesto combinado:

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

Seletor de marcadores

Se você quiser aplicar os marcadores de regra de combinação a apenas uma biblioteca importada específica, adicione o atributo tools:selector com o nome do pacote da biblioteca.

Por exemplo, com o manifesto a seguir, a regra de combinação remove será aplicada somente quando o arquivo de manifesto de menor prioridade for da biblioteca com.example.lib1.

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

Se o manifesto de menor prioridade tiver qualquer outra origem, a regra de combinação remove será ignorada.

Observação: se você usar esse atributo com um dos marcadores de atributo, ele será aplicado a todos os atributos especificados no marcador.

Modificar <uses-sdk> para bibliotecas importadas

Por padrão, na importação de uma biblioteca com um valor de minSdkVersion maior que o arquivo de manifesto principal, ocorre um erro e não é possível importar a biblioteca. Para fazer com que a ferramenta de combinação ignore esse conflito e importe a biblioteca, mantendo o valor menor de minSdkVersion do app, adicione o atributo overrideLibrary à tag <uses-sdk>. O valor do atributo pode ser um ou mais nomes de pacotes de biblioteca (separados por vírgulas), indicando as bibliotecas que podem modificar a minSdkVersion do manifesto principal.

Por exemplo, se o manifesto principal do app aplicar overrideLibrary da seguinte maneira:

    <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"/>
    ...
    

O manifesto a seguir poderá ser combinado sem gerar erro relacionado à tag <uses-sdk>, e o manifesto combinado manterá a minSdkVersion="2" do manifesto do app.

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

Permissões de sistema implícitas

Algumas APIs do Android que antes eram acessadas livremente por apps passaram a ser restringidas por permissões de sistema em versões recentes do Android. Para evitar o cancelamento de apps que contam com o acesso a essas APIs, as versões recentes do Android permitem que os apps continuem acessando essas APIs sem a permissão, desde que definam targetSdkVersion com um valor inferior à versão em que a restrição foi implementada. Na prática, esse comportamento concede ao app uma permissão implícita para acessar as APIs. Portanto, isso pode afetar manifestos combinados que têm valores diferentes de targetSdkVersion da seguinte maneira.

Se o arquivo de manifesto de menor prioridade tiver um valor menor de targetSdkVersion que forneça uma permissão implícita e o manifesto de maior prioridade não tiver a mesma permissão implícita (porque targetSdkVersion é maior ou igual à versão em que a restrição foi implementada), a ferramenta de combinação adicionará explicitamente a permissão de sistema ao manifesto combinado.

Por exemplo, se o app definir targetSdkVersion como 4 ou maior e importar uma biblioteca com targetSdkVersion definido como 3 ou menor, a ferramenta de combinação adicionará a permissão WRITE_EXTERNAL_STORAGE ao manifesto combinado. A Tabela 2 lista todas as permissões possíveis que podem ser adicionadas ao manifesto combinado.

Tabela 2. Lista de permissões que a ferramenta de combinação pode adicionar ao manifesto combinado

Declaração do manifesto de menor prioridade Permissões adicionadas ao manifesto combinado
targetSdkVersion é 3 ou menor WRITE_EXTERNAL_STORAGE, READ_PHONE_STATE
targetSdkVersion é 15 ou menor e usa READ_CONTACTS READ_CALL_LOG
targetSdkVersion é 15 ou menor e usa WRITE_CONTACTS WRITE_CALL_LOG

Inspecionar o manifesto combinado e encontrar conflitos

Você pode visualizar o manifesto combinado mesmo antes de criar o APK abrindo o arquivo AndroidManifest.xml no Android Studio e clicando na guia Merged Manifest na parte inferior do editor.

A visualização "Merged Manifest" mostra os resultados do manifesto combinado à esquerda e as informações sobre cada arquivo de manifesto combinado à direita, como mostrado na figura 2. Os elementos combinados dos arquivos de manifesto de menor prioridade são destacados em cores diferentes à esquerda. O significado de cada cor é especificado em Manifest Sources, à direita.

Figura 2. Visualização "Merged Manifest"

Arquivos de manifesto que eram parte da compilação, mas não contribuíram com elementos ou atributos, são listados em Other Manifest Files à direita.

Para ver informações sobre a origem de um elemento, clique nele à esquerda e os detalhes serão exibidos em Merging Log, à direita.

Se ocorrer um conflito, ele será exibido em Merging Errors no lado direito, com uma recomendação sobre como resolver o conflito usando marcadores de regra de combinação. Os erros também são impressos na janela Event Log (selecione View > Tool Windows > Event Log).

Se você quiser ver um registro completo da árvore de decisões de combinação, o arquivo de registros está no diretório build/outputs/logs/ do módulo e é denominado manifest-merger-buildVariant-report.txt.

Apêndice: políticas de combinação

A ferramenta de combinação de manifestos pode associar logicamente cada elemento XML de um arquivo de manifesto a um elemento correspondente em outro arquivo. A ferramenta de combinação corresponde cada elemento usando uma "chave de correspondência": um valor de atributo único (como android:name) ou a unicidade natural da própria tag (por exemplo, pode haver apenas um elemento <supports-screen>). Se dois manifestos tiverem o mesmo elemento XML, a ferramenta combinará os dois elementos usando uma das três políticas de combinação a seguir:

Combinar
Combinar todos os atributos não conflitantes na mesma tag e combinar elementos filhos de acordo com a respectiva política de combinação. Se houver um conflito entre atributos, combiná-los com os marcadores de regra de combinação.
Combinar apenas filhos
Não combinar atributos (manter apenas os atributos disponibilizados pelo arquivo de manifesto de maior prioridade) e combinar elementos filhos de acordo com a política de combinação deles.
Manter
Deixar o elemento "como está" e adicioná-lo ao elemento pai comum no arquivo combinado. Usado apenas quando a existência de várias declarações para o mesmo elemento é aceitável.

A tabela 3 lista cada tipo de elemento, o tipo de política de combinação usada e a chave usada para determinar uma correspondência de elemento entre dois manifestos.

Tabela 3. Políticas e chaves de correspondência de combinação de elementos de manifesto

Elemento Política de combinação Chave de correspondência
<action> Combinar Atributo android:name
<activity> Combinar Atributo android:name
<application> Combinar Há apenas um por <manifest>
<category> Combinar Atributo android:name
<data> Combinar Há apenas um por <intent-filter>
<grant-uri-permission> Combinar Há apenas um por <provider>
<instrumentation> Combinar Atributo android:name
<intent-filter> Manter Sem correspondência; são permitidas várias declarações dentro do mesmo elemento pai
<manifest> Combinar apenas filhos Há apenas um por arquivo
<meta-data> Combinar Atributo android:name
<path-permission> Combinar Há apenas um por <provider>
<permission-group> Combinar Atributo android:name
<permission> Combinar Atributo android:name
<permission-tree> Combinar Atributo android:name
<provider> Combinar Atributo android:name
<receiver> Combinar Atributo android:name
<screen> Combinar Atributo android:screenSize
<service> Combinar Atributo android:name
<supports-gl-texture> Combinar Atributo android:name
<supports-screen> Combinar Há apenas um por <manifest>
<uses-configuration> Combinar Há apenas um por <manifest>
<uses-feature> Combinar Atributo android:name (se ausente, o atributo android:glEsVersion)
<uses-library> Combinar Atributo android:name
<uses-permission> Combinar Atributo android:name
<uses-sdk> Combinar Há apenas um por <manifest>
Elementos personalizados Combinar Sem correspondência; são desconhecidos para a ferramenta de combinação e, portanto, são sempre incluídos no manifesto combinado