VNDK 构建系统支持

在 Android 8.1 及更高版本中,构建系统内置了 VNDK 支持。如果启用了 VNDK 支持,构建系统就会检查各模块之间的依赖关系,为供应商模块构建特定于供应商的变体,并自动将这些模块安装到指定目录中。

VNDK 构建支持示例

在此示例中,Android.bp 模块的定义部分定义了一个名为 libexample 的库。vendor_available 属性指示框架模块和供应商模块可以依赖于 libexample

设置 vendor_available:true 和 vndk.enabled:true 的 libexample

图 1. 已启用 VNDK 支持

框架可执行文件 /system/bin/foo 和供应商可执行文件 /vendor/bin/bar 均依赖于 libexample,并在其 shared_libs 属性中指定了 libexample

如果框架模块和供应商模块均使用 libexample,将会构建 libexample 的两个变体。核心变体(以 libexample 命名)由框架模块使用,供应商变体(以 libexample.vendor 命名)由供应商模块使用。这两个变体将安装到不同的目录中:

  • 核心变体将安装到 /system/lib[64]/libexample.so 中。
  • 供应商变体将安装到 VNDK APEX 中,因为 vndk.enabledtrue

如需了解详情,请参阅模块定义

配置构建支持

如需为产品设备启用全面的构建系统支持,请将 BOARD_VNDK_VERSION 添加到 BoardConfig.mk

BOARD_VNDK_VERSION := current

此设置具有全局效应:如果在 BoardConfig.mk 中定义,系统会检查所有模块。由于没有将违规模块列入黑名单或白名单的机制,因此在添加 BOARD_VNDK_VERSION 之前,应清除所有不必要的依赖项。您可以通过在环境变量中设置 BOARD_VNDK_VERSION 来测试和编译模块:

$ BOARD_VNDK_VERSION=current m module_name.vendor

如果启用 BOARD_VNDK_VERSION,系统会移除多个默认的全局头文件搜索路径。其中包括:

  • frameworks/av/include
  • frameworks/native/include
  • frameworks/native/opengl/include
  • hardware/libhardware/include
  • hardware/libhardware_legacy/include
  • hardware/ril/include
  • libnativehelper/include
  • libnativehelper/include_deprecated
  • system/core/include
  • system/media/audio/include

如果某个模块依赖于上述目录中的头文件,您必须指明与 header_libsstatic_libs 和/或 shared_libs 的依赖关系。

VNDK APEX

在 Android 10 及更低版本中,设置了 vndk.enabled 的模块安装在 /system/lib[64]/vndk[-sp]-${VER} 中。在 Android 11 及更高版本中,VNDK 库打包为 APEX 格式,且 VNDK APEX 的名称为 com.android.vndk.v${VER}。VNDK APEX 可以是扁平化的,也可以是非扁平化的,具体取决于设备配置;VNDK APEX 可从规范路径 /apex/com.android.vndk.v${VER} 中获取。

VNDK APEX

图 2. VNDK APEX

模块定义

如需使用 BOARD_VNDK_VERSION 构建 Android,您必须在 Android.mkAndroid.bp 中修改模块定义。此部分介绍了不同种类的模块定义,一些与 VNDK 相关的模块属性,以及在构建系统中实现的依赖项检查。

供应商模块

供应商模块是特定于供应商的可执行文件或共享库(必须将这些模块安装到供应商分区中)。在 Android.bp 文件中,供应商模块必须将 vendor 或 proprietary 属性设为 true。在 Android.mk 文件中,供应商模块必须将 LOCAL_VENDOR_MODULELOCAL_PROPRIETARY_MODULE 设为 true

如果定义了 BOARD_VNDK_VERSION,构建系统不允许在供应商模块和框架模块之间建立依赖关系,并且构建系统会在以下情况下发出错误:

  • 未设置 vendor:true 的模块依赖于设置了 vendor:true 的模块,或
  • 设置了 vendor:true 的模块依赖于既未设置 vendor:true 也未设置 vendor_available:true 的非 llndk_library 模块。

