Setting Up a Pipeline-Command Line Tools

In addition to DevEco Studio, you can also invoke Hvigor tasks through the CLI to build your app/atomic service. This approach allows you to set up a continuous integration (CI) pipeline to automate scheduled operations such as HAP/App Pack building, signing, installation, and running.

You can run commands on Windows, Linux, or macOS to build your app/atomic service through the CLI. This section uses Linux as an example. The procedure for invoking commands is the same regardless of the operating system.

NOTE

If your computer is not connected to the Internet, follow the instructions in Creating a CI Pipeline Offline.
Since the HarmonyOS SDK is embedded in DevEco Studio, there is no need for separate downloads or configurations.
Before running any commands, ensure that the current project is trustworthy for secure builds.

System Platform Requirements

Operating system: 64-bit Linux
glibc: 2.28 or later
Memory: 16 GB or larger recommended, 8 GB minimum
Hard disk: 100 GB or above

Prerequisites

Configuring the JDK

Download the JDK. For Command Line Tools 26.0.0 and later versions, JDK 21 is recommended. For versions earlier than 26.0.0, JDK 17 is recommended.
In Terminal, go to the JDK software package directory and run the following command, replacing jdk-17.0.6_linux-x64_bin.tar.gz with the actual package name, to decompress the package.
Collapse
Word wrap
Dark theme
Copy code
```
tar -xvf jdk-17.0.6_linux-x64_bin.tar.gz
```

Configure the JDK environment variables.

Collapse
Word wrap
Dark theme
Copy code
#jdk
export JAVA_HOME=/opt/jdk-17.0.6_linux-x64_bin
export PATH=$PATH:$JAVA_HOME/bin

Run the following command to check the JDK installation result:
Collapse
Word wrap
Dark theme
Copy code
```
java -version
```

Obtaining Command Line Tools

Obtain the command line tools pertaining to your operating system. In this example, command line tools for Linux are downloaded.
Run the following command to decompress the commandline-tools-linux-xxx.zip file (replace the file name with the actual package name in the command):
Collapse
Word wrap
Dark theme
Copy code
```
unzip commandline-tools-linux-x64-5.0.3.XXX.zip
```
Define the path where you decompress the tools as COMMANDLINE_TOOL_DIR, which will be used later when configuring the environment variables for Node.js, HDC, Hvigor, and ohpm. For example, decompress the package to the /opt directory.
Collapse
Word wrap
Dark theme
Copy code
```
export COMMANDLINE_TOOL_DIR=/opt
```

Setting the Node.js Environment Variables

The Command Line Tools package comes with a compatible version of Node.js. You can configure the environment variables by performing the following steps:

Configure the Node.js environment variables.

Collapse
Word wrap
Dark theme
Copy code
# The following uses Linux as an example. The Node.js path varies with the operating system. Replace it with the actual path.
export NODE_HOME=${COMMANDLINE_TOOL_DIR}/command-line-tools/tool/node
export PATH=$PATH:$NODE_HOME/bin

NOTE

The Node.js path varies depending on the OS. On Windows, the Node.js path is tool/node. On Linux and macOS, the Node.js path is tool/node/bin.

Run the following command to check the Node.js version to verify that the configuration is successful:
Collapse
Word wrap
Dark theme
Copy code
```
node -v
```

NOTE

You are advised to use the built-in Node.js of Command Line Tools. If you need to install it separately, use the matching Node.js version. For the version compatibility details, see DevEco Studio Compatibility and Version Mappings.

Setting the hdc Environment Variable

The hdc command line tool is used as a debugging tool for HarmonyOS apps/atomic services. This tool is located in the toolchains directory of the SDK that comes with the Command Line Tools. To facilitate the use of hdc, add it to the environment variables.

Complete Obtaining Command Line Tools.
Run the following command to add hdc to the environment variables, where ${COMMANDLINE_TOOL_DIR}/command-line-tools/sdk/default/openharmony/toolchains is used as an example of the hdc save path.
Collapse
Word wrap
Dark theme
Copy code
```
export HDC_HOME=${COMMANDLINE_TOOL_DIR}/command-line-tools/sdk/default/openharmony/toolchains
export PATH=$PATH:$HDC_HOME
```

