Generating VNDK Snapshots

A VNDK snapshot is a set of VNDK-core and VNDK-SP libs for an Android release. You can upgrade only the system partition if the system.img includes the corresponding VNDK snapshot needed by the vendor.img.

Official VNDK snapshots are built automatically on the Android build server and checked into /prebuilts/vndk of the Android source tree. For development purposes, you can build VNDK snapshots locally. VNDK snapshots are supported for arm, arm64, x86, and x86_64 TARGET_ARCH flavors.

Building snapshots

The Android build server generates build artifacts and VNDK snapshot files using the following build parameters and build commands.

Build parameters

The build target name is vndk. The build target configuration is shown below.

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 is the same as Generic System Image (GSI) target archs (arm, arm64, x86, x86_64).
  • TARGET_ARCH_VARIANT. For snapshot v28 (Android 9) and higher, includes popular configurations listed above.

Build commands

For official snapshots, Android 9 and higher includes a sample target (vndk) in vndk.mk that builds and outputs a VNDK snapshot to $DIST_DIR. The snapshot ZIP file uses the format android-vndk-$(TARGET_ARCH).zip. For example: 

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

The Android build server uses the build.sh script to build all supported arch flavors with the following command. 

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

The VNDK snapshot for an Android version is generated from that version's release branch.

Building locally

During development, you can build VNDK snapshots from a local source tree with the following commands.

  • To build all supported archs at once, execute the following build script (build.sh). 
    cd $ANDROID_BUILD_TOP
development/vndk/snapshot/build.sh
  • To build one specific TARGET_ARCH, execute the following commands. 
    lunch aosp_TARGET_ARCH-user
m -j vndk dist

The corresponding android-vndk-$(TARGET_ARCH).zip file is created under $DIST_DIR.

Snapshot files

A VNDK snapshot includes the following files.

  • Vendor variant of VNDK-core and VNDK-SP shared libraries.
    • LL-NDK shared libs aren't needed as they're backward compatible.
    • For 64 bit targets, both TARGET_ARCH and TARGET_2ND_ARCH libraries are built and included.
  • List of VNDK-core, VNDK-SP, LL-NDK, and VNDK-private libraries is at [vndkcore|vndksp|llndk|vndkprivate].libraries.txt.
  • License files.
  • module_paths.txt. Records the module paths for all VNDK libraries, which is needed for checking that GPL projects have sources released in a given Android source tree.

For a given VNDK snapshot ZIP file, android-vndk-$(TARGET_ARCH).zip, the VNDK prebuilt libraries are grouped in separate directories named arch-$(TARGET_ARCH)-$(TARGET_ARCH_VARIANT) according to ABI bitness. For example, for android-vndk-arm64.zip, the 64-bit libs are placed under arch-arm64-armv8-a and the 32-bit libs are placed under arch-arm-armv8-a. The example below shows the directory structure for an arm64 (TARGET_ARCH=arm64) VNDK snapshot ZIP file (android-vndk-arm64.zip).

VNDK Snapshot Directory Structure
Figure 1. VNDK snapshot directory structure (example)

Building for vendor snapshots

Android 11 supports vendor snapshots, which enable you to build vendor.img regardless of the Android version on the source tree. A default VNDK snapshot contains the shared library files (.so) that can be installed to devices and then linked from vendor C++ binaries in runtime. To build against that VNDK snapshot, you need additional artifacts such as header files and exported flags.

To generate such artifacts (along with the VNDK snapshot) from a local source tree, use the following command. 

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

This command creates android-vndk-$(TARGET_ARCH).zip files under $DIST_DIR. The example below is an arm64 VNDK snapshot ZIP file with build artifacts. The bolded files are newly added files to normal VNDK snapshot (shown in Figure 1) and include JSON files (which store cflags of each library) and all exported header files. 

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

Uploading VNDK snapshots

VNDK snapshots are checked in the source tree under /prebuilts/vndk/vVER, where VER is equal to the version of the VNDK snapshot (which follows the SDK version of the corresponding Android release). For example, the Android 8.1 VNDK snapshot has version 27.

Using the update.py script

The update.py script (/development/vndk/snapshot/update.py) automates the process of adding a prebuilt VNDK snapshot to the source tree. It automatically detects build artifacts and appropriately fills in the associated properties in the generated Android.bp. This script performs the following tasks:

  1. In /prebuilts/vndk/vVER, uses repo start to create new Git branch.
  2. Fetches and unzips VNDK snapshot build artifacts.
  3. Runs gen_buildfiles.py to auto generate the build files (Android.bp).
  4. Runs check_gpl_license.py to verify the prebuilt libraries licensed under the General Public License (GPL) have sources released in current source tree.
  5. Uses git commit to commit new changes.

Using locally built VNDK snapshots

You can also use locally built VNDK snapshots. When the --local option is specified, the update.py script fetches VNDK snapshot build artifacts from local $DIST_DIR (instead of the Android build server) and skips the GPL license checking and git commit steps. To install a locally built VNDK snapshot, navigate to the destination directory and use the update.py script.

