Generating VNDK Snapshots

{% include "_versions.html" %}

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.

Snapshot build artifacts

The Android build server generates build artifacts for VNDK snapshots using the following build parameters and build commands.

Build parameters

The build target name is vndk and the build target configuration is as follows:

TARGET_PRODUCT=aosp_{TARGET_ARCH}_ab
TARGET_BUILD_VARIANT=user
TARGET_ARCH. Same as Generic System Image (GSI) target archs (arm, arm64, x86, x86_64).
TARGET_ARCH_VARIANT. For snapshot v27 (Android 8.1), includes popular configurations (listed below); future releases may include other arch/cpu variants.

TARGET_PRODUCT	TARGET_ARCH	TARGET_ARCH_VARIANT
aosp_arm_ab	arm	armv7-a-neon
aosp_arm64_ab	arm64	armv8-a
aosp_x86_ab	x86	x86
aosp_x86_64_ab	x86_64	x86_64

Build commands

For official snapshots, Android {{ androidPVersionNumber }} includes a new dummy 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_<ARCH>_ab-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

VNDK snapshots for an Android Version are generated from the <Android Version>-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 build script (build.sh):
```
$ cd $ANDROID_BUILD_TOP
$ development/vndk/snapshot/build.sh
```

To build one specific TARGET_ARCH:

$ lunch aosp_<ARCH>_ab-user
$ m -j vndk dist

The corresponding android-vndk-<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 are not needed as they are backward compatible.
- For 64bit 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.
Linker config file is ld.config.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.

Example: VNDK snapshot directory structure

The example below shows the directory structure for an arm64 (TARGET_ARCH=arm64) VNDK snapshot zip file (android-vndk-arm64.zip).

Figure 1. VNDK snapshot directory structure (example)

Uploading VNDK snapshots

VNDK snapshots are checked in the source tree under /prebuilts/vndk/v<VER>, where <VER> is equal to the version of the VNDK snapshot (which follows the SDK version of the corresponding Android release). For example, the O MR1 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 pre-built VNDK snapshot to the source tree. This script performs the following tasks:

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

Using locally-built VNDK snapshots

During development, you can use locally-built VNDK snapshots for testing. When the --local option is specified, update.py fetches VNDK snapshot build artifacts from local $DIST_DIR instead of the Android build server. Usage:

$ python update.py <VER> --local

For example, to update the O MR1 VNDK snapshot with local build artifacts, run:

$ python update.py 27 --local

Because local mode is designed for testing only, the script skips the GPL license checking and git commit steps.

Directory structure for prebuilts/vndk

Figure 2. Prebuilts/vndk directory structure

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 /prebuilts/vndk/v<VER> 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 does not 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.

Note: Vendor modules use the current VNDK version of the system source tree, so you must set BOARD_VNDK_VERSION to current.

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, Generic System Image (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 pre-built 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 out/target/product/<board>/system/lib[64]/vndk[-sp]-${VER}. Missing versions generate a build error.

The VNDK modules will not link with the vendor modules at build time but may be used at runtime if the vendor modules in vendor partition require one of the installed VNDK versions. PRODUCT_EXTRA_VNDK_VERSIONS is valid only if BOARD_VNDK_VERSION is defined. For example, to install the O MR1 VNDK snapshot to system.img:

$ m -j PRODUCT_EXTRA_VNDK_VERSIONS=27

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 /system/lib[64]/vndk-$SDK_VER and /system/lib[64]/vndk-sp-$SDK_VER, where $SDK_VER is the version stored in PLATFORM_VNDK_VERSION.

Namespace configuration

The vendor modules search the required shared libraries using the namespace configuration in /etc/ld.config.${VER}.txt (where ${VER} is obtained from the ro.vndk.version property). The namespace configuration has a versioned VNDK directory that uses the following syntax:

/system/${LIB}/vndk-%VNDK_VER%
/system/${LIB}/vndk-sp-%VNDK_VER%

%VNDK_VER% is replaced with PLATFORM_VNDK_VERSION at build time, enabling a system image to provide multiple snapshots for each 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/lib[64]/vndk[-sp]-<CODE_NAME>
Current VNDK modules	`current`	After	<SDK_ver>	<SDK_ver>	/system/lib[64]/vndk[-sp]-<SDK_ver>
Prebuilt snapshot modules	<VNDK_ver> for snapshot	Before or After	<CODE_NAME> or <SDK_ver>	<VNDK_ver>	/system/lib[64]/vndk[-sp]-<VNDK_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.