Setting the hvigor Environment Variable

Complete Obtaining Command Line Tools.
Run the following command to add hvigorw to the environment variable PATH:
Collapse
Word wrap
Dark theme
Copy code
```
export PATH=${COMMANDLINE_TOOL_DIR}/command-line-tools/bin:$PATH
```
Switch to the root directory of the project and run the following command to query the Hvigor version to verify that the installation is successful:
Collapse
Word wrap
Dark theme
Copy code
```
hvigorw -v
```

Configuring the npm Image Repository

If the dependencies configured the hvigor/hvigor-config.json5 file contain any npm third-party libraries, you need to set the npm image repository address in the pipeline so that the libraries can be correctly downloaded during compilation.

Collapse
Word wrap
Dark theme
Copy code
npm config set registry https://repo.huaweicloud.com/repository/npm/
npm config set "@ohos:registry" https://repo.harmonyos.com/npm/

Installing ohpm

Complete Obtaining Command Line Tools.
Run the following command to add ohpm to the environment variables:
Collapse
Word wrap
Dark theme
Copy code
```
export PATH=${COMMANDLINE_TOOL_DIR}/command-line-tools/bin:$PATH
```
Run the following command to check the ohpm version to verify that the installation is successful:
Collapse
Word wrap
Dark theme
Copy code
```
ohpm -v
```
Run the following commands to specify one or more repository addresses, separated by commas:
Collapse
Word wrap
Dark theme
Copy code
```
ohpm config set registry https://ohpm.openharmony.cn/ohpm/
ohpm config set strict_ssl false
```

Installing the libGL1 Library

To use texture compression on Linux, you need to install the libGL1 library. The installation command varies by operating system. For example, install libgl1-mesa-dev on Ubuntu/Debian and mesa-libGL-devel on CentOS/RHEL.

The command below uses libgl1-mesa-dev as an example. For other operating systems, replace it with the actual package name.

Collapse
Word wrap
Dark theme
Copy code
apt install -y libgl1-mesa-dev

Building an App

Installing Project and Module Dependencies

Before using the CLI to build a project, run the ohpm install command in the project and each module to install the third-party libraries on which the project and modules depend.

Define the ohpm installation function. The following is an example:

Collapse
Word wrap
Dark theme
Copy code
# Switch to the specified directory $1 and run the ohpm install command.
function ohpm_install() {     
    cd $1              # $1: first parameter of the function, which must be a path.
    ohpm install --all # Install all dependencies.
}

Define the PROJECT_PATH variable, which indicates the project path. The following is an example:
Collapse
Word wrap
Dark theme
Copy code
```
PROJECT_PATH=xxx/xxx/project_name  # Project path.
```
NOTICE

Do not store the project directory in a hidden directory. That is, each level in the project path must not start with a period (.), for example, xxx/.xxx/project is not recommended. Otherwise, during the build process, the module's code and configuration files may be packaged into the product as resources without being obfuscated or encrypted.
Install the third-party library dependencies of the project and modules. The following is an example:
Collapse
Word wrap
Dark theme
Copy code
```
# Install the third-party library dependencies based on service requirements.
ohpm_install "${PROJECT_PATH}"
...
```

Running Hvigor Build Commands

After a build command is executed using the hvigorw command-line tool, the HAP, HSP, HAR, or App Pack files are generated in the build directory of the project or corresponding module.

Collapse
Word wrap
Dark theme
Copy code
# Run a build command based on the service requirements. The following is an example:

# Clean the project.
hvigorw clean --no-daemon

# Build a HAP. The generated file is ${PROJECT_PATH}/{moduleName}/build/{productName}/outputs/{targetName}/xxx.hap.
hvigorw assembleHap --mode module -p product=default -p buildMode=debug --no-daemon

# Build an HSP. The generated files are ${PROJECT_PATH}/{moduleName}/build/{productName}/outputs/{targetName}/(xxx.har | xxx.hsp).
hvigorw assembleHsp --mode module -p module=library@default -p product=default --no-daemon

# Build a HAR. The generated file is ${PROJECT_PATH}/{moduleName}/build/{productName}/outputs/{targetName}/outputs/xxx.har.
hvigorw assembleHar --mode module -p module=library1@default -p product=default --no-daemon

