VNDK 构建系统支持

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

VNDK 构建支持示例

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

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

图 1. 已启用支持。

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

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

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

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

配置 build 支持

如需为产品设备启用全面的构建系统支持，请将 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_libs、static_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.mk 或 Android.bp 中修改模块定义。此部分介绍了不同种类的模块定义，一些与 VNDK 相关的模块属性，以及在构建系统中实现的依赖项检查。

供应商模块

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

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

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

依赖项检查适用于 Android.bp 中的 header_libs、static_libs 和 shared_libs，以及 Android.mk 中的 LOCAL_HEADER_LIBRARIES、LOCAL_STATIC_LIBRARIES 和 LOCAL_SHARED_LIBRARIES。

LL-NDK

LL-NDK 共享库是具有稳定 ABI 的共享库。框架模块和供应商模块具有相同的最新实现。对于每个 LL-NDK 共享库，cc_library 都包含一个 llndk 属性和一个符号文件： 

cc_library {
    name: "libvndksupport",
    llndk: {
        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_library、cc_library_static、cc_library_shared 和 cc_library_headers 模块定义支持三个与 VNDK 相关的属性：vendor_available、vndk.enabled 和 vndk.support_system_process。

如果 vendor_available 或 vndk.enabled 设为 true，可以构建两个变体（核心变体和供应商变体）。核心变体应被视为框架模块，而供应商变体应被视为供应商模块。如果某些框架模块依赖于此模块，将会构建核心变体。如果某些供应商模块依赖于此模块，将会构建供应商变体。构建系统会强制执行以下依赖项检查：

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

cc_library 或 cc_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_system_process		 供应商变体说明
true false false 供应商变体为 VND-ONLY。共享库将安装到 /vendor/lib[64] 中。
true 无效（构建错误）
true false 供应商变体为 VNDK。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:true 和 vndk.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:true 和 vendor_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 中指定不同的 cflags 或 cppflags。在 target.vendor 中指定的 cflags 或 cppflags 专门针对供应商变体。

例如，以下 Android.bp 定义了 libexample 和 libexample_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 all, framework_only
/apex/com.android.vndk.v${VER}/lib[64]/libexample.so all, vndk
/vendor/lib[64]/vndk/libexample.so all, vndk, vndk_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.c 和 both.c 中的代码，并且依赖于 libfwk_only 和 libboth 共享库。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 会同时导出 include 和 include-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_defaults 的 cc_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_available 或 vndk.enabled 的模块会得到特殊处理。如果框架模块依赖于设置了 vendor_available 或 vndk.enabled 的模块，会将核心变体纳入到传递安装集中。如果供应商模块依赖于设置了 vendor_available 的模块，会将供应商变体纳入到传递安装集中。不过，无论供应商模块是否使用设置了 vndk.enabled 的模块的供应商变体，都会安装这些变体。

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

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

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

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

PRODUCT_PACKAGES += libexample.vendor