AAPT2

O AAPT2 (Android Asset Packaging Tool) é uma ferramenta de compilação que o Android Studio e o Android Gradle Plugin usam para compilar e empacotar recursos de apps. O AAPT2 analisa, indexa e compila os recursos em um formato binário que é otimizado para a plataforma Android.

O Android Gradle Plugin 3.0.0 e versões posteriores ativam o AAPT2 por padrão, e normalmente você não precisará invocar o aapt2. No entanto, se você preferir usar seu terminal e seu próprio sistema de compilação no Android Studio, poderá usar o AAPT2 a partir da linha de comando. Também é possível depurar erros de compilação relacionados ao AAPT2 a partir da linha de comando. Para isso, o AAPT2 está disponível como uma ferramenta autônoma no Android SDK Build Tools 26.0.2 e versões posteriores.

Para fazer o download do Android SDK Build Tools na linha de comando, use o sdkmanager e execute o comando:

    sdkmanager "build-tools;build-tools-version"
    

Depois de fazer o download do SDK Build Tools, você encontrará o AAPT2 em android_sdk/build-tools/version/. Como revisões do Android SDK Build Tools não são lançadas com muita frequência, a versão do AAPT2 incluída no SDK Build Tools pode não ser a mais recente. Para saber como instalar a versão mais recente do AAPT2, consulte Fazer o download do AAPT2 no Google Maven.

Para usar o AAPT2 a partir da linha de comando no Linux ou Mac, execute o comando aapt2. No Windows, execute o comando aapt2.exe. O AAPT2 é compatível com uma compilação mais rápida de recursos ao permitir a compilação incremental. Isso é feito dividindo o processamento de recursos em duas etapas:

  • Compile: compila arquivos de recursos em formatos binários.
  • Link: mescla todos os arquivos compilados e compacta-os em um único pacote.

Essa divisão ajuda a melhorar o desempenho de compilações incrementais. Por exemplo, se houver alterações em um único arquivo, você precisará recompilar somente esse arquivo.

Fazer o download do AAPT2 no Google Maven

Para instalar a versão mais recente do AAPT2 que não está incluída no SDK Build Tools, faça o download do AAPT2 no repositório Maven do Google da seguinte maneira:

  1. Navegue até com.android.tools.build > aapt2 no índice do repositório.
  2. Copie o nome da versão mais recente do AAPT2.
  3. Insira o nome da versão que você copiou no seguinte URL e especifique seu sistema operacional de destino: https://dl.google.com/dl/android/maven2/com/android/tools/build/aapt2/aapt2-version/aapt2-aapt2-version-[windows | linux | osx].jar

    Por exemplo, para fazer o download da versão 3.2.0-alpha18-4804415 para Windows, use: https://dl.google.com/dl/android/maven2/com/android/tools/build/aapt2/3.2.0-alpha18-4804415/aapt2-3.2.0-alpha18-4804415-windows.jar

  4. Navegue até o URL em um navegador. O download do AAPT2 será iniciado em breve.

  5. Descompacte o arquivo JAR que você acabou de transferir. O arquivo JAR terá um executável aapt2 e algumas bibliotecas das quais o executável depende.

Compile

O AAPT2 é compatível com a compilação de todos os tipos de recursos do Android, como drawables e arquivos XML. Ao invocar o AAPT2 para compilação, você precisa passar um único arquivo de recurso como entrada por invocação. Em seguida, o AAPT2 analisa o arquivo e gera um arquivo binário intermediário com extensão .flat.

Embora seja possível passar diretórios de recursos com mais de um arquivo de recursos para o AAPT2 usando a sinalização --dir, ao fazer isso você não terá o benefício da compilação incremental de recursos. Ou seja, ao passar diretórios inteiros, o AAPT2 recompila todos os arquivos do diretório, mesmo quando apenas um recurso foi alterado.

Os tipos de arquivo de saída podem ser diferentes com base na entrada fornecida para compilação. Isso é explicado na tabela abaixo:

Entrada Saída
Arquivos de recursos XML, como String e Style, localizados no diretório res/values/. Tabela de recursos com *.asrc.flat como extensão.
Todos os outros arquivos de recursos. Todos os arquivos, exceto os arquivos no diretório res/values/, são convertidos em arquivos XML binários com a extensão *.flat. Além disso, todos os arquivos PNG são processados por padrão e adotam a extensão *.png.flat . Se você não quiser compactar PNGs, poderá usar a opção --no-crunch durante a compilação.

Os arquivos de saída AAPT2 não são executáveis. É necessário incluir esses arquivos binários posteriormente como entrada na fase de vinculação a fim de gerar um APK. No entanto, o arquivo APK gerado não é um executável que pode ser implantado em um dispositivo Android imediatamente, porque ele não contém arquivos DEX (bytecode compilado) e não está assinado.

Sintaxe de compile

A sintaxe geral para usar compile é a seguinte:

    aapt2 compile path-to-input-files [options] -o output-directory/
    

No exemplo a seguir, o AAPT2 compila arquivos de recursos chamados values.xml e myImage.png individualmente:

    aapt2 compile project_root/module_root/src/main/res/values-en/
    strings.xml -o compiled/
    aapt2 compile project_root/module_root/src/main/res/drawable
    /myImage.png -o compiled/
    

Como mostrado na tabela acima, o nome do arquivo de saída depende do nome do arquivo de entrada e do nome do diretório pai (o tipo e a configuração do recurso). Para o exemplo acima com strings.xml como entrada, o aapt2 nomeia automaticamente o arquivo de saída como values-en_strings.arsc.flat. Por outro lado, o nome do arquivo do drawable compilado que fica armazenado no diretório drawable será drawable_img.png.flat.

Opções de compile

Há várias opções que você pode usar com o comando compile, como mostrado na tabela abaixo:

Opção Descrição
-o path Especifica o caminho de saída para os recursos compilados.

Essa é uma sinalização obrigatória porque você precisa especificar um caminho para um diretório em que o AAPT2 pode gerar e armazenar os recursos compilados.

--dir directory Especifica o diretório para procurar recursos.

Embora você possa usar essa sinalização para compilar vários arquivos de recursos com um comando, ela desativa os benefícios da compilação incremental e, portanto, não é recomendável usá-la em projetos grandes.

--pseudo-localize Gera versões pseudolocalizadas de strings padrão, como en-XA e en-XB.
--no-crunch Desativa o processamento de PNG.

Use essa opção se você já tiver processado os arquivos PNG ou se estiver criando compilações de depuração que não precisem de redução de tamanho de arquivo. A ativação dessa opção resulta em uma execução mais rápida, mas aumenta o tamanho do arquivo de saída.

--legacy Trata erros que são permitidos como avisos ao usar versões anteriores do AAPT.

Essa sinalização precisa ser usada para erros inesperados de tempo de compilação. Para resolver alterações de comportamento conhecidas que podem ocorrer durante o uso do AAPT2, leia Alterações de comportamento durante o uso do AAPT2.

-v Ativa o registro detalhado.

Na fase de vinculação, o AAPT2 mescla todos os arquivos intermediários gerados na fase de compilação, como tabelas de recursos, arquivos XML binários e arquivos PNG processados, e compacta-os em um único APK. Além disso, outros arquivos auxiliares, como R.java e arquivos de regras ProGuard, podem ser gerados durante essa fase. No entanto, o APK gerado não contém bytecode DEX e não está assinado. Ou seja, não é possível implantar esse APK em um dispositivo. Se você não estiver usando o Android Gradle Plugin para compilar o app a partir da linha de comando, poderá usar outras ferramentas de linha de comando, como d8 para compilar bytecode Java no bytecode DEX e apksigner para assinar o APK.

A sintaxe geral para usar link é a seguinte:

    aapt2 link path-to-input-files [options] -o
    outputdirectory/outputfilename.apk --manifest AndroidManifest.xml
    

