鸿蒙5.0开发进阶：配置构建-配置CPP

往期鸿蒙5.0全套实战文章必看：（文中附带全栈鸿蒙5.0学习资料）

• 鸿蒙开发核心知识点，看这篇文章就够了

• 最新版！鸿蒙HarmonyOS Next应用开发实战学习路线

• 鸿蒙HarmonyOS NEXT开发技术最全学习路线指南

• 鸿蒙应用开发实战项目，看这一篇文章就够了（部分项目附源码）

---

配置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++编译器参数。
cFlags	字符串	可选	C编译参数。仅模块级build-profile.json5文件支持配置。
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模块中的.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字段不生效。
librariesInfo	对象数组	可选	声明so的透传依赖信息。仅模块级build-profile.json5文件支持配置。

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配置中声明，收集顺序按照广度优先的遍历方式来收集依赖。

  如下图，优先级顺序为current > library0 > library1 > library5 > library2 > library3 > library4。

  图1

  

• select

  表4 select字段说明

  字段名称	类型	是否必选	含义
  package	字符串	可选	包名。
  version	字符串	可选	包版本。
  include	字符串数组	可选	选择打包的native产物。
  exclude	字符串数组	可选	排除的native产物。

  例如本模块依赖的libcurl.so所在的har包为@ohos/curl，并且存在多个版本的libcurl.so，需要打包1.3.5版本，那可以通过以下配置，精确打包这个so到产物中。

  {
    buildOption: {
      nativeLib: {
        filter: {
          select: [ // select的优先级高于excludes、pickFirsts等配置项
            {
              package: "@ohos/curl", // 包名
              version: "1.3.5", // 包版本
              include: ["libcurl.so"], // 选择打包的native产物
              exclude: ["libc++_shared.so"] // 排除的native产物
             }
          ]
        }
      }
    }
  }

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。

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文件
          "select": [ // select提供native产物的精准选择能力，根据包名、版本、产物名称等选择或排除，select的优先级高于excludes、pickFirsts等配置项
            {
              "package": "@ohos/curl", // 包名
              "version": "1.3.5", // 包版本
              "include": ["libcurl.so"], // 选择打包的native产物
              "exclude": ["libc++_shared.so"] // 排除的native产物
            }
          ],
        },
        "headerPath": "./src/main/cpp/include" // 声明模块打包共享的c/cpp接口
        "librariesInfo":[
          {
             "name": "libentry.so",
             "linkLibraries": ["curl::curl"]
          }
        ]
      },
    },
  ],
  ...
}