# Build an App Pack. The generated file is ${PROJECT_PATH}/build/outputs/{productName}/xxx.app.
hvigorw assembleApp --mode project -p product=default -p buildMode=debug --no-daemon

When using Linux for your CI pipeline, be aware that Linux is case-sensitive. If your code has case mismatches in imports — for example, using import funcA from './aaa' when the actual file is named AAA.ets — the code might compile successfully on Windows or macOS due to their case-insensitive file systems. However, on Linux, this could lead to compilation failures. To maintain consistency in compilation results across Windows, macOS, and Linux, you can configure caseSensitiveCheck to true in the project-level build-profile.json5 file. This configuration enforces case sensitivity during compilation, ensuring that any case mismatches are detected regardless of the operating system.
Collapse
Word wrap
Dark theme
Copy code
```
// build-profile.json5 file
{
    "name": "default",
    "compatibleSdkVersion": "26.0.0",
    "runtimeOS": "HarmonyOS",
    "buildOption": {
      "strictMode": {
        "caseSensitiveCheck" : true
      }
    }
}
```
In non-daemon mode, you can modify the Node.js memory settings. To do so, uncomment line 15 in the hvigor/bin/hvigorw file and set the memory size to a value you prefer, such as 10240:
Collapse
Word wrap
Dark theme
Copy code
```
NODE_OPTS="--max-old-space-size=10240"
```
In daemon mode, follow the instructions in Setting the Daemon Memory.

The tables below list the common command-line options for compilation and building. For details about more Hvigor command-line options, see Common Commands.

Table 1 Common command-line options in building HarmonyOS apps

Expand

Options	Description
-p buildMode={debug \| release}	Uses the debug or release mode for builds. By default, the debug mode is used in building HAPs, HSPs, or HARs, and the release mode is used in building App Packs. For details about build modes, see Specifying a Build Mode. For details about how to build a HAR, see Building a HAR.
-p product={ProductName}	Specifies the target product under which the module targets are built. Default value: default
-p module={ModuleName}@{TargetName}	Specifies the module and target for builds. You can specify multiple modules of the same type, separated with commas (,). Note: This option must be used together with --mode module. By default, all modules in the project are built when the AssembleHap task is executed, and default is used for TargetName.
-p ohos-test-coverage={true \| false}	Executes the instrumentation compilation of the test framework code coverage.

Table 2 Options related to HarmonyOS app builds

Expand

Options	Description
clean	Cleans build output.
assembleHap	Builds a HAP.
assembleApp	Builds an App Pack.
assembleHsp	Builds an HSP.
assembleHar	Builds a HAR.

Running an App

If signature information has been configured via signingConfigs in the project-level build-profile.json5 file, and the pipeline contains signature files (including the .cer, .p7b, and .p12 files and the material folder, which is stored in the same directory as the .p12 file by default), both signed (for example, xxx-signed.hap) and unsigned (for example, xxx-unsigned.hap) packages will be generated after the build. The signed package can be run directly on a real device without re-signing. To re-sign the package, use the signing tool on the unsigned one, as described below.

Preparing Files to Apply for Signature

To apply for a signature, three files are required: keystore file (.p12 file), digital certificate (.cer file), and profile (.p7b file).

Generating a Keystore File and CSR

Use the Keytool in the JDK to generate a keystore file and a CSR.

After configuring the environment variables by following steps in Configuring the JDK, open the CLI and run the following command to generate a keystore file. This example creates a keystore file named demo.p12 and saves it to the path directory.
Collapse
Word wrap
Dark theme
Copy code
```
keytool -genkeypair -alias "demo_key" -keyalg EC -groupname secp256r1 -sigalg SHA256withECDSA -dname "C=CN,O=HUAWEI,OU=HUAWEI IDE,CN=demo_key"  -keystore /path/demo.p12 -storetype pkcs12 -validity 9125 -storepass 123456Abc -keypass 123456Abc
```
In the preceding command, modify settings of the following parameters and keep the other parameters as they are:
- alias: alias of the key, which is used to identify the key name.
- dname: basic certificate information.
  - C: country/region code, such as CN.
  - O: organization name, such as HUAWEI.
  - OU: organization unit name, such as HUAWEI IDE.
  - CN: your first name and last name. Set this parameter to be the same as alias.