No exemplo a seguir, o AAPT2 mescla os dois arquivos intermediários drawable_Image.flat e values_values.arsc.flat com o arquivo AndroidManifest.xml. O AAPT2 vincula o resultado ao arquivo android.jar, que contém os recursos definidos no pacote Android:

     aapt2 link -o output.apk
     -I android_sdk/platforms/android_version/android.jar
        compiled/res/values_values.arsc.flat
        compiled/res/drawable_Image.flat --manifest /path/to/AndroidManifest.xml -v
    

Você pode usar as seguintes opções com o comando link:

Opção Descrição
-o path Especifica o caminho de saída do APK de recurso vinculado.

Essa é uma sinalização obrigatória porque você precisa especificar o caminho para o APK de saída que pode armazenar os recursos vinculados.

--manifest file Especifica o caminho para o arquivo de manifesto do Android a ser criado.

Essa é uma sinalização obrigatória porque o arquivo de manifesto inclui informações essenciais sobre seu app, como o nome do pacote e o ID do aplicativo.

-I Fornece o caminho para o android.jar da plataforma ou outros APKs, como framework-res.apk, que podem ser úteis para a criação de recursos.

Essa sinalização é obrigatória se você estiver usando atributos com namespace android (por exemplo, android:id) nos seus arquivos de recursos.
-A directory Especifica um diretório de assets a ser incluído no APK.

Você pode usar esse diretório para armazenar arquivos originais não processados. Para saber mais, leia Acessar arquivos originais.

-R file Passa um arquivo .flat a ser vinculado usando a semântica overlay sem a sinalização <add-resource> .

Ao fornecer um arquivo de recurso que se sobrepõe a um arquivo existente (estendendo-o ou modificando-o), o último recurso em conflito fornecido será usado.

--package-id package-id Especifica o código do pacote a ser usado para seu app.

O código do pacote especificado precisa ser maior ou igual a 0x7f, a menos que seja usado em combinação com --allow-reserved-package-id.

--allow-reserved-package-id Permite o uso de um código de pacote reservado.

Códigos de pacotes reservados são normalmente atribuídos a bibliotecas compartilhadas e estão no intervalo de 0x02 a 0x7e inclusive. Ao usar --allow-reserved-package-id, você poderá atribuir códigos que se enquadrem no intervalo de códigos de pacotes reservados.

Essa opção só deve ser usada para pacotes com uma versão min-sdk de 26 ou menor.

--java directory Especifica o diretório no qual gerar R.java.
--proguard proguard_options Gera o arquivo de saída para as regras do ProGuard.
--proguard-conditional-keep-rules Gera o arquivo de saída para as regras do ProGuard para o principal dex.
--no-auto-version Desativa o controle de versões automático de estilo e layout de SDK.
--no-version-vectors Desativa o controle de versões automático de drawables de vetor. Use somente ao criar seu APK com a biblioteca Vector Drawable.
--no-version-transitions Desativa o controle de versões automático dos recursos de transição. Use somente ao criar seu APK com a biblioteca Transition Support.
--no-resource-deduping Desativa a desduplicação automática de recursos com valores idênticos em todas as configurações compatíveis.
--enable-sparse-encoding Permite a codificação de entradas esparsas usando uma árvore de pesquisa binária. Isso é útil para otimizar o tamanho do APK, mas à custa do desempenho da recuperação de recursos.
-z Requer localização de strings marcadas como "suggested".
-c config Fornece uma lista de configurações separadas por vírgulas.

Por exemplo, se você tiver dependências na biblioteca de suporte (que contém traduções para vários idiomas), poderá filtrar recursos apenas para a configuração de idioma fornecida, como inglês ou espanhol.

Você precisa definir a configuração de idioma por um código de idioma ISO 639-1 de duas letras, opcionalmente seguido por um código de região ISO 3166-1-alfa-2 de duas letras precedido por "r" minúsculo (por exemplo, en-rUS).

--preferred-density density Permite que o AAPT2 selecione a densidade de correspondência mais próxima e remova todas as outras.

Existem vários qualificadores de densidade de pixel disponíveis para uso no seu app, como ldpi, hdpi e xhdpi. Quando você especifica uma densidade preferencial, o AAPT2 seleciona e armazena a densidade de correspondência mais próxima na tabela de recursos e remove todas as outras.

