OpenHarmony DevEco Studio使用指南-编译构建

编译构建概述

编译构建是将OpenHarmony应用/服务的源代码、资源、第三方库等，通过编译工具转换为可直接在硬件设备上运行的二进制机器码，然后再将二进制机器码封装为HAP/APP软件包，并为HAP/APP进行签名的过程。其中，HAP是可以直接运行在真机设备中的软件包；APP则是用于应用/服务上架到应用市场，关于HAP和APP的关系说明请参考​​OpenHarmony工程介绍​​。

OpenHarmony构建体系

OpenHarmony应用/服务的构建体系由构建工具Hvigor和构建插件hvigor-ohos-plugin组成。构建工具和构建插件的版本可在工程级的package.json文件中进行配置，示例如下所示：关于构建工具和构建插件的版本配套关系可参考​​DevEco Studio版本说明​​。

{
  ...
  "dependencies": {
    "@ohos/hvigor": "1.4.0",
    "@ohos/hvigor-ohos-plugin": "1.4.0"
  }
}

构建工具Hvigor

一款全新基于TS实现的前端构建任务编排工具，结合npm包管理机制，主要提供任务管理机制，任务注册编排、工程模型管理、配置管理等关键能力，更符合OpenHarmony ArkTS/JS开发者的开发习惯。

构建插件hvigor-ohos-plugin

基于Hvigor构建工具开发的一个插件，利用Hvigor的任务编排机制完成OpenHarmony应用/服务构建任务流的执行，完成OpenHarmony HAP/APP的构建打包，应用于OpenHarmony应用/服务的构建。

工程目录及配置文件说明

基于Hvigor构建体系，DevEco Studio定义了OpenHarmony的工程范式，下面是Hvigor构建体系的工程目录结构示意图：

关于Hvigor构建体系中的构建配置文件（build-profile.json5）、构建脚本（hvigorfile.ts）、依赖配置（package.json）的详细说明请参考​​配置编译构建信息​​章节。

如何构建应用/服务

启动应用/服务构建

• 方式一：通过单击

或

按钮，DevEco Studio会启动应用/服务的编译，并将编译后的HAP部署到设备中。这种方式一般用于应用开发阶段进行应用的调试、功能验证等场景。

• ​方式二：通过DevEco Studio的Build菜单栏的编译选项进行构建，HAP的构建结果存放于各模块的“build”文件夹下，APP包的构建结果存放于工程的“build”文件夹下。这种方式可以分别编译HAP和APP，其中HAP可用于安装到设备中进行功能验证，APP则用于将应用/服务发布到应用市场。

关于Build菜单下的编译选项说明如下：

查看编译过程

启动编译后，您可以在底部工具链的Run窗口查看编译任务的详细信息，例如执行的编译流程、任务的执行时间等信息。如果在编译构建过程中出现错误，您可以根据编译任务的详细错误说明进行问题的定位。

查看编译结果

编译构建成功后，您可以在工程目录中找到对应的编译产物（如APP/HAP），其中，APP将存储于工程根目录的build > outputs >default目录下；而HAP则会存储各模块下的build > default > outputs > default目录下。

多工程构建

为降低大型应用多个团队协作开发的复杂度，提供多工程开发模式，提高协作开发效率。多工程开发能力支持将大型应用拆分为多个模块，每个模块对应一个单独工程。在每个工程分别编译生成HAP后，需统一打包生成一个APP，用于上架应用市场。

1. 分别在每个工程的app.json5配置文件中，设置multiProjects字段值为true。

{
  "app": {
    ...
    "multiProjects": true,
  }
}

2. 使用如下命令，将多个HAP进行打包。

• hap-list：多个HAP文件名称，如“1.hap”和“2.hap”，用逗号隔开；
• out-path：生成的APP名称，如“final.app”

java -jar app_packing_tool.jar --mode multiApp --hap-list 1.hap,2.hap --out-path final.app

配置编译构建信息

在进行OpenHarmony应用/服务的编译构建前，您可以对构建配置文件、构建脚本、应用依赖的npm包等信息进行设置。

• build-profile.json5：OpenHarmony应用/服务构建配置文件。
• hvigorfile.ts：自定义编译构建脚本。
• package.json：应用的三方包依赖，支持HAR（遵循npm标准规范）和npm包的依赖。

build-profile.json5

工程级build-profile.json5

工程级build-profile.json5的示例如下所示：