依赖项检查适用于 Android.bp 中的 header_libsstatic_libsshared_libs,以及 Android.mk 中的 LOCAL_HEADER_LIBRARIESLOCAL_STATIC_LIBRARIESLOCAL_SHARED_LIBRARIES

LL-NDK

LL-NDK 共享库是具有稳定 ABI 的共享库。框架模块和供应商模块具有相同的最新实现。对于每个 LL-NDK 共享库,Android.bp 都包含一个 llndk_library 模块定义:

llndk_library {
    name: "libvndksupport",
    symbol_file: "libvndksupport.map.txt",
}

该模块定义指定了模块名称和符号文件,后者描述了对供应商模块可见的符号。例如:

LIBVNDKSUPPORT {
  global:
    android_load_sphal_library; # llndk
    android_unload_sphal_library; # llndk
  local:
    *;
};

构建系统会根据符号文件为供应商模块生成存根共享库。如果启用了 BOARD_VNDK_VERSION,供应商模块将与这些存根共享库建立关联。符号只有在满足以下条件时,才会包含在桩共享库中:

  • 未在以 _PRIVATE_PLATFORM 结尾的部分中定义,
  • 不带 #platform-only 标记,且
  • 不带 #introduce* 标记或者该标记与目标匹配。

VNDK

Android.bp 文件中,cc_librarycc_library_staticcc_library_sharedcc_library_headers 模块定义支持三个与 VNDK 相关的属性:vendor_availablevndk.enabledvndk.support_system_process

如果 vendor_availablevndk.enabled 设为 true,可以构建两个变体(核心变体和供应商变体)。核心变体应被视为框架模块,而供应商变体应被视为供应商模块。如果某些框架模块依赖于此模块,将会构建核心变体。如果某些供应商模块依赖于此模块,将会构建供应商变体。构建系统会强制执行以下依赖项检查:

  • 核心变体始终供框架专用,供应商模块无法访问。
  • 供应商变体始终无法供框架模块访问。
  • 供应商变体的所有依赖项(在 header_libsstatic_libs 和/或 shared_libs 中指定)必须为 llndk_library 或者设置了 vendor_availablevndk.enabled 的模块。
  • 如果 vendor_available 设为 true,供应商变体可供所有供应商模块使用。
  • 如果 vendor_available 设为 false,供应商变体仅可供其他 VNDK 或 VNDK-SP 模块使用(即,设置了 vendor:true 的模块无法与设置了 vendor_available:false 的模块相关联)。

cc_librarycc_library_shared 的默认安装路径由以下规则确定:

  • 核心变体将安装到 /system/lib[64] 中。
  • 供应商变体安装路径可能会有所不同:
    • 如果 vndk.enabled 设置为 false,供应商变体将安装到 /vendor/lib[64] 中。
    • 如果 vndk.enabled 设置为 true,供应商变体将安装到 VNDK APEX (com.android.vndk.v${VER}) 中。

下表总结了构建系统如何处理供应商变体:

vendor_available vndk
enabled
vndk
support_same_process
供应商变体说明
true false false 供应商变体为 VND-ONLY。共享库将安装到 /vendor/lib[64] 中。
true 无效(构建错误)
true false 供应商变体为 VNDK。共享库将安装到 VNDK APEX 中。
true 供应商变体为 VNDK-SP。共享库将安装到 VNDK APEX 中。

false

false

false

没有供应商变体。此模块为 FWK-ONLY。

true 无效(构建错误)
true false 供应商变体为 VNDK-Private。共享库将安装到 VNDK APEX 中。供应商模块不得直接使用这些变体。
true 供应商变体为 VNDK-SP-Private。共享库将安装到 VNDK APEX 中。供应商模块不得直接使用这些变体。

VNDK 扩展

VNDK 扩展是具有额外 API 的 VNDK 共享库。这些扩展将安装到 /vendor/lib[64]/vndk[-sp](不带版本后缀)中,并在系统运行时替换原始的 VNDK 共享库。