--output-to-dir Gera o conteúdo do APK para um diretório especificado por -o.

Se houver algum erro durante o uso dessa sinalização, você poderá resolvê-lo atualizando para o Android SDK Build Tools 28.0.0 ou posterior.

--min-sdk-version min-sdk-version Define a versão mínima padrão do SDK a ser usada no AndroidManifest.xml.
--target-sdk-version target-sdk-version Define a versão do SDK de destino padrão a ser usada no AndroidManifest.xml.
--version-code version-code Especifica o código da versão (número inteiro) a ser injetado no AndroidManifest.xml se nenhum estiver presente.
--compile-sdk-version-name compile-sdk-version-name Especifica o nome da versão a ser injetada no AndroidManifest.xml se nenhum estiver presente.
--proto-format Gera recursos compilados no formato Protobuf.

Adequado como entrada para bundletool para gerar um Android App Bundle.

--non-final-ids Gera R.java com códigos de recursos não finais (referências aos códigos do app não serão embutidas durante a compilação em kotlinc/javac).
--emit-ids path Emite um arquivo no caminho fornecido com uma lista de nomes de tipos de recursos e os respectivos mapeamentos de código. É apropriado para uso com --stable-ids.
--stable-ids outputfilename.ext Consome o arquivo gerado por --emit-ids que contém a lista de nomes de tipos de recursos e os respectivos códigos designados.

Essa opção permite que os códigos atribuídos permaneçam estáveis mesmo quando você exclui ou adiciona novos recursos durante a vinculação.

--custom-package package_name Especifica o pacote Java personalizado no qual gerar R.java.
--extra-packages package_name Gera o mesmo arquivo R.java, mas com nomes de pacotes diferentes.
--add-javadoc-annotation annotation Adiciona uma anotação JavaDoc a todas as classes Java geradas.
--output-text-symbols path Gera um arquivo de texto contendo os símbolos de recurso da classe R no arquivo especificado.

Você precisa especificar o caminho para o arquivo de saída.

--auto-add-overlay Permite o acréscimo de novos recursos em sobreposições sem usar a tag <add-resource> .
--rename-manifest-package manifest-package Renomeia o pacote em AndroidManifest.xml.
--rename-instrumentation-target-package instrumentation- target-package Altera o nome do pacote de destino para instrumentation.

Precisa ser usado em conjunto com --rename-manifest-package.

-0 extension

Especifica as extensões de arquivos que você não quer compactar.

--split path:config[,config[..]] Divide recursos com base em um conjunto de configurações para gerar uma versão diferente do APK.

É preciso especificar o caminho para o APK de saída, juntamente com o conjunto de configurações.

-v Permite maior detalhamento da saída.

Dump

dump é usado para imprimir informações de recursos e manifestos sobre o APK gerado pelo comando link. Você pode imprimir as informações no seu console usando o dump como mostrado abaixo:

    aapt2 dump output.apk
    

Sintaxe de dump

A sintaxe geral para usar dump é a seguinte:

    aapt2 dump filename.apk [options]
    

Opções de dump

Você pode usar as seguintes opções com dump:

OpçãoDescrição
--no-values Suprime a saída de valores ao exibir recursos.
--file file Especifica um arquivo como argumento a ser removido do APK.
-v Aumenta o detalhamento da saída.

Alterações de comportamento durante o uso do AAPT2

Antes do AAPT2, o AAPT era a versão padrão do Android Asset Packaging Tool, que agora ficou obsoleta. Embora o AAPT2 deva funcionar imediatamente com projetos antigos, esta seção descreve algumas alterações de comportamento que é preciso conhecer.

Hierarquias de elementos no manifesto do Android

Nas versões anteriores do AAPT, os elementos aninhados em nós incorretos no manifesto do Android eram ignorados ou geravam um aviso. Por exemplo, considere a seguinte amostra:

    <manifest xmlns:android="http://schemas.android.com/apk/res/android"
       package="com.example.myname.myapplication">
       <application
           ...
           <activity android:name=".MainActivity">
               <intent-filter>
                   <action android:name="android.intent.action.MAIN" />
                   <category android:name="android.intent.category.LAUNCHER" />
               </intent-filter>
               <action android:name="android.intent.action.CUSTOM" />
           </activity>
       </application>
    </manifest>
    

