Gerar snapshots do VNDK

Um snapshot do VNDK é um conjunto de bibliotecas VNDK-core e VNDK-SP para uma versão do Android. Só é possível fazer upgrade da partição do sistema se o system.img incluir o snapshot do VNDK correspondente necessário para o vendor.img.

Os snapshots oficiais do VNDK são criados automaticamente no servidor de build do Android e verificados em /prebuilts/vndk da árvore de origem do Android. Para fins de desenvolvimento, é possível criar snapshots do VNDK localmente. Os snapshots do VNDK têm suporte para os sabores TARGET_ARCH arm, arm64, x86 e x86_64.

Criar snapshots

O servidor de build do Android gera artefatos de build e arquivos de snapshot do VNDK usando os comandos e parâmetros de build a seguir.

Parâmetros do build

O nome do destino de build é vndk. A configuração do destino de build é mostrada abaixo.

TARGET_PRODUCT TARGET_ARCH TARGET_ARCH_VARIANT
aosp_arm arm armv7-a-neon
aosp_arm64 arm64 armv8-a
aosp_x86 x86 x86
aosp_x86_64 x86_64 x86_64
  • TARGET_PRODUCT=aosp_$(TARGET_ARCH)
  • TARGET_BUILD_VARIANT=user
  • TARGET_ARCH é o mesmo que a imagem genérica do sistema (GSI) arquiteturas de destino (arm, arm64, x86, x86_64).
  • TARGET_ARCH_VARIANT. Para o snapshot v28 (Android 9) e versões mais recentes, inclui as configurações comuns listadas acima.

Comandos de build

Para instantâneos oficiais, o Android 9 e versões mais recentes inclui um destino de amostra (vndk) em vndk.mk que cria e gera um snapshot do VNDK para $DIST_DIR. O arquivo ZIP de snapshot usa o formato android-vndk-$(TARGET_ARCH).zip. Exemplo: 

lunch aosp_TARGET_ARCH-user
make -j vndk dist [BOARD_VNDK_VERSION=current]

O servidor de build do Android usa o script build.sh para criar todos os sabores de arquitetura com suporte com o comando abaixo. 

DIST_DIR=dist_dir development/vndk/snapshot/build.sh

O snapshot do VNDK para uma versão do Android é gerado a partir do branch de lançamento dessa versão.

Criar localmente

Durante o desenvolvimento, é possível criar snapshots do VNDK a partir de uma árvore de origem local com os comandos abaixo.

  • Para criar todos os arches com suporte de uma só vez, execute o seguinte script de build (build.sh). 
    cd $ANDROID_BUILD_TOP
development/vndk/snapshot/build.sh
  • Para criar um TARGET_ARCH específico, execute os seguintes comandos. 
    lunch aosp_TARGET_ARCH-user
m -j vndk dist

O arquivo android-vndk-$(TARGET_ARCH).zip correspondente é criado em $DIST_DIR.

Arquivos de snapshot

Um snapshot do VNDK inclui os seguintes arquivos.

  • Variante do fornecedor das bibliotecas compartilhadas VNDK-core e VNDK-SP.
    • As bibliotecas compartilhadas do LL-NDK não são necessárias, porque são compatíveis com versões anteriores.
    • Para destinos de 64 bits, as bibliotecas TARGET_ARCH e TARGET_2ND_ARCH são criadas e incluídas.
  • A lista de bibliotecas VNDK-core, VNDK-SP, LL-NDK e VNDK-private está em [vndkcore|vndksp|llndk|vndkprivate].libraries.txt.
  • Arquivos de licença.
  • module_paths.txt. Registra os caminhos de módulo de todas as bibliotecas do VNDK, o que é necessário para verificar se os projetos GPL têm fontes lançadas em uma determinada árvore de origem do Android.

Para um determinado arquivo ZIP de snapshot do VNDK, android-vndk-$(TARGET_ARCH).zip, as bibliotecas pré-criadas do VNDK são agrupadas em diretórios separados chamados arch-$(TARGET_ARCH)-$(TARGET_ARCH_VARIANT) de acordo com o tamanho do ABI. Por exemplo, para android-vndk-arm64.zip, as bibliotecas de 64 bits são colocadas em arch-arm64-armv8-a e as bibliotecas de 32 bits são colocadas em arch-arm-armv8-a. O exemplo abaixo mostra a estrutura de diretórios de um arquivo ZIP de snapshot do VNDK arm64 (TARGET_ARCH=arm64) (android-vndk-arm64.zip).

Estrutura de diretórios de snapshots do VNDK
Figura 1. Estrutura de diretório de snapshots do VNDK (exemplo)

Criar para snapshots do fornecedor

O Android 11 oferece suporte a instantâneos do fornecedor, que permitem criar vendor.img, independente da versão do Android na árvore de origem. Um snapshot padrão do VNDK contém os arquivos de biblioteca compartilhada (.so) que podem ser instalados em dispositivos e vinculados a partir de binários C++ do fornecedor no tempo de execução. Para criar contra esse snapshot do VNDK, você precisa de outros artefatos, como arquivos de cabeçalho e flags exportadas.

