# 配置CPP

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

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

#### externalNativeOptions

externalNativeOptions是Native编译配置项。

| 字段名称 | 类型 | 可选/必选 | 含义 |
| --- | --- | --- | --- |
| 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）相关配置。

| 字段名称 | 类型 | 可选/必选 | 含义 |
| --- | --- | --- | --- |
| 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 Beta1版本开始支持。 说明： 仅HAP/HSP模块支持配置该字段。 配置为true时，libs/{ABI}根目录及子目录下不能有重名的so。 |

#### filter

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

| 字段名称 | 类型 | 可选/必选 | 含义 |
| --- | --- | --- | --- |
| 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**
    
    | 字段名称 | 类型 | 可选/必选 | 含义 |
    | --- | --- | --- | --- |
    | 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
               }
            ]
          }
        }
      }
    }
    ```
    

#### debugSymbol

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

| 字段名称 | 类型 | 可选/必选 | 含义 |
| --- | --- | --- | --- |
| 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文件支持配置。

| 字段名称 | 类型 | 可选/必选 | 含义 |
| --- | --- | --- | --- |
| 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"]
          }
        ]
      },
    },
  ],
  ...
}
```