{
  "app": { 
    "signingConfigs": [  //工程的签名信息，可包含多个签名信息
      {
        "name": "default",  //标识签名方案的名称
        "material": {  //该方案的签名材料
          "certpath": "D:\\SigningConfig\\debug_ohos.cer",  //调试或发布证书文件，格式为.cer
          "storePassword": "******",  //密钥库密码，以密文形式呈现
          "keyAlias": "debugKey",  //密钥别名信息
          "keyPassword": "******",  //密钥密码，以密文形式呈现
          "profile": "D:\\SigningConfig\\debug_ohos.p7b",  //调试或发布证书Profile文件，格式为.p7b
          "signAlg": "SHA256withECDSA",  //密钥库signAlg参数
          "storeFile": "D:\\SigningConfig\\debug_ohos.p12"  //密钥库文件，格式为.p12
        }
      }
    ],
    "compileSdkVersion": 9,  //指定OpenHarmony应用/服务编译时的SDK版本
    "compatibleSdkVersion": 9,  //指定OpenHarmony应用/服务兼容的最低SDK版本
    "products": [  //定义构建的产品品类，如通用默认版、付费版、免费版等
      {
        "name": "default",  //定义产品的名称，支持定制多product目标产物，具体请参考定制多目标构建产物
        "signingConfig": "default",  //指定当前产品品类对应的签名信息，签名信息需要在signingConfigs中进行定义
      }
    ]
  },
  "modules": [
    {
      "name": "entry",  //模块名称
      "srcPath": "./entry",  //标明src目录相对工程根目录的相对路径
      "targets": [  //定义构建的产物，由product和各模块定义的targets共同定义
        {
          "name": "default",  //target名称，由各个模块的build-profile.json5中的targets字段定义
          "applyToProducts": [  
            "default"  //表示将该模块下的“default” Target打包到“Default” Product中
          ]
        }
      ]
    }
  ]
}

模块级build-profile.json5

模块级build-profile.json5的示例如下所示：

{
  "apiType": 'faMode',  //API类型，API 8为FA模型，API 9为FA或Stage模型
  "showInServiceCenter": true,  //是否在服务中心展示
  "buildOption": {
    //配置筛选har依赖.so资源文件的过滤规则
    "napiLibFilterOption": {
      //按照.so文件的优先级顺序，打包最高优先级的.so文件
      "pickFirsts": [
        "**/1.so"
      ],
      //按照.so文件的优先级顺序，打包最低优先级的.so 文件
      "pickLasts": [
        "**/2.so"
      ],
      //排除的.so文件
      "excludes": [
        "**/3.so"
      ],
      //允许当.so重名冲突时，使用高优先级的.so文件覆盖低优先级的.so文件
      "enableOverride": true
    },
    //cpp相关编译配置
    "externalNativeOptions": {
      "path": "./src/main/cpp/CMakeLists.txt",  //CMake配置文件，提供CMake构建脚本
      "arguments": "",  //传递给CMake的可选编译参数
      "abiFilters": [  //用于设置本机的ABI编译环境
        "armeabi-v7a",
        "arm64-v8a"
      ],
      "cppFlags": ""  //设置C++编译器的可选参数
    },
  },
  "targets": [  ////定义的Target，开发者可以定制不同的Target，具体请参考定制多目标构建产物
    {
      "name": "default",
    },
    {
      "name": "ohosTest",
    }    
  ]
}

package.json

OpenHarmony应用/服务支持通过npm来安装、共享、分发代码，管理项目的依赖关系。OpenHarmony npm包规范是在标准npm规范的基础上，增加了对OpenHarmony平台的拓展。因此，package.json格式遵循标准的NPM规范（具体可查阅​​npm官方文档​​），接下来主要介绍OpenHarmony npm部分的规范。

工程级package.json

工程级package.json的示例如下所示：

{
  "name": "myapplication",
  "version": "1.0.0",
  "ohos": {
    "org": "huawei",
    "buildTool": "hvigor",
    "directoryLevel": "project"
  },
  "description": "example description",
  "repository": {},
  "license": "ISC",
  "dependencies": {
    "@ohos/hypium": "1.0.5",
    "@ohos/hvigor": "1.4.0",
    "@ohos/hvigor-ohos-plugin": "1.4.0"
  }
}

关于OpenHarmony npm包的相关字段说明如下，其余字段遵循​​package.json标准规范​​。

• ohos闭包：OpenHarmony应用/服务的扩展字段，表示在npm标准规范的基础上叠加了OpenHarmony npm包。

    ○  org：标识OpenHarmony npm包的维护主体。

    ○  buildTool：标识OpenHarmony npm包的构建工具是hvigor。

    ○  directoryLevel：标识OpenHarmony npm包是工程的依赖。

• dependencies闭包：设置工程依赖的npm包及版本，在遵循npm原生的基础上，可以添加@ohos相关的依赖，如构建插件，OpenHarmony npm三方共享包等。

模块级package.json

模块级package.json的示例如下所示：

{
    "license": "ISC",
    "devDependencies": {
        "@types/libentry.so": "file:./src/main/cpp/types/libentry"
    },
    "name": "entry",
    "ohos": {
        "org": "huawei",
        "directoryLevel": "module",
        "buildTool": "hvigor"
    },
    "description": "example description",
    "repository": {},
    "version": "1.0.0",
    "dependencies": {}
}

关于HAR包的相关字段说明如下，其余字段遵循​​package.json标准规范​​。