Para gerar esses artefatos (junto com o snapshot do VNDK) de uma árvore de origem local, use o comando abaixo. 

VNDK_SNAPSHOT_BUILD_ARTIFACTS=true development/vndk/snapshot/build.sh

Esse comando cria arquivos android-vndk-$(TARGET_ARCH).zip em $DIST_DIR. O exemplo abaixo é um arquivo ZIP de snapshot do arm64 VNDK com artefatos de build. Os arquivos em negrito são arquivos recém-adicionados ao snapshot normal do VNDK (mostrado na Figura 1) e incluem arquivos JSON (que armazenam cflags de cada biblioteca) e todos os arquivos de cabeçalho exportados. 

android-vndk-arm64.zip
├── arch-arm64-armv8-a
│   └── shared
│       ├── vndk-core  -> *.so files, *.json files
│       └── vndk-sp    -> *.so files, *.json files
├── arch-arm-armv8-a   -> (same as arch-arm64-armv8-a)
├── configs            -> *.libraries.txt, module_paths.txt, module_names.txt
├── include            -> exported header files (*.h, *.hh, etc.)
└── NOTICE_FILES       -> license txt files

Fazer upload de snapshots do VNDK

Os snapshots do VNDK são verificados na árvore de origem em /prebuilts/vndk/vVER, em que VER é igual à versão do snapshot do VNDK (que segue a versão do SDK da versão do Android correspondente). Por exemplo, o snapshot do VNDK do Android 8.1 tem a versão 27.

Usar o script update.py

O script update.py (/development/vndk/snapshot/update.py) automatiza o processo de adicionar um snapshot do VNDK pré-criado à árvore de origem. Ele detecta automaticamente artefatos de build e preenche adequadamente as propriedades associadas no Android.bp gerado. Esse script executa as seguintes tarefas:

  1. Em /prebuilts/vndk/vVER, usa repo start para criar uma nova ramificação do Git.
  2. Busca e descompacta artefatos de build de snapshots do VNDK.
  3. Executa gen_buildfiles.py para gerar automaticamente os arquivos de build (Android.bp).
  4. Executa check_gpl_license.py para verificar se as bibliotecas pré-criadas licenciadas pela Licença Pública Geral (GPL, na sigla em inglês) têm fontes lançadas na árvore de origem atual.
  5. Usa git commit para confirmar novas alterações.

Usar snapshots do VNDK criados localmente

Também é possível usar snapshots do VNDK criados localmente. Quando a opção --local é especificada, o script update.py busca artefatos de build de instantâneos do VNDK do diretório local especificado (em vez do servidor de build do Android) que tem os arquivos android-vndk-$(TARGET_ARCH).zip gerados pelo development/vndk/snapshot/build.sh. Com a opção --local, o script update.py pula a verificação de licença GPL e as etapas git commit.

Sintaxe: 

python update.py VER --local local_path

Exemplo de comando para atualizar o snapshot do VNDK do Android 8.1 com artefatos de build locais em /path/to/local/dir: 

python update.py 27 --local /path/to/local/dir

Exemplo de estrutura de diretório de um snapshot do VNDK criado localmente: 

prebuilts/vndk
├── v30
│   ├── arm64
│   │   ├── arch-arm64-armv8-a -> (prebuilt libs)
│   │   ├── arch-arm-armv8-a   -> (prebuilt libs)
│   │   ├── configs            -> (config files)
│   │   ├── include            -> (exported header files)
│   │   └── Android.bp         -> (VNDK modules with cflags)
│   ├── arm                    -> (same as above)
│   ├── x86_64                 -> (same as above)
│   ├── x86                    -> (same as above)
│   ├── common
│   │   ├── NOTICE_FILES       -> (license files)
│   │   └── Android.bp         -> (license file modules)
│   └── Android.bp             -> (*.libraries.30.txt modules)
└── (other VNDK versions)      -> (same as above)
Os artefatos de build locais são adicionados automaticamente se foram criados com VNDK_SNAPSHOT_BUILD_ARTIFACTS=true.

Instalar snapshots do VNDK

A imagem do sistema instala bibliotecas de snapshot do VNDK no momento da criação usando as informações em BOARD_VNDK_VERSION, PRODUCT_EXTRA_VNDK_VERSIONS e ro.vndk.version. É possível controlar quais snapshots do VNDK são instalados nos diretórios de snapshot pré-criados do VNDK (por exemplo, /prebuilts/vndk/v29 ou /prebuilts/vndk/v30) usando uma das opções a seguir.

  • Opção 1:BOARD_VNDK_VERSION. Use os módulos de snapshot para criar os módulos de fornecedor atuais e instale apenas os módulos de snapshot necessários para os módulos de fornecedor.
  • Opção 2:PRODUCT_EXTRA_VNDK_VERSIONS. Instale os módulos de snapshot do VNDK, independentemente dos módulos de fornecedores atuais. Isso instala os snapshots pré-criados do VNDK listados em PRODUCT_EXTRA_VNDK_VERSIONS sem vinculá-los a outros módulos no momento do build.