定义 VNDK 扩展

在 Android 9 及更高版本中,Android.bp 原生支持 VNDK 扩展。如需构建 VNDK 扩展,请定义另一个设置了 vendor:true 且具有 extends 属性的模块:

cc_library {
    name: "libvndk",
    vendor_available: true,
    vndk: {
        enabled: true,
    },
}

cc_library {
    name: "libvndk_ext",
    vendor: true,
    vndk: {
        enabled: true,
        extends: "libvndk",
    },
}

设置了 vendor:truevndk.enabled:true 且具有 extends 属性的模块可定义 VNDK 扩展:

  • extends 属性必须指定基础 VNDK 共享库名称(或 VNDK-SP 共享库名称)。
  • VNDK 扩展(或 VNDK-SP 扩展)以扩展时所基于的基础模块名称命名。例如,libvndk_ext 的输出二进制文件是 libvndk.so,而不是 libvndk_ext.so
  • VNDK 扩展将安装到 /vendor/lib[64]/vndk 中。
  • VNDK-SP 扩展将安装到 /vendor/lib[64]/vndk-sp 中。
  • 基础共享库必须同时设置了 vndk.enabled:truevendor_available:true

VNDK-SP 扩展必须从 VNDK-SP 共享库进行扩展(vndk.support_system_process 的设置必须相同):

cc_library {
    name: "libvndk_sp",
    vendor_available: true,
    vndk: {
        enabled: true,
        support_system_process: true,
    },
}

cc_library {
    name: "libvndk_sp_ext",
    vendor: true,
    vndk: {
        enabled: true,
        extends: "libvndk_sp",
        support_system_process: true,
    },
}

VNDK 扩展(或 VNDK-SP 扩展)可以依赖于其他供应商共享库:

cc_library {
    name: "libvndk",
    vendor_available: true,
    vndk: {
        enabled: true,
    },
}

cc_library {
    name: "libvndk_ext",
    vendor: true,
    vndk: {
        enabled: true,
        extends: "libvndk",
    },
    shared_libs: [
        "libvendor",
    ],
}

cc_library {
    name: "libvendor",
    vendor: true,
}

使用 VNDK 扩展

如果供应商模块依赖于由 VNDK 扩展定义的额外 API,该模块必须在其 shared_libs 属性中指定 VNDK 扩展的名称:

// A vendor shared library example
cc_library {
    name: "libvendor",
    vendor: true,
    shared_libs: [
        "libvndk_ext",
    ],
}

// A vendor executable example
cc_binary {
    name: "vendor-example",
    vendor: true,
    shared_libs: [
        "libvndk_ext",
    ],
}

如果供应商模块依赖于 VNDK 扩展,这些 VNDK 扩展将自动安装到 /vendor/lib[64]/vndk[-sp] 中。如果模块不再依赖于 VNDK 扩展,请向 CleanSpec.mk 添加一个清理步骤,以移除相应的共享库。例如:

$(call add-clean-step, rm -rf $(TARGET_OUT_VENDOR)/lib/libvndk.so)

条件编译

