配置CPP

Hvigor集成CMake、Ninja为cpp代码的构建工具。在初始状态下，无需额外配置，您也可以添加以下自定义配置，定制cpp代码编译。

CPP配置包含externalNativeOptions和nativeLib，除特殊说明外，在工程级和模块级build-profile.json5文件中均支持配置，工程级配置会与模块级配置进行合并，模块级配置优先，具体合并规则和优先级请参考合并编译选项规则。

externalNativeOptions

externalNativeOptions是Native编译配置项。

表1 externalNativeOptions字段说明
字段名称	类型	可选/必选	含义
path	字符串	可选	CMake构建脚本地址，即CMakeLists.txt文件地址。
abiFilters	字符串数组	可选	HarmonyOS当前支持的ABI编译环境，包括： arm64-v8a x86_64 如不配置该参数，编译时默认为arm64-v8a。
arguments	字符串/字符串数组	可选	CMake编译参数。 Hvigor将会把此处的自定义参数传递给CMake构建工具，您可通过CMake官方文档查找您所需的编译参数，同时它也将覆盖默认同名参数。
cppFlags	字符串	可选	C++编译器参数。从DevEco Studio 6.0.1 Beta1版本开始，新增"-iclang"参数，提升编译效率，具体请参考通过IClang提升C++增量编译效率。
cFlags	字符串	可选	C编译参数。仅模块级build-profile.json5文件支持配置。从DevEco Studio 6.0.1 Beta1版本开始，新增"-iclang"参数，提升编译效率，具体请参考通过IClang提升C++增量编译效率。
targets	字符串数组	可选	指定Hvigor应构建的CMake项目中的库和可执行目标。仅模块级build-profile.json5文件支持配置。

nativeLib

nativeLib是Native库（.so）相关配置。

表2 nativeLib字段说明
字段名称	类型	可选/必选	含义
filter	对象	可选	Native 库（.so）文件的筛选选项。配置后优先级高于napiLibFilterOption。
debugSymbol	对象	可选	移除.so文件中的符号表、调试信息。
headerPath	字符串/字符串数组	可选	指定要导出的头文件路径。注意：请勿将源码等文件放置在该路径下，可能会被打包到产物中，请谨慎配置。
collectAllLibs	布尔值	可选	对libs目录收集打包时，是否收集所有后缀的文件。 true：不限制后缀，即收集所有文件（包括无后缀文件）。 false（缺省默认值）：限制后缀为.so，即只收集后缀为.so的文件。
excludeFromHar	布尔值	可选	构建HAR时，是否排除依赖HAR模块中的.so文件，排除时，依赖HAR模块的.so文件不会被打包到产物中。 true（缺省默认值）：排除。 false：不排除。说明：仅针对HAR模块生效。
excludeSoFromInterfaceHar	布尔值	可选	编译HSP模块时，打包的HAR产物是否排除.so文件，减少.tgz包体积大小。 true：排除。HAR产物不包含.so文件，HSP产物包含.so文件。 false（缺省默认值）：不排除。HAR产物和HSP产物都包含.so文件。说明：仅针对HSP模块生效。当HSP模块的工程级或模块级build-profile.json5文件中配置headerPath字段时，excludeSoFromInterfaceHar字段不生效。
excludeSoFromBinXO	字符串数组	可选	开启BinXO检测时，指定不需要进行二进制插桩的无源码.so文件，支持正则匹配，具体使用方式请参考使用HWASan检测内存错误。从DevEco Studio 6.1.0 Beta1版本开始支持。
librariesInfo	对象数组	可选	声明.so的透传依赖信息。仅模块级build-profile.json5文件支持配置。
enableSoDirCollection	布尔值	可选	ets文件中是否能够加载libs/{ABI}/子目录下的.so文件，其中{ABI}是设备CPU架构类型（如arm64-v8a）。 true：能够加载libs/{ABI}根目录及子目录下的.so文件。 false（缺省默认值）：只能加载libs/{ABI}根目录下的.so文件。从26.0.0版本开始支持。说明：仅HAP/HSP模块支持配置该字段。配置为true时，libs/{ABI}根目录及子目录下不能有重名的.so。

[h2]filter

filter是Native 库（.so）文件的筛选选项。配置后优先级高于napiLibFilterOption。