- keystore: keystore file. Replace /path/demo.p12 with the actual path to the file.
- validity: certificate validity period, for example, 9125 (25 years).
- storepass: key store password, which must contain at least 8 characters that include two types of the following: uppercase letters, lowercase letters, digits, and special characters. Make a note of the password. You will need it when configuring the signature.
- keypass: password of the key. The value must be the same as that of storepass.
Run the following command. After the command is executed, enter the storepass to generate a .csr file.
Collapse
Word wrap
Dark theme
Copy code
```
keytool -certreq -alias "demo_key" -sigalg SHA256withECDSA -keystore /path/demo.p12 -storetype pkcs12 -file /path/demo.csr
```
Parameters in the CSR:
- alias: alias. The value is the same as the alias set in the previous step.
- keystore: keystore file. The value is the same as the keystore set in the previous step.
- file: name of the generated CSR file, with a .csr extension. Replace /path/demo.csr with the actual path to the file.

Requesting a Debug Digital Certificate and Profile File

With the CSR, request and download a debug digital certificate and profile in AppGallery Connect. For details, see Requesting a Debug Certificate and Requesting a Debug Profile.

Signing the Unsigned HAP or APP File

Prepare the signing tool hap-sign-tool.jar, which is available in the ${COMMANDLINE_TOOL_DIR}/command-line-tools/sdk/default/openharmony/toolchains/lib directory.
In the signing tool directory, run the following command to sign the HAP: For details about the signing tool, see hapsigner.
Collapse
Word wrap
Dark theme
Copy code
```
java -jar hap-sign-tool.jar sign-app -keyAlias "demo_key" -signAlg "SHA256withECDSA" -mode "localSign" -appCertFile "/path/demo.cer" -profileFile "/path/demo.p7b" -inFile "/path/hap-unsigned.hap" -keystoreFile "/path/demo.p12" -outFile "/path/hap-signed.hap" -keyPwd "123456Abc" -keystorePwd "123456Abc"
```
In the preceding command, modify settings of the following parameters and keep the other parameters as they are:
- keyAlias: key alias.
- appCertFile: debug certificate file in .cer format.
- profileFile: debug profile file in .p7b format.
- inFile: HAP to sign.
- keystoreFile: keystore file in .p12 format.
- outFile: HAP that carries the signature information, to be generated after the signing.
- keyPwd: key password.
- keystorePwd: keystore password.
NOTE

To sign an APP Pack, modify the inFile and outFile parameters in the preceding command to point to the APP Pack.

Running an App

Use hdc to push a signed HAP to a real device for installation. Note that if the pushed HAP is not signed, the installation will fail.

To push a HAP, run the following commands:

Collapse
Word wrap
Dark theme
Copy code
# Push the HAP to the device.
hdc file send "{PROJECT_PATH}/entry/build/default/outputs/default/entry-default-signed.hap" "data/local/tmp/entry-default-signed.hap"
# Install the HAP.
hdc shell bm install -p "data/local/tmp/entry-default-signed.hap"
# Delete the HAP.
hdc shell rm -rf "data/local/tmp/entry-default-signed.hap"

To run the HAP on the device, run the following command:

Collapse
Word wrap
Dark theme
Copy code
hdc shell aa start -a EntryAbility -b com.example.myapplication -m entry

Script Example

NOTE

The following example is not ready for direct use. Adapt it to meet your specific requirements.

Collapse
Word wrap
Dark theme
Copy code
#!/bin/bash
set -ex

JAVA_HOME=xxx # Specify the installation directory of the JDK.
COMMANDLINE_TOOL_DIR=xxx # Specify the installation directory of the command line tool.

# Configure the hvigor and ohpm environment variables.
export PATH=${COMMANDLINE_TOOL_DIR}/command-line-tools/bin:$PATH