Definir BOARD_VNDK_VERSION

BOARD_VNDK_VERSION mostra a versão do VNDK que os módulos de fornecedores atuais precisam para criar. Se BOARD_VNDK_VERSION tiver uma versão de snapshot do VNDK disponível no diretório /prebuilts/vndk, o snapshot do VNDK indicado em BOARD_VNDK_VERSION será instalado. Se o snapshot do VNDK não estiver disponível no diretório, um erro de build vai ocorrer.

A definição de BOARD_VNDK_VERSION também permite que os módulos do VNDK sejam instalados. Os módulos do fornecedor são vinculados à versão de snapshot do VNDK definida em BOARD_VNDK_VERSION no momento do build. Isso não cria módulos atuais do VNDK na origem do sistema. Ao fazer o download da árvore de origem completa de um repositório, as origens do sistema e do fornecedor são baseadas na mesma versão do Android.

Definir PRODUCT_EXTRA_VNDK_VERSIONS

PRODUCT_EXTRA_VNDK_VERSIONS lista as versões extras do VNDK a serem instaladas. Normalmente, basta ter um snapshot do VNDK para a partição do fornecedor atual. No entanto, em alguns casos, talvez seja necessário incluir vários snapshots em uma imagem do sistema. Por exemplo, a GSI tem vários snapshots para oferecer suporte a várias versões de fornecedores com uma imagem do sistema. Ao definir PRODUCT_EXTRA_VNDK_VERSIONS, é possível instalar os módulos de snapshot do VNDK, além da versão do VNDK em BOARD_VNDK_VERSION.

Se PRODUCT_EXTRA_VNDK_VERSIONS tiver uma lista específica de versões, o sistema de build vai procurar snapshots pré-criados da lista de versões no diretório prebuilts/vndk. Se o sistema de build localizar todos os instantâneos listados, ele vai instalar esses arquivos de snapshot em cada APEX do VNDK (out/target/product/$(TARGET_DEVICE)/system_ext/apex/com.android.vndk.vVER). As versões ausentes geram um erro de build.

Os módulos do VNDK não são vinculados aos módulos do fornecedor no momento da criação, mas podem ser usados no momento da execução se os módulos do fornecedor na partição do fornecedor exigirem uma das versões instaladas do VNDK. PRODUCT_EXTRA_VNDK_VERSIONS só é válido se BOARD_VNDK_VERSION estiver definido.

PLATFORM_VNDK_VERSION

PLATFORM_VNDK_VERSION define a versão do VNDK para os módulos atuais do VNDK na origem do sistema. O valor é definido automaticamente:

  • Antes do lançamento, o PLATFORM_VNDK_VERSION é definido como PLATFORM_VERSION_CODENAME.
  • Na versão, PLATFORM_SDK_VERSION é copiado para PLATFORM_VNDK_VERSION.

Depois que a versão do Android é lançada, as bibliotecas atuais do VNDK são instaladas no VNDK APEX (/system/apex/com.android.vndk.vVER), em que VER é a versão armazenada em PLATFORM_VNDK_VERSION.

Quando BOARD_VNDK_VERSION é definido como current, o PLATFORM_VNDK_VERSION é armazenado em ro.vndk.version. Caso contrário, BOARD_VNDK_VERSION é armazenado em ro.vndk.version. PLATFORM_VNDK_VERSION é definido como a versão do SDK quando o Android é lançado. Antes do lançamento, o nome do código alfanumérico do Android é usado para PLATFORM_VNDK_VERSION.

Resumo das configurações da versão do VNDK

A tabela resume as configurações da versão do VNDK.

Fornecedor
Build		 Versão do
board		 SDK
Release		 Versão da
plataforma		 Propriedade
da versão		 Diretório de instalação
Módulos atuais do VNDK current Antes CODE_NAME CODE_NAME /system/apex/com.android.vndk.vCODE_NAME
Depois SDK_VER SDK_VER /system/apex/com.android.vndk.vSDK_VER
Módulos de snapshots predefinidos VNDK_VER
para snapshot		 Antes ou depois CODE_NAME
ou SDK_VER		 VNDK_VER /system_ext/apex/com.android.vndk.vVNDK_VER
  • Versão da placa (BOARD_VNDK_VERSION): versão do VNDK necessária para criar módulos do fornecedor. Defina como current se os módulos do fornecedor puderem ser vinculados aos módulos do sistema atuais.
  • Versão da plataforma (PLATFORM_VNDK_VERSION): versão do VNDK que os módulos do sistema atuais estão criando. Criado apenas quando BOARD_VNDK_VERSION for igual ao atual.
  • Propriedade de versão (ro.vndk.version). Propriedade que especifica a versão do VNDK que os binários e as bibliotecas em vendor.img exigem para serem executados. Armazenado no vendor.img em /vendor/default.prop.