As versões anteriores do AAPT simplesmente ignoravam a tag <action> posicionada incorretamente. No entanto, com o AAPT2, ocorre o seguinte erro:

    AndroidManifest.xml:15: error: unknown element <action> found.
    

Para resolver o problema, verifique se os elementos do manifesto estão aninhados corretamente. Para mais informações, leia Estrutura do arquivo do manifesto.

Declaração de recursos

Não é mais possível indicar o tipo de recurso no atributo name. Por exemplo, o código abaixo declara incorretamente um item de recurso attr:

    <style name="foo" parent="bar">
        <item name="attr/my_attr">@color/pink</item>
    </style>
    

A declaração de um tipo de recurso dessa forma resulta no seguinte erro de compilação:

    Error: style attribute 'attr/attr/my_attr (aka my.package:attr/attr/my_attr)'
    not found.
    

Para resolver esse erro, declare explicitamente o tipo usando type="attr":

    <style name="foo" parent="bar">
      <item type="attr" name="my_attr">@color/pink</item>
    </style>
    

Além disso, ao declarar um elemento <style>, o pai dele também precisa ser um tipo de recurso style. Caso contrário, ocorrerá um erro semelhante ao seguinte:

    Error: (...) invalid resource type 'attr' for parent of style
    

Namespace do Android com ForegroundLinearLayout

ForegroundLinearLayout inclui três atributos: foregroundInsidePadding, android:foreground e android:foregroundGravity. Observe que foregroundInsidePadding não está incluído no namespace android, ao contrário dos outros dois atributos.

Nas versões anteriores do AAPT, o compilador ignorava silenciosamente atributos foregroundInsidePadding quando definidos com o namespace android. Ao usar AAPT2, o compilador detecta isso antecipadamente e gera o seguinte erro de compilação:

    Error: (...) resource android:attr/foregroundInsidePadding is private
    

Para resolver esse problema, basta substituir android:foregroundInsidePadding por foregroundInsidePadding.

Uso incorreto de símbolos de referência de recursos @

O AAPT2 gera erros de compilação quando você omite ou posiciona incorretamente símbolos de referência de recursos (@). Por exemplo, considere a omissão do símbolo ao especificar um atributo de estilo, como mostrado a seguir:

    <style name="AppTheme" parent="Theme.AppCompat.Light.DarkActionBar">
      ...
      <!-- Note the missing '@' symbol when specifying the resource type. -->
      <item name="colorPrimary">color/colorPrimary</item>
    </style>
    

Ao compilar o módulo, o AAPT2 gera o seguinte erro de compilação:

    ERROR: expected color but got (raw string) color/colorPrimary
    

Além disso, considere a inclusão incorreta do símbolo ao acessar um recurso do namespace android, como mostrado a seguir:

    ...
    <!-- When referencing resources from the 'android' namespace, omit the '@' symbol. -->
    <item name="@android:windowEnterAnimation"/>
    

Ao compilar o módulo, o AAPT2 gera o seguinte erro de compilação:

    Error: style attribute '@android:attr/windowEnterAnimation' not found
    

Configuração incorreta de bibliotecas

Se seu app tiver uma dependência de uma biblioteca de terceiros criada com versões mais antigas do Android SDK Build Tools, ele poderá ter falha no tempo de execução sem exibir erros ou avisos. Essa falha pode ocorrer porque, durante a criação da biblioteca, os campos R.java são declarados final e, como resultado, todos os códigos de recursos são embutidos nas classes da biblioteca.

O AAPT2 depende da possibilidade de reatribuir códigos aos recursos da biblioteca ao criar o app. Se a biblioteca presumir que os códigos são final e embuti-los no dex da biblioteca, haverá uma incompatibilidade no tempo de execução.

Para resolver esse erro, entre em contato com o autor da biblioteca para que ele a recrie usando a versão mais recente do Android SDK Build Tools e publique-a novamente.