• ohos闭包：OpenHarmony应用/服务的扩展字段，表示在npm标准规范的基础上叠加了OpenHarmony npm包。

     ○  org：标识OpenHarmony npm包的维护主体。

     ○  directoryLevel：标识OpenHarmony npm包是模块级的依赖。

     ○  buildTool：标识OpenHarmony npm包的构建工具是hvigor。

• dependencies闭包：设置模块依赖的npm包及版本，在遵循npm原生的基础上，可以添加@ohos相关的依赖，如OpenHarmony npm三方共享包等。

配置应用的依赖

OpenHarmony应用/服务支持通过npm来安装、共享、分发代码，管理项目的依赖关系。OpenHarmony npm包规范是在标准npm规范的基础上，增加了对OpenHarmony平台的拓展。本文将介绍如何配置OpenHarmony工程/模块的npm包依赖。

配置npm包依赖

npm包的依赖一般包括以下三种：npm原生三方包、OpenHarmony npm三方共享包和OpenHarmony npm本地共享模块。开发者可在工程或模块下的package.json中进行配置，配置依赖的示例如下所示：

• npm原生三方包依赖示例如下：

"dependencies": {
  "eslint": "^7.32.0",
  ... 
}

• OpenHarmony三方包依赖示例如下：

"dependencies": {
 "@ohos/vcard": "^2.1.0",
 ...
}

• OpenHarmony npm本地共享模块依赖示例如下

"dependencies": {
 "@ohos/library": "file:../library", 
 ...
}

依赖配置完成后，请在Terminal窗口执行npm install命令下载依赖包，或者单击编辑器窗口上方的Sync Now进行同步，依赖包会存储在工程或各模块的node_modules目录下。

npm install

引用npm包资源

依赖设置完成后，您可以在工程中引用npm三方共享包资源，包括：引用OpenHarmony npm包hml页面、引用OpenHarmony npm包ArkTS页面、引用OpenHarmony npm包内ts/js方法，以及引用OpenHarmony npm包内资源。引用方法请参考​​引用OpenHarmony npm包文件和资源​​。

配置签名信息

在使用真机设备调试应用/服务时，需要提前为应用/服务进行签名。OpenHarmony应用签名包括自动化签名和使用命令行工具手动签名两种方式。

请注意，自动化签名和使用命令行工具手动签名仅用于应用/服务调试阶段使用，不可用于发布上架应用市场。

使用DevEco Studio自动化签名

自动化签名指导

DevEco Studio为开发者提供了自动化签名方案，可以一键完成应用/服务签名。具体操作如下：

单击File > Project Structure > Project > Signing Configs界面勾选Automatically generate signature，等待自动签名完成即可，单击OK。如下图所示：

说明

如果您的应用/服务使用了“system_basic”和“system_core”权限，请参考​​修改应用权限等级​​修改签名模板。您使用到的应用权限，可以在自动化签名完成后，单击Show Restricted Permissions进行查看。

修改应用权限等级

OpenHarmony针对应用/服务访问额外的系统或其他应用/服务的数据（包括用户个人数据）或功能，提供了一种访问控制机制来保证这些数据或功能不会被不当或恶意使用，即应用权限。根据权限对于不同等级应用/服务有不同的开放范围，权限类型对应分为以下三种，等级依次提高。

• normal权限
• system_basic权限
• system_core权限

关于以上三种权限的详细说明请参考​​权限等级说明​​。

如果您的应用/服务申请了​​访问控制的权限​​，默认情况下自动化签名功能只能申请权限等级为“normal”的权限。若使用了更高级别的权限（system_core或system_basic），请修改自动化签名所需要的Profile模板，然后再使用自动化签名功能对应用/服务进行签名。

修改Profile模板的步骤如下：

1. 打开OpenHarmony SDK所在目录（可通过DevEco Studio菜单栏中单击File > Settings > SDKs > OpenHarmony界面查看 ）。

2. 在SDK目录下，进入 {Version} >Toolchains > lib文件夹，打开“UnsgnedReleasedProfileTemplate.json”文件。

3. ​根据工程的config.json中配置的应用权限对应的​​权限级别​​，修改apl参数。后续使用时，若权限级别未发生变化，不需要重复修改UnsgnedReleasedProfileTemplate.json文件的权限级别。

说明

修改权限等级时，请将apl参数修改为您当前应用/服务使用到的最高等级。例如，您如果同时使用了权限等级为“normal”和“system_basic”权限，则apl参数请修改为“system_basic”。此时使用自动化签名功能时，将自动为您申请“normal”和“system_basic”的权限。

4. 修改app-feature参数属性。

参数属性可配置范围：

• hos_normal_app：普通应用（默认）
• hos_system_app：系统应用

5. 在allowed-acls参数中配置应用需要的权限。
6. 保存UnsgnedReleasedProfileTemplate.json文件，使用自动化签名功能​​为应用/服务签名​​。

使用命令行工具手动签名

使用HAP签名工具为应用/服务进行签名，具体请参考​​Hap包签名工具​​。

文章转载自：​​https://developer.harmonyos.com/cn/docs/documentation/doc-guides-V3/ohos-auto-configuring-signature-information-0000001271659465-V3​​