Syntax: 

python update.py VER --local

Example command for updating the Android 8.1 VNDK snapshot with local build artifacts: 

python update.py 27 --local

Example directory structure of a locally built VNDK snapshot: 

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)
Local build artifacts are added automatically if artifacts were built with VNDK_SNAPSHOT_BUILD_ARTIFACTS=true.

Installing VNDK snapshots

The system image installs VNDK snapshot libraries at build time using the information in BOARD_VNDK_VERSION, PRODUCT_EXTRA_VNDK_VERSIONS, and ro.vndk.version. You can control which VNDK snapshots get installed from the prebuilt VNDK snapshot directories (for example, /prebuilts/vndk/v29 or /prebuilts/vndk/v30) using one of the following options.

  • Option 1: BOARD_VNDK_VERSION. Use the snapshot modules for building the current vendor modules and install only the snapshot modules that are required for the vendor modules.
  • Option 2: PRODUCT_EXTRA_VNDK_VERSIONS. Install the VNDK snapshot modules regardless of the current vendor modules. This installs the prebuilt VNDK snapshots listed in PRODUCT_EXTRA_VNDK_VERSIONS without linking them to any other modules at build time.

Setting BOARD_VNDK_VERSION

BOARD_VNDK_VERSION shows the VNDK version that current vendor modules are required to build. If BOARD_VNDK_VERSION has an available VNDK snapshot version in /prebuilts/vndk directory, the VNDK snapshot indicated in BOARD_VNDK_VERSION is installed. If the VNDK snapshot is not available in the directory, a build error occurs.

Defining BOARD_VNDK_VERSION also enables the VNDK modules to be installed. Vendor modules link with the VNDK snapshot version defined in BOARD_VNDK_VERSION at build time (this doesn't build current VNDK modules in the system source). When downloading the full source tree from a repository, both system and vendor sources are based on the same Android release.

Setting PRODUCT_EXTRA_VNDK_VERSIONS

PRODUCT_EXTRA_VNDK_VERSIONS lists the extra VNDK versions to be installed. Normally it is enough to have one VNDK snapshot for the current vendor partition. However, in some cases you might need to include multiple snapshots in one system image. For example, the GSI has multiple snapshots to support multiple vendor versions with one system image. By setting PRODUCT_EXTRA_VNDK_VERSIONS, you can install the VNDK snapshot modules in addition to the VNDK version in BOARD_VNDK_VERSION.

If PRODUCT_EXTRA_VNDK_VERSIONS has a specific list of versions, the build system looks for prebuilt snapshots of the version list in the prebuilts/vndk directory. If the build system locates all listed snapshots, it installs those snapshot files to each VNDK APEX (out/target/product/$(TARGET_DEVICE)/system_ext/apex/com.android.vndk.vVER. Missing versions generate a build error.

The VNDK modules don't link with the vendor modules at build time but can be used at runtime if the vendor modules in the vendor partition require one of the installed VNDK versions. PRODUCT_EXTRA_VNDK_VERSIONS is valid only if BOARD_VNDK_VERSION is defined.

PLATFORM_VNDK_VERSION

PLATFORM_VNDK_VERSION defines the VNDK version for current VNDK modules in the system source. The value is set automatically:

  • Prior to release, the PLATFORM_VNDK_VERSION is set as PLATFORM_VERSION_CODENAME.
  • At release, PLATFORM_SDK_VERSION is copied to PLATFORM_VNDK_VERSION.

After the Android version is released, the current VNDK libraries are installed to VNDK APEX (/system/apex/com.android.vndk.vVER), where VER is the version stored in PLATFORM_VNDK_VERSION.

When BOARD_VNDK_VERSION is set to current, the PLATFORM_VNDK_VERSION is stored in ro.vndk.version, otherwise BOARD_VNDK_VERSION is stored in ro.vndk.version. PLATFORM_VNDK_VERSION is set to the SDK version when Android releases; prior to release, the alphanumeric Android code name is used for PLATFORM_VNDK_VERSION.

Summary of VNDK version settings

The table below summarizes the VNDK version settings.

Vendor
Build		 Board
Version		 SDK
Release		 Platform
Version		 Version
Property		 Install Directory
Current VNDK modules current Before CODE_NAME CODE_NAME /system/apex/com.android.vndk.vCODE_NAME
After SDK_VER SDK_VER /system/apex/com.android.vndk.vSDK_VER
Prebuilt snapshot modules VNDK_VER
for snapshot		 Before or After CODE_NAME
or SDK_VER		 VNDK_VER /system_ext/apex/com.android.vndk.vVNDK_VER
  • Board Version (BOARD_VNDK_VERSION). VNDK version that vendor modules require to build. Set to current if vendor modules can link with current system modules.
  • Platform Version (PLATFORM_VNDK_VERSION). VNDK version that current system modules are building. Built only when BOARD_VNDK_VERSION equals current.
  • Version Property (ro.vndk.version). Property that specifies the VNDK version the binaries and libs in vendor.img require to run. Stored in the vendor.img at /vendor/default.prop.