本节介绍了如何处理以下三个 VNDK 共享库之间的细微差别(例如,为其中一个变体添加或移除某项功能):

  • 核心变体(例如 /system/lib[64]/libexample.so
  • 供应商变体(例如 /apex/com.android.vndk.v${VER}/lib[64]/libexample.so
  • VNDK 扩展(例如 /vendor/lib[64]/vndk[-sp]/libexample.so

条件编译器标记

默认情况下,Android 构建系统会为供应商变体和 VNDK 扩展定义 __ANDROID_VNDK__。您可以使用 C 预处理器防护程序保护代码:

void all() { }

#if !defined(__ANDROID_VNDK__)
void framework_only() { }
#endif

#if defined(__ANDROID_VNDK__)
void vndk_only() { }
#endif

除了 __ANDROID_VNDK__,还可以在 Android.bp 中指定不同的 cflagscppflags。在 target.vendor 中指定的 cflagscppflags 专门针对供应商变体。

例如,以下 Android.bp 定义了 libexamplelibexample_ext

cc_library {
    name: "libexample",
    srcs: ["src/example.c"],
    vendor_available: true,
    vndk: {
        enabled: true,
    },
    target: {
        vendor: {
            cflags: ["-DLIBEXAMPLE_ENABLE_VNDK=1"],
        },
    },
}

cc_library {
    name: "libexample_ext",
    srcs: ["src/example.c"],
    vendor: true,
    vndk: {
        enabled: true,
        extends: "libexample",
    },
    cflags: [
        "-DLIBEXAMPLE_ENABLE_VNDK=1",
        "-DLIBEXAMPLE_ENABLE_VNDK_EXT=1",
    ],
}

下面是 src/example.c 的代码清单:

void all() { }

#if !defined(LIBEXAMPLE_ENABLE_VNDK)
void framework_only() { }
#endif

#if defined(LIBEXAMPLE_ENABLE_VNDK)
void vndk() { }
#endif

#if defined(LIBEXAMPLE_ENABLE_VNDK_EXT)
void vndk_ext() { }
#endif

构建系统会根据这两个文件生成带有以下导出符号的共享库:

安装路径 导出符号
/system/lib[64]/libexample.so allframework_only
/apex/com.android.vndk.v${VER}/lib[64]/libexample.so allvndk
/vendor/lib[64]/vndk/libexample.so allvndkvndk_ext

对导出符号的要求

VNDK ABI 检查工具会将 VNDK 供应商变体和 VNDK 扩展的 ABI 与 prebuilts/abi-dumps/vndk 下的参考 ABI 转储进行比较。

  • 通过 VNDK 供应商变体(例如 /apex/com.android.vndk.v${VER}/lib[64]/libexample.so)导出的符号必须与 ABI 转储中定义的符号完全相同(而不是后者的超集)。
  • 通过 VNDK 扩展(例如 /vendor/lib[64]/vndk/libexample.so)导出的符号必须是 ABI 转储中定义的符号的超集。

如果 VNDK 供应商变体或 VNDK 扩展未能遵循上述要求,VNDK ABI 检查工具会发出构建错误并停止构建。

从供应商变体中排除源文件或共享库

如需从供应商变体中排除源文件,请将这些文件添加到 exclude_srcs 属性。同样,为了确保共享库不与供应商变体相关联,请将这些库添加到 exclude_shared_libs 属性。例如:

cc_library {
    name: "libexample_cond_exclude",
    srcs: ["fwk.c", "both.c"],
    shared_libs: ["libfwk_only", "libboth"],
    vendor_available: true,
    target: {
        vendor: {
            exclude_srcs: ["fwk.c"],
            exclude_shared_libs: ["libfwk_only"],
        },
    },
}

在此示例中,libexample_cond_exclude 的核心变体包含 fwk.cboth.c 中的代码,并且依赖于 libfwk_onlylibboth 共享库。libexample_cond_exclude 的供应商变体仅包含 both.c 中的代码,因为 fwk.c 已被 exclude_srcs 属性排除。同样,它仅依赖于共享库 libboth,因为 libfwk_only 已被 exclude_shared_libs 属性排除。

从 VNDK 扩展导出头文件

VNDK 扩展可以向 VNDK 共享库添加新类或新函数。建议将这些声明保留在独立头文件中,并避免更改现有头文件。

例如,为 VNDK 扩展 libexample_ext 创建了一个新的头文件 include-ext/example/ext/feature_name.h

  • Android.bp
  • include-ext/example/ext/feature_name.h
  • include/example/example.h
  • src/example.c
  • src/ext/feature_name.c

在下面的 Android.bp 中,libexample 只会导出 include,而 libexample_ext 会同时导出 includeinclude-ext。这样可以确保 libexample 的用户不会错误地添加 feature_name.h

cc_library {
    name: "libexample",
    srcs: ["src/example.c"],
    export_include_dirs: ["include"],
    vendor_available: true,
    vndk: {
        enabled: true,
    },
}

cc_library {
    name: "libexample_ext",
    srcs: [
        "src/example.c",
        "src/ext/feature_name.c",
    ],
    export_include_dirs: [
        "include",
        "include-ext",
    ],
    vendor: true,
    vndk: {
        enabled: true,
        extends: "libexample",
    },
}

如果无法将扩展单独保存到独立的头文件中,也可以选择添加 #ifdef 防护程序。但是,请确保所有 VNDK 扩展用户都添加了 define 标记。您可以定义 cc_defaults 以向 cflags 添加 define 标记并使用 shared_libs 关联共享库。

例如,如需将新成员函数 Example2::get_b() 添加到 VNDK 扩展 libexample2_ext,您必须修改现有的头文件并添加 #ifdef 防护程序:

#ifndef LIBEXAMPLE2_EXAMPLE_H_
#define LIBEXAMPLE2_EXAMPLE_H_

class Example2 {
 public:
  Example2();

  void get_a();

#ifdef LIBEXAMPLE2_ENABLE_VNDK_EXT
  void get_b();
#endif

 private:
  void *impl_;
};

#endif  // LIBEXAMPLE2_EXAMPLE_H_

libexample2_ext 的用户定义了一个名为 libexample2_ext_defaultscc_defaults

cc_library {
    name: "libexample2",
    srcs: ["src/example2.cpp"],
    export_include_dirs: ["include"],
    vendor_available: true,
    vndk: {
        enabled: true,
    },
}

cc_library {
    name: "libexample2_ext",
    srcs: ["src/example2.cpp"],
    export_include_dirs: ["include"],
    vendor: true,
    vndk: {
        enabled: true,
        extends: "libexample2",
    },
    cflags: [
        "-DLIBEXAMPLE2_ENABLE_VNDK_EXT=1",
    ],
}

cc_defaults {
    name: "libexample2_ext_defaults",
    shared_libs: [
        "libexample2_ext",
    ],
    cflags: [
        "-DLIBEXAMPLE2_ENABLE_VNDK_EXT=1",
    ],
}

libexample2_ext 的用户只需在其 defaults 属性中添加 libexample2_ext_defaults

cc_binary {
    name: "example2_user_executable",
    defaults: ["libexample2_ext_defaults"],
    vendor: true,
}

产品包

在 Android 构建系统中,变量 PRODUCT_PACKAGES 指定应安装到设备中的可执行文件、共享库或软件包。指定模块的传递依赖项也会隐式安装到设备中。

如果启用了 BOARD_VNDK_VERSION,设置了 vendor_availablevndk.enabled 的模块会得到特殊处理。如果框架模块依赖于设置了 vendor_availablevndk.enabled 的模块,会将核心变体纳入到传递安装集中。如果供应商模块依赖于设置了 vendor_available 的模块,会将供应商变体纳入到传递安装集中。不过,无论供应商模块是否使用设置了 vndk.enabled 的模块的供应商变体,都会安装这些变体。

当相关依赖项对构建系统不可见时(例如,可以在运行时使用 dlopen() 打开的共享库),您应该在 PRODUCT_PACKAGES 中指定模块名称来明确安装这些模块。

如果某个模块设置了 vendor_availablevndk.enabled,模块名称代表该模块的核心变体。如需在 PRODUCT_PACKAGES 中明确指定供应商变体,请将 .vendor 后缀附加到模块名称。例如:

cc_library {
    name: "libexample",
    srcs: ["example.c"],
    vendor_available: true,
}

在此示例中,libexample 代表 /system/lib[64]/libexample.solibexample.vendor 代表 /vendor/lib[64]/libexample.so。如需安装 /vendor/lib[64]/libexample.so,请将 libexample.vendor 添加到 PRODUCT_PACKAGES

PRODUCT_PACKAGES += libexample.vendor