表3 filter字段说明
字段名称	类型	可选/必选	含义
excludes	字符串数组	可选	根据正则表达式排除匹配到的.so文件，匹配到的.so文件将不会被打包。
pickFirsts	字符串数组	可选	按照.so文件的优先级顺序，打包最高优先级的.so文件。
pickLasts	字符串数组	可选	按照.so文件的优先级顺序，打包最低优先级的.so文件。
enableOverride	布尔值	可选	是否允许当.so文件重名冲突时，使用高优先级的.so文件覆盖低优先级的.so文件： true：允许。 false（缺省默认值）：不允许。
select	对象数组	可选	select提供Native产物的精准选择能力，根据包名、版本、产物名称等，选择打包或排除Native产物到HAP/HSP/HAR产物。 select的优先级高于excludes、pickFirsts等配置项。

库文件.so的优先级
库文件.so的优先级顺序，可以通过pickFirsts，pickLasts选项来选择，其中pickFirsts选择高优先级的库文件，pickLasts选择低优先级的库文件。

这个优先级是由本模块的依赖模块或三方包的收集顺序决定的，本模块的依赖在oh-package.json5文件的dependencies配置中声明，优先级顺序如下。
- 三方包（包括远程三方包及本地har包）的优先级高于本地依赖模块的优先级。
- 按照广度优先的遍历方式来收集依赖，如下图，优先级顺序为current > library0 > library1 > library5 > library2 > library3 > library4。

select

表4 select字段说明
字段名称	类型	可选/必选	含义
package	字符串	可选	包名。
version	字符串	可选	包版本。
includePattern	字符串数组	可选	当依赖的多个包中存在重名的Native产物时，指定需要打包的Native产物，支持glob语法。从DevEco Studio 6.0.0 Beta2版本开始支持。
excludePattern	字符串数组	可选	指定排除的Native产物，默认打包所有产物，支持glob语法。excludePattern优先级比includePattern高。从DevEco Studio 6.0.0 Beta2版本开始支持。
include	字符串数组	可选	当依赖的多个包中存在重名的Native产物时，指定需要打包的Native产物。从DevEco Studio 6.0.0 Beta2版本开始，字段标记为废弃，推荐使用includePattern字段。
exclude	字符串数组	可选	指定排除的Native产物，默认打包所有产物。从DevEco Studio 6.0.0 Beta2版本开始，字段标记为废弃，推荐使用excludePattern字段。

includePattern/excludePattern字段和include/exclude字段不能同时配置。

示例一：entry模块依赖har包@ohos/curl和har1包@ohos/curl1，har包和har1包中的.so文件如下，两个包中存在重名的libcurl.so，可通过includePattern选择需要打包的libcurl.so，同时通过excludePattern排除不需要的产物。

// har包@ohos/curl的目录结构
└── har
    └── libs
        └── x86_64
            └── libcurl.so
            └── libcurl1.so
        └── arm64-v8a
            └── libcurl2.so
            └── libcurl3.so
            └── libcurl4.so
// har1包@ohos/curl1的目录结构
└── har1
    └── libs
        └── x86_64
            └── libcurl.so
// build-profile.json5
{
  buildOption: {
    nativeLib: {
      filter: {
        select: [ // select的优先级高于excludes、pickFirsts等配置项
          {
            package: "@ohos/curl", // 包名
            version: "1.3.5", // 包版本
            excludePattern: ['**/arm64-v8a/**'],    // 排除har包arm64-v8a目录下的所有.so文件
          },
          {
            package: "@ohos/curl1", // 包名
            version: "1.3.5", // 包版本
            includePattern: ['**/x86_64/libcurl.so'],  // 针对重名的libcurl.so，指定打包har1包中的libcurl.so
            // include: ["libcurl.so"]  // 针对重名的libcurl.so，指定打包har1包中的libcurl.so
          },
        ]
      }
    }
  }
}
// 打包后hap包的目录结构
└── entry-default.hap
    └── libs
        └── x86_64
            └── libcurl.so    // 来自har1包
            └── libcurl1.so   // 来自har包

示例二：har包中存在多个.so文件，需要打包其中的libcurl1.so和libcurl2.so。

// har包@ohos/curl的目录结构
└── libs
    └── arm64-v8a
        └── libcurl.so
        └── libcurl1.so
        └── libcurl2.so
