前言

OpenHarmony 应用和服务使用 Hvigor 作为工程的构建工具。 本篇文章将介绍 Hvigor 的基本用法和配置。

什么是 Hvigor ？

命名的含义

Harmony vigor ，寓意：元气 活力 坚定，以轻量、高速、便捷为宗旨。

简介

Hvigor 是基于任务管理机制实现的一款全新的自动化构建工具，主要提供任务注册编排，编译工程模型管理，编译配置定制，插件扩展等核心能力，当前主要面向 OpenHarmonyOS 应用的 JS/eTS 开发场景。

Hvigor 结构化模型

Hvigor 工程主要以 build-profile.json5 与 hvigorfile.js 组成。

RootProject                     // Hvigor 工程根目录
├── build-profile.json5         // 工程级别 Hvigor 配置，主要配置工程相关信息，包括子模块名字、路径等。
├── hvigorfile.js               // 工程级别任务脚本
├── ModuleA
│   ├── build-profile.json5     // 模块级别 Hvigor 配置，主要模块构建相关参数
│   └── hvigorfile.js           // 模块级别任务脚本
└── ModuleB
    ├── build-profile.json5     // 模块级别 Hvigor 配置，主要模块构建相关参数
    └── hvigorfile.js           // 模块级别任务脚本

安装和使用

Hvigor 工具通过 NPM 包管理器安装， Node.js 运行，所以在系统中需预先安装 Node.js 和 NPM 工具。

Node.js 版本要求： v14.18.3 及以上版本

安装 hvigor

npm install @ohos/hvigor --save

安装 hvigor-ohos-plugin

hvigor-ohos-plugin 是基于 hvigor 插件机制开发的一款插件，服务于 OpenHarmonyOS 应用构建工作流，完成 HAP/APP 打包。

npm install @ohos/hvigor-ohos-plugin --save

Hvigor 的使用

命令行指令结构

hvigor [taskName...] [--option-name]

详细参数

Usage: hvigor [options]
​
Options:
--version, -v   Print the global and local vigor versions.            [boolean]
--cwd           Manually set the CWD. The search for the vigorfile, as well as 
                the relativity of all requires will be from here.     [string]
--require       Will require a module before running the vigorfile. This is useful 
                for transpilers but also has other applications.      [string]
--prop,  -p     Define extra properties.                              [string]
--mode,  -m     Specifies the mode in which the command is currently 
                executed.                                             [string]
--sync,  -s     Sync the information in plugin for other platform.    [boolean]
--error, -e     Log errors only.                                      [boolean]
--warn,  -w     Set log level to warn.                                [boolean]
--info,  -i     Set log level to info.                                [boolean]
--debug, -d     Set log level to debug.                               [boolean]

例如在工程目录下使用 Hvigor 工具通过命令行 Build Hap(s) ，执行的命令如下：

node node_modules/@ohos/hvigor/bin/hvigor.js --mode module assembleHap

应用和服务的构建配置

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

• build-profile.json5：OpenHarmony 应用/服务构建配置文件。

• hvigorfile.js：编译构建脚本。

• package.json：应用的 npm 包依赖，在遵循 npm 标准规范的基础上，支持 OpenHarmony npm 包的依赖。

build-profile.json5

工程级别 build-profile.json5

{
  "app": { 
    "signingConfigs": [                                     //工程的签名信息，可包含多个签名信息
      {
        "name": "debug",                                    //标识签名方案的名称
        "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": 8,           //指定OpenHarmony应用/服务编译时的SDK版本
    "compatibleSdkVersion": 8,        //指定OpenHarmony应用/服务兼容的最低SDK版本
    "products": [                     //定义构建的产品品类，如通用默认版、付费版、免费版等
      {
        "name": "default",            //定义产品的名称，由开发者自定义
        "signingConfig": "debug",     //指定当前产品品类对应的签名信息，签名信息需要在signingConfigs中进行定义
      }
    ]
  },
  "modules": [
    {
      "name": "entry",                //模块名称
      "srcPath": "./entry",           //标明src目录相对工程根目录的相对路径
      "targets": [                    //定义构建的产物，由product和各模块定义的targets共同定义
        {
          "name": "default",          //target名称，由各个模块的build-profile.json5中的targets字段定义
          "applyToProducts": [        //产品品类名称，由products字段进行定义
            "default"
          ]
        }
      ]
    }
  ]
}

模块级别 build-profile.json5

{
  "apiType": 'faMode',          //API类型，FA模型或者Stage模型
  "showInServiceCenter": true,  //是否在服务中心露出
  "buildOption": {
    "arkEnable": true,          //是否使用方舟编译器进行编译
    //cpp相关编译配置
    "externalNativeOptions": {
      "path": "./src/main/cpp/CMakeLists.txt",      //CMake配置文件，提供CMake构建脚本
      "arguments": "-v -DOHOS_STL=c++_shared",      //传递给CMake的可选编译参数
      "abiFilters": [                               //用于设置本机的ABI编译环境
        "armeabi-v7a"
      ],
      "cppFlags": ""                                //设置C++编译器的可选参数
    },
  },
  "targets": [                                      //模块对应的产物配置
    {
      "name": "default",
    },
    {
      "name": "ohosTest",
    }    
  ]
}

hvigorfile.js

工程级别 hvigorfile.js

// FA 模型
module.exports = require('@ohos/hvigor-ohos-plugin').legacyAppTasks

// Stage 模型
module.exports = require('@ohos/hvigor-ohos-plugin').appTasks

模块级別 HAP 的 hvigorfile.js

// FA 模型
module.exports = require('@ohos/hvigor-ohos-plugin').legacyHapTasks

// Stage 模型
module.exports = require('@ohos/hvigor-ohos-plugin').hapTasks

模块级別 HAR 的 hvigorfile.js

// FA 模型
module.exports = require('@ohos/hvigor-ohos-plugin').legacyHarTasks

// Stage 模型
module.exports = require('@ohos/hvigor-ohos-plugin').harTasks

package.json

OpenHarmony 应用/服务支持通过 npm 来安装、共享、分发代码，管理工程的依赖关系。OpenHarmony npm 包规范是在标准 npm规范 的基础上，增加对 OpenHarmony 平台的拓展。

工程级別 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.2",
      "@ohos/hvigor-ohos-plugin":"1.2.2",
      "@ohos/hvigor":"1.2.2"
  }
}

模块级別 package.json

{
    "license": "ISC",
    "devDependencies": {},
    "name": "entry",
    "ohos": {
        "org": "huawei",
        "directoryLevel": "module",
        "buildTool": "hvigor"
    },
    "description": "example description",
    "repository": {},
    "version": "1.0.0",
    "dependencies": {}
}

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

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

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

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

• directoryLevel：标识 npm 包是工程的依赖或是模块级的依赖。

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

DevEco 中的构建命令

Build Hap(s)

node node_modules/@ohos/hvigor/bin/hvigor.js --mode module assembleHap

Build APP(s)

node node_modules/@ohos/hvigor/bin/hvigor.js --mode project assembleApp

Make Module 'entry'

node node_modules/@ohos/hvigor/bin/hvigor.js --mode module -p product -p module=entry assembleHap

Rebuild Project

node node_modules/@ohos/hvigor/bin/hvigor.js --mode module clean assembleHap

Clean Project

node node_modules/@ohos/hvigor/bin/hvigor.js clean

Previewer

node node_modules/@ohos/hvigor/bin/hvigor.js --mode module -p module=entry buildPreviewerResource -p buildRoot=.preview