# Download and configure JDK.
function init_JDK() {
  if [ ! -d "${JAVA_HOME}" ]; then 
     mkdir "${JAVA_HOME}"
  fi
  cd ${JAVA_HOME}
  wget --no-check-certificate -q "${jdk_download_path}" -O jdk-linux.tar.xz # Download JDK, specifying the actual download path.
  tar -vxf jdk-linux.tar.xz
  JDK_DIR=xxx # Specify the directory in the compressed JDK package.
  cd ${JDK_DIR}
  mv -f ./* .[^.]* ../
  cd ..
  rm -rf JDK_DIR jdk-linux.tar.xz
  export JAVA_HOME=${JAVA_HOME}
  export PATH=$JAVA_HOME/bin:$PATH
  java -version
}

# Configure the hdc environment variable.
function init_hdc() {
  export HDC_HOME=${COMMANDLINE_TOOL_DIR}/command-line-tools/sdk/default/openharmony/toolchains # Set the hdc environment variable. hdc is stored in toolchains.
  export PATH=$HDC_HOME:$PATH
}

# Install ohpm. Skip this step if ohpm already exists in the image.
function init_ohpm() {
    ohpm -v
    # Configure the address of the ohpm repository.
    ohpm config set registry https://ohpm.openharmony.cn/ohpm/
}

# Initialize related paths.
PROJECT_PATH=xxx  # Project directory.
# Go to the package directory and install the dependency.
function ohpm_install {
    cd $1
    ohpm install
}
# Environment adaptation
function buildHAP() {
# Install the third-party library dependencies based on service requirements.
    ohpm_install "${PROJECT_PATH}"
    ohpm_install "${PROJECT_PATH}/entry"
    ohpm_install "${PROJECT_PATH}/xxx"
    # Run commands based on your service requirements. For details, see the commands in the DevEco Studio build log.
    cd ${PROJECT_PATH}
    hvigorw clean --no-daemon
    hvigorw assembleHap --mode module -p product=default -p debuggable=false --no-daemon # It is recommended that --no-daemon be added to the end of the command.
}
function install_hap() {
    hdc file send "${PROJECT_PATH}/entry/build/default/outputs/default/entry-default-signed.hap" "data/local/tmp/entry-default-signed.hap"
    hdc shell bm install -p "data/local/tmp/entry-default-signed.hap" 
    hdc shell rm -rf "data/local/tmp/entry-default-signed.hap"
    hdc shell aa start -a MainAbility -b com.example.myapplication -m entry
}

# Use ohpm to publish the HAR.
function upload_har {
  ohpm publish pkg.har
}

function main {
  local startTime=$(date '+%s')
  init_JDK
  init_hdc
  init_ohpm
  buildHAP
  install_hap
  upload_har
  local endTime=$(date '+%s')
  local elapsedTime=$(expr $endTime - $startTime)
  echo "build success in ${elapsedTime}s..."
}
main

Creating a CI Pipeline Offline

If your computer is not connected to the Internet, you can build a pipeline environment by referring to the following steps.

Installing the pnpm Plugin

On the computer that has Internet access, create an empty folder and in it create the package.json file. Enter the following information in the file:
Collapse
Word wrap
Dark theme
Copy code
```
{
  "dependencies": {
    "pnpm": "8.13.1"
  }
}
```
Configure environment variables, open the CLI, and run the npm install command in the folder to generate the node_modules folder.
Copy the node_modules folder and package.json file to the C:\Users\Username\.hvigor\wrapper\tools directory on the computer without Internet access. If the directory does not exist, create one first.
On the computer where Internet access is denied, run the following command to enable the npm offline mode:
Collapse
Word wrap
Dark theme
Copy code
```
npm config set offline true
```

Installing the npm Plugin

On the computer that has Internet access, create an empty folder and in it create the package.json file. Enter the following information in the file:
Collapse
Word wrap
Dark theme
Copy code
```
{
  "dependencies": {
    "ajv": "latest"
  }
}
```
Open the CLI and run the npm install command in the folder to generate the node_modules folder.
Copy the node_modules folder to the project's root directory on the computer without Internet access.

Installing the ohpm Plugin

For details, see Installing a Third-Party Library.

Installing the libGL1 Library

To install the libGL1 library, which is required for using texture compression on Linux:

Download the libGL1 library installation package on a computer with Internet access, for example, download libgl1-mesa-dev on Ubuntu/Debian and mesa-libGL-devel on CentOS/RHEL, then copy the downloaded package to the offline computer for installation.