// build-profile.json5
{
  buildOption: {
    nativeLib: {
      filter: {
        select: [  // select的优先级高于excludes、pickFirsts等配置项
          {
            package: "@ohos/curl", // 包名
            version: "1.3.5", // 包版本
            includePattern: [],
            excludePattern: ['**/arm64-v8a/!(*(libcurl1|libcurl2).so*)'], // 打包arm64-v8a目录下的libcurl1.so和libcurl2.so
            // include: [],
            // exclude: ["libcurl.so"] // 打包arm64-v8a目录下的libcurl1.so和libcurl2.so
          }
        ]
      }
    }
  }
}

[h2]debugSymbol

debugSymbol用于移除.so文件中的符号表、调试信息。

表5 debugSymbol字段说明
字段名称	类型	可选/必选	含义
strip	布尔值	可选	是否移除.so文件中的符号表、调试信息。 true（缺省默认值）：移除。 false：不移除。说明：从DevEco Studio NEXT Developer Beta2（5.0.3.502）版本开始，缺省默认值由false改为true。
exclude	字符串数组	可选	需要排除的.so文件，支持正则表达式写法。如果strip配置为true，匹配的.so文件将不会执行strip。如果strip配置为false，只有匹配的.so文件会执行strip。

[h2]librariesInfo

librariesInfo用于声明.so的透传依赖信息。仅模块级build-profile.json5文件支持配置。

表6
字段名称	类型	可选/必选	含义
name	字符串	必选	本模块.so库的名称。
linkLibraries	字符串数组	必选	.so库的依赖信息，格式为"依赖包名::依赖.so名称"。

如果需要声明库之间的依赖关系，例如entry依赖curl，可在模块内build-profile.json5中配置librariesInfo。

"buildOption": {
  "nativeLib": {
    "librariesInfo": [
      {
        "name": "libentry.so",
        "linkLibraries": ["curl::curl"]
      }
    ]
  }
}

当其他模块依赖声明了依赖透传的模块并使用libentry.so时，libentry.so会将依赖curl::curl添加到参数INTERFACE_LINK_LIBRARIES，开发者无需关注它的依赖。

add_library(library::library SHARED IMPORTED)
set_target_properties(library::library PROPERTIES
    IMPORTED_LOCATION "/path/to/file"
    INTERFACE_LINK_LIBRARIES "curl::curl")

配置字段示例

以模块级build-profile.json5为例：

{
  "buildOptionSet": [
    {
      "name": "release",
      "arkOptions": {
        "obfuscation": {
          "ruleOptions": {
            "enable": true,
            "files": [
              "./obfuscation-rules.txt"
            ]
          }
        }
      },
      "externalNativeOptions": {
        "path": "./src/main/cpp/CMakeLists.txt", // 自定义CMake配置脚本CMakeLists.txt的位置，它是以模块根目录为起始位置的相对路径
        "arguments": ["-DCMAKE_BUILD_TYPE=Debug"], // Hvigor将会把此处的自定义参数传递给CMake构建工具，您可通过CMake官方文档查找您所需的编译参数，同时它也将覆盖默认同名参数
        "cppFlags": "-g", // 自定义cpp flags参数
        "abiFilters": ["arm64-v8a"] // 自定义cpp编译架构，默认编译架构为arm64-v8a
      },
      "nativeLib": {
        "debugSymbol": { // 可通过此配置对cpp编译产物.so执行strip，移除.so中的调试信息与符号表等
          "strip": true, // 执行strip
          "exclude": [] //执行strip的过滤正则表达式规则
        },
        "filter": { // 可通过此选项自定义此cpp产物.so是否打包到应用包中
          "excludes": [ // 根据正则表达式排除匹配到的.so文件，匹配到的.so文件将不会被打包，可用于打包时缩小包体积
            "**/3.so", // 排除所有名称为“3”的.so文件
            "**/x86_64/*.so" // 排除所有x86_64架构的.so文件
          ], 
          "pickFirsts": ["**/1.so"], // 按照.so文件的优先级顺序，打包最高优先级的.so文件
          "pickLasts": ["**/2.so"], // 按照.so文件的优先级顺序，打包最低优先级的.so文件
          "enableOverride": true, // 当.so重名冲突时，使用高优先级的.so文件覆盖低优先级的.so文件
        },
        "headerPath": "./src/main/cpp/include", // 声明模块打包共享的c/cpp接口
        "librariesInfo":[
          {
             "name": "libentry.so",
             "linkLibraries": ["curl::curl"]
          }
        ]
      },
    },
  ],
}