DEV Community: ZHZL-m

【Journey of HarmonyOS Next】DevEco Studio User Guide (38)

ZHZL-m — Sun, 29 Jun 2025 01:56:52 +0000

1 -> Introduction

Build mode: DevEco Studio provides two build modes by default: debug and release, and developers can customize the build mode.

Product format: The constructed HAR package products are divided into three product formats: HAR containing source code, HAR containing js intermediate code, and HAR containing bytecode.

In the debug build mode, starting from DevEco Studio NEXT Beta 1 (5.0.3.800), the default product is bytecode HAR, which is used for local commissioning by developers to improve compilation and build efficiency, and supports building HAR containing source code.

When the release mode is released, starting from DevEco Studio NEXT Developer Beta 3 (5.0.3.600), obfuscation is not enabled by default, and the build product is the same as the debug mode.

2 -> Use Constraints

The HAR package does not support configuring the extension component in module.json5.
The HAR package does not support pages routing configuration.
It is not recommended to refer to the local module in the build of the HAR itself, which may cause the installation failure when other modules depend on the HAR package, if the installation fails, you need to configure overrides in the engineering level oh-package.json5.
When building a HAR in release mode, the obfuscation of the ArkTS code only supports Stage models with API 10 and above.
When referencing a bytecode Har package, it is not available when the API version of the bytecode Har package is higher than the compatibleSDKVersion of the project.
If both the bytecode Har package and the compatibleSDKVersion of the Hap project are API 12, the compatibleSdkVersionStage of the bytecode Har package is higher than the compatibleSdkVersionStage of the Hap project.

3 -> Create a module

When creating a new project, select a Stage model with API 10 or later, and create a new Static Library module after the project is created.

Write code.

library // HAR root directory ├─libs // Native libraries that store user-defined references, usually .so files └─src │ └─main │ ├─cpp │ │ ├─types // Define the interface exposed by the Native API │ │ │ │ └─liblibrary │ │ │ ├─index.d.ts │ │ │ └─oh-package.json5 │ │ ├─CMakeLists.txt // CMake configuration file │ │ └─napi_init.cpp // C++ source code file │ └─ets // ArkTS source code directory │ │ └─components │ │ └─MainPage.ets │ ├─resources // resource directory, used to store resource files, such as pictures, multimedia, strings, etc. │ └─module.json5 // module configuration file, Contains the configuration information of the current HAR ├─build-profile.json5 // Hvigor compiles and builds the configuration file required for the build, including compilation options ├─hvigorfile.ts // Hvigor build script file, including plug-ins and custom tasks to build the current module ├─Index.ets // The entry file of the HAR is generally used as the export definition of the functions and components provided by the HAR └─oh-package.json5 // The description file of the HAR, which defines the basic information and dependencies of the HAR

In oh-package.json5, the "main" field defines the entry point for the export file. If you do not set the main field, Index.ets is used as the entry file in the current directory by default, and the search is made in the order of .ets >.ts>.js. Let's take the ets/components/MainPage.ets file as an entry file as an example:

{
  ...
  "main": "./src/main/ets/components/MainPage.ets",
  ...
}

4 -> Build a HAR

4.1 -> Build HAR in debug mode

The product is a HAR package that contains the source code, resource files, and configuration files, etc., which is convenient for developers to conduct local commissioning oh_modules node_modules. cxx、. previewer、. hvigor、. gitignore、. ohpmignore、. gitignore/.ohpmignore and the CMakeLists.txt of the cpp project.

illustrate

If it is a Native project, the Native product built in debug mode does not contain debugging information and symbol tables.
Starting from version 5.0.3.403, it is no longer recommended to use relative paths to reference code files across modules.
Starting from version 5.0.3.403, the process of building a HAR in debug/release mode uses the same syntax validation rules.

Set the useNormalizedOHMUrl field in project-level build-profile.json5 to false.

illustrate

With DevEco Studio NEXT Beta 1 (5.0.3.800) or earlier, the default value of the useNormalizedOHMUrl field in engineering-grade build-profile.json5 is false, so you do not need to perform this step.

{
  "app": {
    "products": [
      {
         "buildOption": {
           "strictMode": {
             "useNormalizedOHMUrl": false
           }
         }
      }
    ]
  }
}

Click on the DevEco Studio icon in the top right corner

and select debug for Build Mode. The default mode is mode: the release mode is used when compiling apps, and the debug mode is used when compiling HAP/HSP/HARR.

If some project source files do not need to be built into the HAR package, you can create a .ohpmignore file in the module directory, configure the files to be ignored during packaging, and support regular expression writing. Write the file/folder name that does not need to be packed into the HAR package to the .ohpmignore file. DevEco Studio builds will filter out files/folders contained in the .ohpmignore file.

Select the root directory of the HAR module and click Build > Make Module '' to start the build.

After the build is complete, the HAR package is generated in the build directory.

After the HAR package product is decompressed, the structure is as follows:

4.2 -> Build the HAR in release mode
Starting from DevEco Studio NEXT Developer Beta 3 (5.0.3.600), obfuscation is not enabled by default, and the build product is the same as the debug mode.

After obfuscation is enabled, the build product is a HAR package containing js intermediate code, which contains the js intermediate code file, resource file, configuration file, readme, changelog declaration file, and license certificate file generated after source code obfuscation, which is used to publish to the ohpm central repository.

Click on the DevEco Studio icon in the top right corner

and select release in Build mode. The default mode is mode: the release mode is used when compiling apps, and the debug mode is used when compiling HAP/HSP/HARR.

If the compilation mode is set to release, we recommend that you enable obfuscation/ruleOptions in the buildOptionSet configuration of the release file in the module-level build-profile.json5 file to enable to protect code assets.

{
  "apiType": "stageMode",
  "buildOption": {
  },
  "buildOptionSet": [
    {
      "name": "release",
      "arkOptions": {
        // 混淆相关参数
        "obfuscation": {
          "ruleOptions": {
            // true表示进行混淆，false表示不进行混淆。5.0.3.600及以上版本默认为false
            "enable": true,
            // 混淆规则文件
            "files": [
              "./obfuscation-rules.txt"
            ]
          },
          // consumerFiles中指定的混淆配置文件会在构建依赖这个library的工程或library时被应用
          "consumerFiles": [
            "./consumer-rules.txt"
          ]
        }
      },
    },
  ],
  "targets": [
    {
      "name": "default"
    }
  ]
}

Set the useNormalizedOHMUrl field in project-level build-profile.json5 to false.

illustrate

With DevEco Studio NEXT Beta 1 (5.0.3.800) or earlier, the default value of the useNormalizedOHMUrl field in engineering-grade build-profile.json5 is false, so you do not need to perform this step.

{
  "app": {
    "products": [
      {
         "buildOption": {
           "strictMode": {
             "useNormalizedOHMUrl": false
           }
         }
      }
    ]
  }
}

Select the root directory of the HAR module and click Build > Make Module '' to start the build.

After the build is complete, the HAR package is generated in the build directory.

After the HAR package product is decompressed, the structure is as follows:

4.3 -> Construct a HAR in bytecode format

The default product is a HAR package containing bytecode, which contains abc bytecode, resource files, configuration files, readme, changelog declaration files, and license certificate files, improving the security of products released to the ohpm central repository.

Since the bytecode HAR package contains the compiled abc bytecode, when the bytecode HAR is dependent on other application modules (HAP/HSP), there is no need to perform syntax check and compilation operations on the code in the dependent HAR when the application module is compiled and built, which can effectively improve the compilation and construction efficiency of the application module compared with the HAR containing source code and the HAR containing js intermediate code.

illustrate

Since building a bytecode HAR requires generating a binary format, building a bytecode HAR alone can take more time than building a non-bytecode HAR.
When the bytecode HAR is used by the integration, useNormalizedOHMUrl in build-profile.json5 of the project must be set to true.
If obfuscation is not enabled for bytecode HAR, the HAR package will no longer be obfuscated when the bytecode HAR is integrated and used.
The dependencies used by bytecode HAR need to be configured in the dependencies or dynamicDependencies of oh-package.json5 of this module, if not configured, a runtime exception will occur when the bytecode HAR is integrated.
Different build modes are supported, which is the same as building HAP/HSP.

Set useNormalizedOHMUrl of project-level build-profile.json5 to true.

illustrate

Starting from DevEco Studio NEXT Beta 1 (5.0.3.800), the useNormalizedOHMUrl field in project-level build-profile.json5 is true by default, and byteCodeHar is true by default.

{
  "app": {
    "products": [
      {
         "buildOption": {
           "strictMode": {
             "useNormalizedOHMUrl": true
           }
         }
      }
    ]
  }
}

In the build-profile.json5 of the HAR module, set byteCodeHar to true.

{
  "buildOption": {
    "arkOptions": {
      "byteCodeHar": true
    }
  }
}

Select the root directory of the HAR module and click Build > Make Module '' to start the build.

After the build is complete, the HAR package is generated in the build directory.

After the HAR package product is decompressed, the structure is as follows:

4.4 -> Sign the HAR

DevEco Studio supports signing HARs on top of building HAR processes. The signed HAR package can be used to access the ecosystem marketplace in the future.

illustrate

This capability is supported only in SDKs running Compatible SDK 5.0.0(12) or later.
Make sure that Daemon is enabled for the current project, open Settings > Build, Execution, Deployment > Build Tools > Hvigor, and check the field Enable the Daemon for tasks.
In hvigor-config.json5, enable the Build Signature HAR:

{
  "properties": {
    "ohos.sign.har": true
  }
}

Configure the project signature information, please refer to Configuring the Signature Information for the configuration process.
Select the root directory of the HAR module and click Build > Make Module '' to start the build.

After the build is complete, the signed HAR package is generated in the build directory.

【Journey of HarmonyOS Next】DevEco Studio User Guide (37)

ZHZL-m — Sun, 29 Jun 2025 01:51:59 +0000

1 -> Configure CPP

Hvigor integrates cmake, ninja is a tool for building cpp code. In the initial state, you do not need additional configuration, in order to customize your CPP code compilation, you can add custom configuration through the following configuration.

In the build-profile.json5 of the module, the following configuration items exist:

{
  ...
  "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": [], // 按照.so文件的优先级顺序，打包最高优先级的.so文件
          "pickLasts": [], // 按照.so文件的优先级顺序，打包最低优先级的.so文件
          "enableOverride": true, // 当.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"]
          }
        ]
      },
    },
  ],
  ...
}

You can modify the compilation performance of cpp by customizing the externalNativeOptions parameter. nativeLib/headerPath declares the module's c/cpp interface file and exposes it to the dependent module via packaging. You can modify the volume and packaging rules of so products through configurations such as debugSymbol and filter.

1.1 -> about the priority of the library file so

The priority selection of library file so can be selected by pickFirsts, pickLasts option, where pickFirsts selects the high-priority library file and pickLasts selects the low-priority library file.

This priority is determined by the order in which the module or third-party package is collected, and the dependency declaration of this module is in the dependencies configuration item of the oh-package.json5 file, and the collection order collects the dependencies according to the breadth-first traversal method.

As shown in the figure below, the order of precedence is current > library0 > library1 > library5 > library2 > library3 > library4.

1.2 -> Use of select

Select provides the ability to accurately select native products, and selects or excludes native products to hap/hsp/har products based on package name, version, product name, etc.

For example, if the HAR package of the libcurl.so that this module depends on is @ohos/curl, and there are multiple versions of the libcurl.so, and you need to package version 1.3.5, you can use the following configuration to accurately package this SO into the product.

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

2-> Multi-engineering builds

In order to reduce the complexity of multi-team collaborative development of large-scale applications, a multi-project development mode is provided to improve the efficiency of collaborative development. The multi-project development capability allows you to split a large application into multiple modules, with each module corresponding to a separate project. After each project is compiled and generated separately, an APP needs to be packaged and generated for the application market.

In the project-level build-profile.json5 configuration file of each project, set the value of the multiProjects field to true.

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

Prepare the HAP packaging tool app_packing_tool.jar (in the $DevEco Studio installation directory/sdk/default/openharmony/toolchains/lib).
In the HAP Packaging Tool directory, run the command to package multiple HAPs, as shown in the following example.

java -jar app_packing_tool.jar --mode multiApp --hap-list D:\project\MyApplication\1.hap,D:\project\MyApplication1\2.hap --out-path D:\project\final.app

hap-list: Multiple HAP file paths, separated by commas.
out-path: the path of the generated APP file, for example, "D:\project\final.app".

3 -> Customize the .hvigor directory path

By default, the .hvigor directory is located in the user directory:

Windows：C:\Users\username.hvigor
macOS：/Users/UserName/.hvigor
Linux：
root: /root/.hvigor
Non-root user: /home/UserName/.hvigor
If the disk space of the default directory is insufficient, you need to customize the path of the .hvigor directory, which can be configured by following the following methods:

illustrate

This feature is supported from DevEco Studio 5.0 Canary1 release.

How to set Windows environment variables:
In the system or user variables, add the absolute path of the custom .hvigor directory.

Variable name: HVIGOR_USER_HOME

Variable value: Customize the absolute path to store the .hvigor directory. For example, D:\HvigorUserHome

macOS environment variable setting method:

Setting environment variables for DevEco Studio on macOS requires launchd.

How to set it to take effect temporarily:
Run the launchctl setenv statement in the terminal and restart DevEco Studio.

launchctl setenv HVIGOR_USER_HOME /User/xx #本处路径请替换为.hvigor目录的绝对路径

This setting method will not work after restarting the computer.

How to set the restart without invalidation:
illustrate

The following is just an example of how to set system variables for DevEco Studio on macOS, depending on the system version.

Add the following content to /etc/launchd.conf (if the file does not exist, you can create it yourself):

setenv HVIGOR_USER_HOME /User/xx #本处路径请替换为.hvigor目录的绝对路径

Once the settings are complete, restart your computer before it takes effect.

How to set Linux environment variables:
Open Terminal Tools and run the following command:

vim ~/.bashrc

Add HVIGOR_USER_HOME environment variables.

export HVIGOR_USER_HOME=/home/xx  #本处路径请替换为.hvigor目录的绝对路径

Save and close the file, use the source command to reload the .bashrc configuration file.

source ~/.bashrc

【Journey of HarmonyOS Next】DevEco Studio User Guide (36) -> Configuration and Build (3)

ZHZL-m — Sun, 29 Jun 2025 01:48:54 +0000

1-> Custom HAR multi-objective construction products

Each HAR module supports customization of different targets, and the customization of device types (deviceType), resources, buildOption configuration items (such as C++ dependent .so, obfuscated configurations, abi types, cppFlags, etc.) and source code sets is implemented in the build-profile.json5 file in the module.

illustrate

In the current version, only modules whose target is default are supported when compiling in DevEco Studio. If you want to specify a different target, you need to specify it from the command line and compile it from the command line.

For example, to build a custom target:free harr, run the following command:

hvigorw --mode module -p product=default -p module=library@free -p buildMode=debug assembleHar

1.1 -> Define the deviceType of the product

Each target can be specified with or without deviceType. If it is not defined, the target supports the device type defined in config.json or module.json5 by default.

At the same time, when defining the deviceType of each target, the supported device types must have been defined in config.json or module.json5. For example, in the two targets defined above, default supports all device types by default, and the free version supports only 2-in1 devices.

{ 
  "apiType": 'stageMode', 
  "buildOption": { 
  }, 
  "targets": [ 
    { 
      "name": "default"  //未定义deviceType，默认支持config.json或module.json5中定义的设备类型 
    }, 
    { 
      "name": "free",
      "config": { 
        "deviceType": [  //定义free支持的设备类型为2in1
          "2in1" 
        ] 
      } 
    }
  ] 
}

1.2 -> Define the C++ project dependencies. SO file

In a C++ project, you can customize the .so files that each target depends on. For example, a module depends on the function1.so, function2.so, and function3.so files, and the product with target is default depends on the function1.so and function2.so. If the target is a product of VIP and depends on function1.so and function3.so, the sample code is as follows:

{
  "apiType": 'stageMode',
  "buildOption": {
    "externalNativeOptions": {
      "path": "./src/main/cpp/CMakeLists.txt",
      "arguments": [],
      "abiFilters": [
        "arm64-v8a",
        "x86_64"
      ],
      "cppFlags": "",
    }
  },
  "targets": [  //定义不同的target 
    {
      "name": "default",
      "config": {
        "buildOption": {
          "nativeLib": {
            "filter": {
              //按照.so文件的优先级顺序，打包最高优先级的function1.so文件 
              "pickFirsts": [
                "**/function1.so"
              ],
              //排除不打包的function3.so文件 
              "excludes": [
                "**/function3.so"
              ],
              //允许当.so中资源重名冲突时，使用高优先级的.so文件覆盖低优先级的.so文件 
              "enableOverride": true
            }
          }
        }
      }
    },
    {
      "name": "vip",
      "config": {
        "buildOption": {
          "nativeLib": {
            "filter": {
              //按照.so文件的优先级顺序，打包最高优先级的function1.so文件 
              "pickFirsts": [
                "**/function1.so"
              ],
              //排除不打包的function2.so文件 
              "excludes": [
                "**/function2.so"
              ],
              //允许当.so中资源重名冲突时，使用高优先级的.so文件覆盖低优先级的.so文件 
              "enableOverride": true
            }
          }
        }
      }
    }
  ]
}

1.3 -> Define the resources of the product

There may be differences in the resource files used by each target, and developers can store the resources used by each target in different resource directories during the development process. Among them, the ArkTS project supports customization of the resource file directory in the main directory. JS projects support customization of the resource file directory (resource) in the main directory and the resource file directory (res) in Ability. The following is an example of customizing the resource file directory of an ArkTS project:

{ 
  "apiType": 'stageMode', 
  "buildOption": { 
  }, 
  "targets": [ 
    { 
      "name": "default",
      "resource": {  //定义默认版target使用的资源文件目录 
        "directories": [ 
          "./src/main/resources_default" 
        ] 
      } 
    }, 
    { 
      "name": "free", 
      "config": { 
        "deviceType": [ 
          "2in1" 
        ] 
      }, 
      "resource": {  //定义免费版target使用的资源文件目录 
        "directories": [ 
          "./src/main/resources_default", 
          "./src/main/resources_free" 
        ] 
      } 
    },
  ] 
}

2 -> Configure the APP multi-objective build product

APP is used for the release of applications/meta-services, and different products can be customized for different application scenarios, and each product supports customization of bundleName, bundleType, signature information, icon and label, and the target included.

Define the target product

Each product corresponds to a customized APP package, so the name of the product that needs to be customized should be planned in advance before customizing the APP multi-target construction product. For example, define productA and productB. An example of the project-level build-profile.json5 file is as follows:

When customizing a product, there must be a "default" product, otherwise there will be an error when compiling.

"app": { 
  "signingConfigs": [], 
  "products": [ 
    { 
      "name": "default", 
      "signingConfig": "default", 
      "compatibleSdkVersion": "5.0.2(14)", 
      "runtimeOS": "HarmonyOS", 
    }, 
    { 
      "name": "productA", 
      "compatibleSdkVersion": "5.0.2(14)", 
      "runtimeOS": "HarmonyOS", 
    }, 
    { 
      "name": "productB", 
      "compatibleSdkVersion": "5.0.2(14)", 
      "runtimeOS": "HarmonyOS", 
    } 
  ], 
  "buildModeSet": [ 
    { 
      "name": "debug", 
    }, 
    { 
      "name": "release" 
    } 
  ] 
}

2.1 -> Define the APP package name and supplier name of the product

Each product can be specified with a product name and a supplier name.

{ 
  "app": { 
    "signingConfigs": [], 
    "products": [ 
      { 
        "name": "default", 
        "signingConfig": "default", 
        "compatibleSdkVersion": "5.0.2(14)", 
        "runtimeOS": "HarmonyOS", 
        "output": { 
          "artifactName": "customizedProductOutputName-1.0.0"  //产物名称为customizedProductOutputName-1.0.0
        }, 
        "vendor": "customizedProductVendorName"   //供应商名称为customizedProductVendorName
      }, 
      { 
        "name": "productA", 
        "compatibleSdkVersion": "5.0.2(14)", 
        "runtimeOS": "HarmonyOS", 
        "output": { 
          "artifactName": "customizedProductOutputNameA-1.0.0"  //产物名称为customizedProductOutputNameA-1.0.0
        }, 
        "vendor": "customizedProductVendorNameA"   //供应商名称为customizedProductVendorNameA
      }, 
      { 
        "name": "productB", 
        "compatibleSdkVersion": "5.0.2(14)", 
        "runtimeOS": "HarmonyOS", 
        "output": { 
          "artifactName": "customizedProductOutputNameB-1.0.0" //产物名称为customizedProductOutputNameB-1.0.0
        }, 
        "vendor": "customizedProductVendorNameB"   //供应商名称为customizedProductVendorNameB
      } 
    ], 
    "buildModeSet": [ 
      { 
        "name": "debug", 
      }, 
      { 
        "name": "release" 
      } 
    ] 
  }, 
}

If a signature has been configured, the APP package name corresponding to the product is the name customized by the developer. If no signature is configured, the app package name corresponding to the product is the customized name + unsigned.

2.2 -> Define the bundleName of the product

Different bundleNames can be customized for each defined product, and if the product does not have a bundleName, the default bundleName of the project is used. An example is shown below:

"app": { 
  "signingConfigs": [], 
  "products": [ 
    { 
      "name": "default", 
      "signingConfig": "default",
      "compatibleSdkVersion": "5.0.2(14)", 
      "runtimeOS": "HarmonyOS", 
      "bundleName": "com.example00.com"  //定义default的bundleName信息 
    }, 
    { 
      "name": "productA", 
      "signingConfig": "default",

      "compatibleSdkVersion": "5.0.2(14)", 
      "runtimeOS": "HarmonyOS", 
      "bundleName": "com.example01.com"  //定义productA的bundleName信息
    }, 
    { 
      "name": "productB", 
      "signingConfig": "default",
      "compatibleSdkVersion": "5.0.2(14)", 
      "runtimeOS": "HarmonyOS", 
      "bundleName": "com.example02.com"  //定义productB的bundleName信息 
    } 
  ], 
  "buildModeSet": [ 
    { 
      "name": "debug", 
    }, 
    { 
      "name": "release" 
    } 
  ] 
}

2.3 -> Define the bundleType of the product

Different bundleTypes can be customized for each defined product. Developers can define the product type by defining the bundleType of each product:

The bundleType value is app, which indicates that the product is an application.
The bundleType value is atomicService, indicating that the product is a metaservice.
If the product does not have a bundleType defined, the bundleType of the project (that is, the Application/Atomic Service selected when creating the project) is used. An example is shown below:

"app": { 
  "signingConfigs": [], 
  "products": [ 
    { 
      "name": "default", 
      "signingConfig": "default",
      "compatibleSdkVersion": "5.0.2(14)", 
      "runtimeOS": "HarmonyOS", 
      "bundleName": "com.example00.com",   
      "bundleType": "app" //定义default的bundleType信息 
    },
    { 
      "name": "productA", 
      "signingConfig": "default",
      "compatibleSdkVersion": "5.0.2(14)", 
      "runtimeOS": "HarmonyOS", 
      "bundleName": "com.example01.com",    
      "bundleType": "atomicService"  //定义productA的bundleType信息 
    },
    { 
      "name": "productB", 
      "signingConfig": "default",
      "compatibleSdkVersion": "5.0.2(14)", 
      "runtimeOS": "HarmonyOS", 
      "bundleName": "com.example02.com",    
      "bundleType": "atomicService"  //定义productB的bundleType信息 
    } 
  ], 
  "buildModeSet": [ 
    { 
      "name": "debug", 
    },
    { 
      "name": "release"
    } 
  ] 
}

2.4 -> Define the signature configuration information of the product

For each defined product, different signingConfig signature files can be customized, and if the product does not have a signingConfig defined, the unsigned APP package will be built.

In most cases, you first need to configure the signature information on the signature configuration page or in the build-profile.json5 file of the project. For example, on the File > Project Structure > Project > Signing Configs page, configure the signatures of default, productA, and productB, as shown in the following figure:

After the signature information is configured, add the signature file corresponding to each product, as shown in the following example:

You can also define the signature file information in the product in advance, and then sign each product on the signature page to ensure that the product signature file is the same as the signature file on the signature page.

"app": { 
  "signingConfigs": [], //此处通过界面配置签名后会自动生成相应的签名配置，本文略 
  "products": [ 
    { 
      "name": "default", 
      "signingConfig": "default", //定义default的签名文件信息
      "compatibleSdkVersion": "5.0.2(14)", 
      "runtimeOS": "HarmonyOS", 
      "bundleName": "com.example00.com"  
    }, 
    { 
      "name": "productA", 
      "signingConfig": "productA", //定义productA的签名文件信息
      "compatibleSdkVersion": "5.0.2(14)", 
      "runtimeOS": "HarmonyOS", 
      "bundleName": "com.example01.com"  
    }, 
    { 
      "name": "productB", 
      "signingConfig": "productB", //定义productB的签名文件信息
      "compatibleSdkVersion": "5.0.2(14)", 
      "runtimeOS": "HarmonyOS", 
      "bundleName": "com.example02.com" 
    } 
  ], 
  "buildModeSet": [ 
    { 
      "name": "debug", 
    }, 
    { 
      "name": "release" 
    } 
  ] 
}

2.5 -> Define the icon and label of the product

Different icons and labels can be customized for each defined product, and if the product does not have icons and labels defined, the default icons and labels of the project are used. An example is shown below:

illustrate

The icon and label fields in products will replace the corresponding fields in app.json5 at compile time, and both app.json5 and module.json5 can be configured.

{
  "app": {
    "signingConfigs": [],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.2(14)",
        "runtimeOS": "HarmonyOS",
        "icon":"$media:default_icon", //定义default的icon
        "label":"$string:default_name", //定义default的label
      },
      {
        "name": "productA",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.2(14)",
        "icon":"$media:productA_icon", //定义productA的icon
        "label":"$string:productA_name", //定义productA的label
      },
      {
        "name": "productB",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.2(14)",
        "runtimeOS": "HarmonyOS",
        "icon":"$media:productB_icon", //定义productB的icon
        "label":"$string:productB_name",  //定义productB的label
      }
    ],
    "buildModeSet": [
      {
        "name": "debug",
      },
      {
        "name": "release"
      }
    ]
  },
  ...
}

2.6 -> Define the target contained in the product

You can select the product to which you want to package the defined targets, and each product can specify one or more targets.

At the same time, each target can also be packaged into a different product, but different targets of the same module cannot be packaged into the same product (unless different targets of the module are configured with different deviceType or distributionFilter/distroFilter).

For example, if you have defined default, free, and pay, you need to package the default target into the default product. Package the free target into productA; Package the pay target into productB, and the corresponding sample code is as follows:

{ 
  "app": { 
    "signingConfigs": [], //此处通过界面配置签名后会自动生成相应的签名配置，本文略 
    "products": [ 
      { 
        "name": "default", 
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.2(14)", 
        "runtimeOS": "HarmonyOS", 
        "bundleName": "com.example00.com"  
      }, 
      { 
        "name": "productA", 
        "signingConfig": "productA",
        "compatibleSdkVersion": "5.0.2(14)", 
        "runtimeOS": "HarmonyOS", 
        "bundleName": "com.example01.com"  
      }, 
      { 
        "name": "productB", 
        "signingConfig": "productB",  
        "compatibleSdkVersion": "5.0.2(14)", 
        "runtimeOS": "HarmonyOS", 
        "bundleName": "com.example02.com" 
      } 
    ], 
  "modules": [ 
    { 
      "name": "entry", 
      "srcPath": "./entry", 
      "targets": [ 
        { 
          "name": "default",  //将default target打包到default APP中 
          "applyToProducts": [ 
            "default" 
          ] 
        }, 
        { 
          "name": "free",  //将free target打包到productA APP中 
          "applyToProducts": [ 
            "productA" 
          ] 
        }, 
        { 
          "name": "pay",  //将pay target打包到productB APP中 
          "applyToProducts": [ 
            "productB" 
          ] 
        } 
      ] 
    } 
  ] 
}

3 -> Multi-product construction target

align target: the target with the highest priority during compilation and build. After the align target is configured in the project, if the align target exists in the module, the align target is automatically selected for construction. The scope of align target is the entire project, and only one can be configured, and it supports two modes: command line and configuration file.

The following is an example of a command-line approach:

hvigorw -c properties.ohos.align.target=target1 assembleHap

Add ohos.align.target to the hvigor-config.json5 configuration file, as shown below:

"properties": {
  'ohos.align.target': 'target1'
},

fallback target: If the module does not have a specified target, default will be used to build, but if you do not want to use default to build, you can configure a fallback target, and if the specified target cannot be found, if there is a fallback target in the module, the fallback target will be used to build. The scope of the fallback target is the entire project, which can be configured with multiple items, and when multiple are configured, the first hit will take effect in the order of the array.

The following is an example of a command-line approach:

hvigorw -c properties.ohos.fallback.target=target1,target2 assembleHap

Add ohos.fallback.target to the hvigor-config.json5 configuration file, as shown below:

"properties": {
  'ohos.fallback.target': ['target1', 'target2']
}

illustrate

The align target and fallback target configuration mode take precedence over the configuration file.
If you use a configuration file to configure align target and fallback target, you can use the HDC command line to push and run packages.
The priority order of multiple targets is as follows: align target > the command line specifies the module target > the parent module target > fallback target > default.

Illustrate:

The project relies on entry->lib1->lib2 and needs to build multiple products A, B, and C.

entry: A、B、default

lib1: B、C、default

lib2: A、C、default

Set align target to A and fallback target to C. Then the compilation command when building the hap is:

hvigorw --mode module -p module=entry -c properties.ohos.align.target=A -c properties.ohos.fallback.target=C assembleHap

The target selection for compilation is: entry@A, lib1@C, lib2@A.

illustrate

All of the above instructions are for non-ohosTest mode only. In ohosTest mode, the dependent target is fixed to default, and no other targets take effect.

【Journey of HarmonyOS Next】DevEco Studio User Guide (35) -> Configuration and Build (2)

ZHZL-m — Sun, 29 Jun 2025 01:44:10 +0000

1-> Customized HAP multi-objective construction products

Each Entry/Feature module supports customization of different targets, and by implementing differentiated customization in the build-profile.json5 file in the module, it currently supports HAP package name, device type (deviceType), source code set (source), resource (resource), buildOption configuration items (such as C++ dependent .so, obfuscated configuration, abi type, cppFlags, etc.), distribution rules (distributionFilter) customization.

Define the target product

Each target corresponds to a customized HAP, so you should plan the target name that needs to be customized in advance before customizing the HAP multi-target construction product. For example, if you use the ArkTS Stage model as an example, you can define a free version and a paid version, and the module-level build-profile.json5 file is as follows:

{ 
  "apiType": 'stageMode', 
  "buildOption": {   
  }, 
  "targets": [  //定义不同的target 
    { 
      "name": "default",  //默认target名称default 
    }, 
    { 
      "name": "free",  //免费版target名称 
    }, 
    { 
      "name": "pay",  //付费版target名称 
    } 
  ] 
}

According to the definition of the target above, three different HAPs of default, free and pay will be generated at the same time during compilation and construction.

1.1 -> Define the HAP package name of the product

Each target can be named with a product.

{ 
  "apiType": "stageMode", 
  "buildOption": { 
  }, 
  "targets": [ 
    { 
      "name": "default", 
      "output": { 
        "artifactName": "customizedTargetOutputName-1.0.0"  //产物名称为customizedTargetOutputName-1.0.0
      } 
    }, 
    { 
      "name": "free", 
      "output": { 
        "artifactName": "customizedTargetOutputName1-1.0.0"  //产物名称为customizedTargetOutputName1-1.0.0
      } 
    }, 
    { 
      "name": "pay", 
      "output": { 
        "artifactName": "customizedTargetOutputName2-1.0.0"  //产物名称为customizedTargetOutputName2-1.0.0
      } 
    } 
  ] 
}

If a signature is configured, the HAP package name corresponding to the target product is the name customized by the developer. If no signature is configured, the HAP package name of the target product is the name customized by the developer + unsigned.

1.2 -> Define the deviceType of the product

Each target can be specified with or without deviceType. If it is not defined, the target supports the device type defined in config.json or module.json5 by default.

At the same time, when defining the deviceType of each target, the supported device types must have been defined in config.json or module.json5. For example, in the three targets defined above, default supports all device types by default, and the free and pay versions support only phone devices.

{ 
  "apiType": 'stageMode', 
  "buildOption": { 
  }, 
  "targets": [ 
    { 
      "name": "default",  //未定义deviceType，默认支持config.json或module.json5中定义的设备类型 


    }, 
    { 
      "name": "free", 
      "config": { 
        "deviceType": [  //定义free支持的设备类型为phone 
          "phone" 
        ] 
      } 
    }, 
    { 
      "name": "pay", 
      "config": { 
        "deviceType": [  //定义pay支持的设备类型为phone 
          "phone" 
        ] 
      } 
    } 
  ] 
}

1.3 -> Define the distributionFilter of the product

If the distribution rule of the target is not defined, the distroFilter/distributionFilter distribution rule of the module configuration shall prevail.

If multiple targets have the same device type, you need to specify the distributionFilter distribution rule for targets of the same device type.

If the project is an FA project, replace the distributionFilter field with distroFilter.

{ 
  "apiType": "stageMode", 
  "buildOption": { 
  }, 
  "targets": [ 
    { 
      "name": "default", 


    }, 
    { 
      "name": "free", 
      "config": { 
        "distributionFilter": {  // 具体请参考distributionFilter标签
          "screenShape": { // 屏幕形状枚举 
            "policy": "include", 
            "value": ["circle"] 
          } 
        } 
      } 
    }, 
    { 
      "name": "pay", 
      "config": { 
        "distributionFilter": { 
          "screenShape": { 
            "policy": "include", 
            "value": ["rect"] 
          } 
        } 
      } 
    } 
  ] 
}

1.4 -> Define the subcontracting of product preloads

For metaservices, each target can specify the subcontracting of preloads, or it may not be defined. If not, the configuration in module.json5 prevails.

{ 
  "apiType": 'stageMode', 
  "showInServiceCenter": true, 
  "buildOption": { 
  }, 
  "targets": [   
    { 
      "name": "default",   
    },
    { 
      "name": "free",   
    },
    { 
      "name": "pay",   
      "config": { 
        "atomicService": { 
          "preloads": [  //指定preloads的分包 
            { 
              "moduleName": "preloadSharedLibrary"
            } 
          ] 
        } 
      } 
    } 
  ] 
}

1.5 -> Define the source set of the product -pages

For source code set customization, due to the differences between the Stage model and the FA model, the Stage model supports customization of the page page in the pages source code directory, and the FA model supports the customization of the page page in the Ability source code directory.

For example, for a project in the Stage model, three pages are defined in the pages directory of the module: Index.ets, Page1.ets, and Page2.ets. The Index.ets page is used for default, the Index.ets and Page1.ets pages are used for free, and the Index.ets and Page2.ets pages are used for pay.

{ 
   "apiType": 'stageMode', 
   "buildOption": { 
   }, 
   "targets": [ 
     { 
       "name": "default", 
       "source": {  //定义Stage模型中默认版target的pages源码文件
         "pages": [ 
           "pages/Index" 
         ] 
       } 
     }, 
     { 
       "name": "free", 
       "config": { 
         "deviceType": [ 
           "phone" 
         ] 
       }, 
       "source": {  //定义Stage模型中免费版target的pages源码文件
         "pages": [ 
           "pages/Index", 
           "pages/Page1" 
         ] 
       } 
     }, 
     { 
       "name": "pay", 
       "config": { 
         "deviceType": [ 
           "phone" 
         ] 
       }, 
       "source": {  //定义Stage模型中付费版target的pages源码文件
         "pages": [ 
           "pages/Index", 
           "pages/Page2" 
         ] 
       } 
     } 
   ] 
 }

For example, in the FA model, index.ets, page1.ets, and page2.ets are defined in the MainAbility of the module, where the index.ets page is used for default. free uses the index.ets and page1.ets pages, and pay uses the index.ets and page2.ets pages.

{ 
   "apiType": 'faMode', 
   "buildOption": { 
   }, 
   "targets": [ 
     { 
       "name": "default", 
       "source": {  //定义FA模型中默认版target的pages源码文件
         "abilities": [ 
           { 
             "name": ".MainAbility", 
             "pages": [ 
               "pages/index" 
             ] 
           } 
         ], 
       } 
     }, 
     { 
       "name": "free", 
       "config": { 
         "deviceType": [ 
           "phone" 
         ] 
       }, 
       "source": {  //定义FA模型中免费版target的pages源码文件
         "abilities": [ 
           { 
             "name": ".MainAbility", 
             "pages": [ 
               "pages/index", 
               "pages/page1" 
             ] 
           } 
         ], 
       } 
     }, 
     { 
       "name": "pay", 
       "config": { 
         "deviceType": [ 
           "phone" 
         ] 
       }, 
       "source": {  //定义FA模型中付费版target的pages源码文件
         "abilities": [ 
           { 
             "name": ".MainAbility", 
             "pages": [ 
               "pages/index", 
               "pages/page2" 
             ] 
           } 
         ], 
       } 
     } 
   ] 
 }

1.6 -> Define the source source set of the product -sourceRoots

In the main code space (src/main) of the module, the public code written by the developer is hosted. If developers need to implement differentiated logic between different targets, they can use the differentiated codespace (sourceRoots). Combined with the ability of differentiated code space, you can compile the corresponding code into the final product for different targets under the condition that the code in the main code space remains unchanged.

Concept note

packageName: the value of the name field in oh-package.json5 of the current module.
sourceRoot： | where the is src/main, is customizable, and the addressing priority is > .
sourcePath: the directory of the code structure in sourceRoot.
sourceFileName: the name of the ets file in the code directory.
For example, the following project catalog:

packageName is entry.
sourceRoot is src/main and src/target.
sourcePath is set to ets/code and util.
sourceFileName is test.ets and util.ets.
Specification limitations

import xxx from '/sourcePath/sourceFileName': By using packageName, sourceRoot can be omitted to achieve differentiated construction under different targets.
Support hap, hsp, har (please note: the har module that enables file/folder name confusion needs to use -keep-file-name to specify sourceRoot, sourcePath, and the file/folder names corresponding to sourceFileName are not confused).
Cross-module references are not supported.
Dynamic import is not supported.

Description of the priority of module target selection at compile time

During the compilation of a module, the sourceRoots used by the module is determined by the target at the time of compilation of the current module. The priority of selecting target during the compilation of the current module is as follows: explicitly specify the > direct reference target > default on the command line.

For example:

hap -> hsp -> har (-> indicates dependency)

Among them, HAP and HSP have three targets: Default, Custom, and Static, while HAR has two targets: Default and Static.

Run the compilation command: hvigorw -p module=hap@custom assembleHap, hap specifies the target as custom for compilation, then the targets of the three modules are as follows:
hap: custom, explicitly specified by the command line;

hsp: custom, if the command line is not explicitly specified, the search is based on the direct referrer, the direct referrer of hsp is hap, the target of hap is custom, and the target of hsp exists, then the target of hsp is custom;

har: default, if the command line does not explicitly specify it, then the search is based on the direct referrer, the direct referrer of har is hsp, the target of hsp is custom, and the target of har does not exist, then the target of har is default;

Run the compilation command: hvigorw -p module=hap@custom, hsp@static assembleHap assembleHsp, hap specifies target as custom, hsp specifies target as static for compilation, then the targets of the three modules are as follows:
hap: custom, explicitly specified by the command line;

hsp: static, explicitly specified by the command line;

har: static, if the command line does not explicitly specify it, the search is based on the direct referrer, the direct referrer of har is hsp, the target of hsp is static, and the target of har is static.

On top of the current dependency, add the dependency: hap -> har. Run the compilation command: hvigorw -p module=hap@custom, hsp@static assembleHap assembleHsp. Since the HAR does not display the specified target, and there are two direct references to different targets (HAP and HSP, corresponding targets are custom and static, respectively), you can only choose one of the targets of HAR during the compilation process. Based on this scenario, it is recommended that developers display the target of the specified module for compilation: hvigorw -p module=hap@custom, hsp@static, har@static assembleHap assembleHsp assembleHar.
example

Add sourceRoots to build-profile.json5 of the entry module:

{
  "apiType": "stageMode",
  "buildOption": {},
  "targets": [ 
    { 
      "name": "default", 
      "source": { 
        "sourceRoots": ["./src/default"] // 配置target为default的差异化代码空间
      } 
    }, 
    { 
      "name": "custom", 
      "source": { 
        "sourceRoots": ["./src/custom"] // 配置target为custom的差异化代码空间
      } 
    } 
  ]
}

Add default/Test.ets and custom/Test.ets to the src directory, and add the following module directory structure:

Write the code in default/Test.ets:

export const getName = () => "default"

Write the code in custom/Test.ets:

export const getName = () => "custom"

Modify the code of src/main/ets/pages/Index.ets:

import { getName } from 'entry/Test'; // 其中entry为模块级的oh-package.json5中的name字段的值
@Entry
@Component
struct Index { 
  @State message: string = getName(); 
  build() { 
    RelativeContainer() { 
      Text(this.message) 
    } 
    .height('100%') 
    .width('100%') 
  }
}

Configure targets in project-level build-profile.json5:

{
  "app": {
    "signingConfigs": [],
    "products": [
      {
        "name": "default",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.2(14)",
        "runtimeOS": "HarmonyOS",
      },
      {
        "name": "custom",
        "signingConfig": "default",
        "compatibleSdkVersion": "5.0.2(14)",
        "runtimeOS": "HarmonyOS",
      }
    ],
    "buildModeSet": [
      {
        "name": "debug",
      },
      {
        "name": "release"
      }
    ]
  },
  "modules": [
    {
      "name": "entry",
      "srcPath": "./entry",
      "targets": [
        {
          "name": "default",
          "applyToProducts": [
            "default"
          ]
        },
        {
          "name": "custom",
          "applyToProducts": [
            "default"
          ]
        }
      ]
    }
  ]
}

After Sync is complete, select the target of the entry as default, click Run, and the interface will display default. Set the target of entry to custom and click Run to display custom.

1.7 -> Define the resources of the product

There may be differences in the resource files used by each target, and developers can store the resources used by each target in different resource directories during the development process. Among them, the ArkTS project supports customization of the resource file directory in the main directory. JS projects support customization of the resource file directory in the main directory and the resource file directory (res) in the ability directory. The following is an example of customizing the resource file directory of an ArkTS project:

{ 
  "apiType": 'stageMode', 
  "buildOption": { 
  }, 
  "targets": [ 
    { 
      "name": "default", 
      "source": { 
        "pages": [ 
          "pages/Index" 
        ] 
      }, 
      "resource": {  //定义默认版target使用的资源文件目录 
        "directories": [ 
          "./src/main/resources_default" 
        ] 
      } 
    }, 
    { 
      "name": "free", 
      "config": { 
        "deviceType": [ 
          "phone" 
        ] 
      }, 
      "source": {   
        "pages": [ 
          "pages/Index", 
          "pages/Page1" 
        ] 
      }, 
      "resource": {  //定义免费版target使用的资源文件目录 
        "directories": [ 
          "./src/main/resources_default", 
          "./src/main/resources_free" 
        ] 
      } 
    }, 
    { 
      "name": "pay", 
      "config": { 
        "deviceType": [ 
          "phone" 
        ] 
      }, 
      "source": {   
        "pages": [ 
          "pages/Index", 
          "pages/Page2" 
        ] 
      }, 
      "resource": {  //定义付费版target使用的资源文件目录，该功能在API 9及以上版本的工程中生效 
        "directories": [ 
          "./src/main/resources_default", 
          "./src/main/resources_pay" 
        ] 
      } 
    } 
  ] 
}

Note that if there are resources with the same name in multiple resource file directories referenced by target, the resource file directories will be selected in the order of the configured resource file directories during the build and packaging process. For example, if there are resource files with the same name in the resource_default and resource_pay of the resources referenced by the target of the preceding paid edition, the resources in the resource_default are packaged into HAP.

1.8 -> Define the icon, label, and launchType of the product

For each target's ability, different icons, labels, and launchTypes can be customized. If not defined, the target uses the icon and label configured in module.json5, and the launchType is singleton by default. An example is shown below:

{ 
   "apiType": 'stageMode', 
   "buildOption": { 
   }, 
   "targets": [ 
     { 
       "name": "default", 
       "source": {
        "abilities": [
          {
            "name": "EntryAbility",
            "icon":"$media:layered_image",
            "label":"$string:EntryAbility_label",
            "launchType": "singleton"
          }
        ]
      }
     }, 
     { 
       "name": "free", 
       "source": {
        "abilities": [
          {
            "name": "EntryAbility",
            "icon":"$media:layered_image",
            "label":"$string:EntryAbility_label",
            "launchType": "multiton"
          }
        ]
      }
     }
   ] 
 }

1.9 -> Define the C++ engineering dependencies on the . SO file

{
  "apiType": 'stageMode',
  "buildOption": {
    "externalNativeOptions": {
      "path": "./src/main/cpp/CMakeLists.txt",
      "arguments": [],
      "abiFilters": [
        "arm64-v8a",
        "x86_64"
      ],
      "cppFlags": "",
    }
  },
  "targets": [  //定义不同的target 
    {
      "name": "default",
      "config": {
        "buildOption": {
          "nativeLib": {
            "filter": {
              //按照.so文件的优先级顺序，打包最高优先级的function1.so文件 
              "pickFirsts": [
                "**/function1.so"
              ],
              //排除不打包的function3.so文件 
              "excludes": [
                "**/function3.so"
              ],
              //允许当.so中资源重名冲突时，使用高优先级的.so文件覆盖低优先级的.so文件 
              "enableOverride": true
            }
          }
        }
      }
    },
    {
      "name": "vip",
      "config": {
        "buildOption": {
          "nativeLib": {
            "filter": {
              //按照.so文件的优先级顺序，打包最高优先级的function1.so文件 
              "pickFirsts": [
                "**/function1.so"
              ],
              //排除不打包的function2.so文件 
              "excludes": [
                "**/function2.so"
              ],
              //允许当.so中资源重名冲突时，使用高优先级的.so文件覆盖低优先级的.so文件 
              "enableOverride": true
            }
          }
        }
      }
    }
  ]
}

2-> Construct a defined target product

Each target corresponds to a HAP, and each product corresponds to an APP package.

Click in the top right corner

icon to specify the product and target to be packaged, and then click Apply to save. For example, if you select ProductA, the free" target corresponding to the entry module is selected.

Product: Select the app package to be built.
Build Mode: Select the build mode.
Product Info: the BundleName and SigningConfig of the app package.
Target Select: Select the target of each module, which needs to be included in the defined Product to be selected, if it is not included, "No Target to apply" is displayed.

Then perform the task of compiling and building the APP/HAP:

Click Build > Build Hap(s)/APP(s) > Build APP(s) in the menu bar to build the app corresponding to the specified product. For example, following the above settings, DevEco Studio will build an APP package that generates ProductA. Neither default nor ProductB apps will be generated.
Click Build > Build Hap(s)/APP(s) > Build Hap(s) in the menu bar to build the HAPs that are generated by all targets under the specified product. For example, according to the above configuration, DevEco Studio will build the default and free HAPs that generate the entry module.
If you want to package a specified target under a module to generate HAP, you can click the module name in the project directory, and then click Build > Make Module 'Module Name', and DevEco Studio will build the package corresponding to the specified target under the build module. For example, according to the preceding configuration, DevEco Studio will build the free HAP under the entry module, but will not generate the default HAP.

3 -> Debug and run the specified Target
When using DevEco Studio to debug or run an application/meta service, each module can only select one of the targets to run, which can be run by clicking in the upper right corner

icon to specify the corresponding Module Target under the Product to be debugged or run, and then click Apply to save.

illustrate

When you select a target that needs to be debugged or run, you need to select the Product to which the target belongs, otherwise you will not find a target that can be debugged and run.

【Journey of HarmonyOS Next】DevEco Studio User Guide (34) -> Configuration and Build (1)

ZHZL-m — Sun, 29 Jun 2025 01:38:57 +0000

1-> Multi-module configuration

1.1 -> Static configuration module

The modules field in the project-level build-profile.json5 configuration file is used to record the module information under the project, including the module name, the source code path of the module, and the target information of the module.

For example, there are two module directories in the following directory, you can add module information to the build-profile.json5 configuration file under the project to bind the module to the project:

Other Profiles:

oh-package.json5: the third-party package dependency configuration file of the application
local.properties: Applies the local environment configuration file
obfuscation-rules.txt: The obfuscation rule profile of the app module
consumer-rules.txt: The obfuscation rule file exported by the library module by default will be packaged into the HAR package. Only HAR modules are supported
Example module configuration in the build-profile.json5 file in the project:

{
  "modules": [
    {
      "name": "module1", // 模块的名称。该名称需与module.json5文件中的module.name保持一致。在FA模型中，对应的文件为config.json。
      "srcPath": "./module1" // 模块的源码路径，为模块根目录相对工程根目录的相对路径
    },
    {
      "name": "module2",
      "srcPath": "./module2"
    }
  ]
}

1.2 -> Dynamically configure the module

Hvigor allows you to dynamically add or exclude a module from hvigorconfig.ts scripts.

2-> Module compilation

Hvigor supports modular compilation and packaging. You can build in modules in two ways:

In DevEco Studio, select the module directory to be built, and click "Make module 'module1'" in the Build menu bar, where "module1" is displayed according to the name of the specific project module.
In the Terminal of DevEco Studio, specify the module for compilation. For example, if the module type is entry and the target product is default, you can run the following command to build a HAP module:
hvigorw --mode module -p product=default -p module=module1@default assembleHap

3 -> Add dependencies

Applications/metaservices support the installation, sharing, and distribution of code and management of project dependencies through the package management tool ohpm. This article explains how to add dependencies in your project.

You can specify dependencies in the dependencies/devDependencies fields in the oh-package.json5 file of your project or module, and the above two dependency fields can be referenced in three ways: remote third-party packages, local folders, and local HAR/HSP. The dynamicDependencies in the oh-package.json5 file are limited to the use case of dynamic dependencies HSP. The following configuration takes dependencies as an example.

3.1 -> Remote tripartite package

Set the third-party package dependency in the oh-package.json5 file of the module to which the third-party package needs to be imported, as shown in the following configuration:

"dependencies": {
  "@ohos/lottie": "^2.0.0"
}

3.2 -> Local folder

Set the local folder in the oh-package.json5 file of the module, as shown in the following configuration:

"dependencies": {
  "folder": "file:../folder"
}

3.3 -> Local HAR/HSP packets

To quote HAR:

"dependencies": {
  "package": "file:../package.har"
}

Referencing HSP (only in release mode, building HSP generates a tgz package):

"dependencies": {
  "package": "file:../package.tgz"
}

After the dependency is configured, you need to run the ohpm install command to install the dependency package, which will be stored in the oh_modules directory of the corresponding module.

【Journey of HarmonyOS Next】DevEco Studio User Guide (33)

ZHZL-m — Sun, 29 Jun 2025 01:36:13 +0000

1 -> Task flow chart

1.1 -> HAP Basic Task Flow Chart

1.2 -> Flowchart of HSP basic tasks

1.3 -> Flowchart of HAR basic tasks

2 -> Use the command to view the task

In DevEco Studio, you can run the following command to obtain task-related information:

hvigorw taskTree

When you get the task tree, the task tree registered in the module will be output in the following figure according to the module in the project:

As shown in the figure, assembleHap depends on signHap, and signHap depends on packageHap. The task execution order is packageHap->signHap->assembleHap.

3 -> Detailed description of the task

According to the different tasks and functions, they are mainly divided into the following types of tasks.

3.1 -> Hook

assembleHap compiles the hook task that builds the hap module.
assembleHsp: Compiles the hook task of building the hsp module.
assembleHar compiles the hook task that builds the har module.
assembleAppCompile the hook task of building the app module.
assembleDevHqf supports incremental deployment of hook tasks.
HotReloadBuild HotReloadArkTS pre-hook task.
PreviewBuild PreviewArkTS pre-hook task.
buildHotReloadResource Hotload a pre-hook task related to a hot loaded resource.
PreviewHookCompileResource Preview: Whether the Restool incremental compilation of the Hook task supports the PreviewHookCompileResource preview.
GenerateBuildProfile Generate the Hook task of the BuildProfile.ets file.
BuildUnitTestHook: A pre-hook task related to the compilation of resource resources for unit tests.
buildPreviewerResource previews the pre-hook tasks related to the resource.
compileNative native resource related pre-hook tasks.
UnitTestBuild UnitTestArkTS precedent hook task.
test uses the CLI to execute the Local Test hook task.
onDeviceTest uses the command line to execute the Instrument Test hook task.

3.2 -> ArkTS

CompileArkTS/BuildArkTS call the loader to compile the ArkTS source code.
In PreviewArkTS preview mode, call the loader to compile the ArkTS source code.
HotReloadArkTS In a hot-loading scenario, call the loader to compile the ArkTS source code.
OhosTestCompileArkTS/OhosTestBuildArkTS In the ohos test scenario, call loader to compile the ArkTS source code.
HarCompileArkTS/HarBuildArkTS In the scenario of building a HAR package, call the loader to compile the ArkTS source code.
UnitTestArkTS In the unit test scenario, call the loader to compile the ArkTS source code.

3.3 -> JS

CompileJS/BuildJS calls loader to compile js source code.
In the OhosTestCompileJS/OhosTestCompileJS ohos test scenario, call loader to compile the js source code.

3.4 -> Resources

ProcessResource processes and generates intermediate files that compile resources as files.
In the PreviewProcessResource preview scenario, intermediate files that compile resources in file form are processed and generated.
CompileResource calls restool to compile the resource.
In the preview scenario, call restool to compile the resource.
ProcessLibs collects .so files in hap and har dependencies.

3.5 -> Package

PackageHap calls the packaging tool to play hap packages.
PackageHar calls the packaging tool to har the package.
PackageHsp calls the packaging tool to play the hsp package.
PackageApp calls the packaging tool to play the app package.
PackageHqf calls the packaging tool to increment the package.
PackageSharedHar calls the packaging tool to play the har package of the hsp module.
PackageSharedTgz calls the packaging tool to package the unsigned hap and har packages generated by the hsp module into a tgz package.
PackageSignHar invokes the packaging tool to create a signed har package, which currently takes effect only in daemon mode.

3.6 -> Sign

SignHap invokes the signature tool to sign the hap package.
SignHsp calls the signature tool to sign the hsp package.
SignApp invokes the signing tool to sign the app package.
SignHqf invokes the signing tool to sign the incremental package.
SignModuleRemoteHsp calls the signature tool to sign the hsp package on the module-level ohpm repository.
SignProjectRemoteHsp calls the signature tool to sign the hsp package on the project-level ohpm repository.

3.7 -> Verification

PreBuild module-level precheck tasks.
PreBuildApp project-level pre-check task.
PreCheckSyscap Configure a precheck task related to syscap.

3.8 -> Generate

GenerateLoaderJson generates loader.json file.
GenerateMetadata generates metadata.json files.
SyscapTransform syscap transformation task.
MakePackInfo generates pack.info at the module level.
MakeProjectPackInfo generates a project-level pack.info.
ProcessPackageJson processes the package.json file.
ProcessOHPackageJson processes the oh_package.json5 file.
GeneratePackRes generates the pack.res file.
CreateBuildProfile Generate the BuildProfile.ets file for hap/hsp.
CreateHarBuildProfile Generate the BuildProfile.ets file of the har.
PrepareQuickfix fetches the delta file by checking it and outputs it to the quiekfix.json file.

3.9 -> Config

ProcessProfile handles the module.json5 file.
PrepareSharedHarResource generates package.json and module.json for packaged shared libraries.
UnitTestProcessProfile The UnitTestBuild scenario processes the module.json file of the build intermediate.
MergeProfile merges the module.json5 file.
In PreviewUpdateAssets preview mode, the Stage model updates the module.json and main_pages.json files generated by the pre-task before compiling the preview code.

3.10 -> Native

BuildNativeWithNinja compiles native code into a so file.
BuildNativeWithCmake uses CMake to compile the CPP source code.

3.11 -> Help

tasks View all of Hvigor's tasks and their details.
taskTree View the task tree involved in the current project.

3.12 -> Other

ReplaceUnitTestIndexFile unit test replaces the entry file.
ReplacePreviewerPage accepts the parameters provided by the previewer to replace the parameters in the page file.
OhosTestCopyMockConfigJson The test framework copies the mock-config.json to the test package when it executes a mock.
clean cleans the generated Build directory.
collectCoverage generates a coverage statistical report based on the gauge dot data.

3.13 -> Sync

init initialization project.

3.14 -> Init

This task type is different from init in Sync, which does not have a specific task and is mainly responsible for preparing for the invocation of hvigor.

【Journey of HarmonyOS Next】DevEco Studio User Guide (32) -> Build the system lifecycle

ZHZL-m — Sun, 29 Jun 2025 01:31:04 +0000

1 -> Engineering Structure Definition

Hvigor parses the project into a tree structure, the project is the root node of the tree, each module in the project is the leaf node of the tree, the tree is up to two layers, the module cannot contain other modules, and the project or module is collectively referred to as a node in the definition of Hvigor.

At the beginning of the initial construction phase, a tree structure will be constructed to store the project structure of the project through the configuration in the project-level build-profile.json5 file, and the project-level build-profile.json5 file and the hvigorconfig.ts file can be configured with multiple modules.

2 -> Hvigor script file

In the lifecycle of the build, Hvigor uses two script files to complete the registration of plugins, tasks, and lifecycle hooks:

hvigorconfig.ts: This file only exists in the root directory in the whole project, it is not a necessary file for construction and does not exist by default, you can create it yourself if necessary, this file is parsed and executed earlier, and can be used to manipulate some data at the beginning of the Hvigor life cycle.
hvigorfile.ts: This file is a copy under each node, which is a necessary file for the build, and can be used to register operations such as plugins, tasks, and lifecycle hooks.

3 -> Task and task dependency graphs

Hvigor is an automated construction of a project based on tasks, and a task is the basic unit of work in the Hvigor build process, which defines the specific work that needs to be performed when building a project. Tasks can complete a variety of operations, such as source code compilation tasks, packaging tasks, or signing tasks. The execution logic of each task is provided by the plugin, which can be the default task logic provided by the hvigor-ohos-plugin, or you can customize it.

It should be noted that there are dependencies on tasks, Hvigor will build a task dependency graph before executing any task, and all tasks will form a directed acyclic graph (DAG), as shown in the following example diagram, the dependencies between tasks are represented by arrows:

Both the hvigor-ohos-plugin and the build scripts in the hvigorfile.ts file will affect the task dependency graph through the task dependency mechanism.

4 -> hvigor-ohos-plugin

hvigor-ohos-plugin is the default build plug-in, which provides business logic support for the completion of tasks, such as providing Hap, Har and Hsp packaging services for Hvigor, and the specific execution logic of each task is provided by different plug-ins in this module.

4.1 -> Relationship between Hvigor and hvigor-ohos-plugin

Hvigor provides task management mechanisms such as task registration and configuration management, which is responsible for controlling the task execution process, but does not include the specific business logic of each task, which is provided by hvigor-ohos-plugin.

The relationship between Hvigor and hvigor-ohos-plugin can be illustrated by the following figure: Hvigor accepts the registration of tasks, arranges the order of task execution, and calls the plug-ins in hvigor-ohos-plugin in order to execute the tasks. If you customize your own task logic plugin and register it, hvigor-ohos-plugin will also call your personalized plugin to complete the compilation and build process.

In the process of Hvigor executing the build, hvigor-ohos-plugin will register the task with Hvigor, and Hvigor will call the corresponding plug-in to execute the corresponding task according to the built task execution directed graph, and after completing a series of tasks such as compilation, packaging, and signing, Hvigor will officially complete the build.

5-> Hvigor life cycle

The lifecycle shows how the Hvigor build system can go through a complete build process. Hvigor's compilation and build process has three distinct phases, which are initialized, configured, and executed, and Hvigor runs these stages sequentially.

5.1 -> Initialization

illustrate

The main purpose of this phase is to initialize the compilation parameters of the project and construct a tree data model of the project structure, with each node being a HvigorNode object.

Set the build parameters of Hvigor according to the command parameters and the configuration in the hvigor-config.json5 file, and construct the hvigor object and hvigorConfig object:
hvigor objects are destroyed throughout the hvigor lifecycle, from the very beginning of creation to the end of the build;
The hvigorConfig object is used to represent hvigor's abstraction of the project structure, is a simple configuration object of hvigor that is used to dynamically add or remove nodes, and it also holds a description object for each node (nodeDescriptor object).
Create a rootNodeDescriptor instance from the build-profile.json5 file in the root directory of the project, and initialize the NodeDescriptor object instances of all modules in the project through the modules field.
Execute a hvigorconfig.ts file in the root directory of the project, where you can register hooks for the lifecycle through hvigor's APIs or perform other processes at the start of the build.
Based on the node description object, an instance of the HvigorNode object for each node is constructed.

5.2 -> Configuration

illustrate

At the beginning of this phase, all nodes are loaded, but there are no plugins, tasks, and DAGs in each node, and the main purpose of this phase is to load these contents.

Execute the hvigorfile.ts files in each node, add the plugin for each node (register the task with Hvigor), execute the apply method of the plugin, and add the context of the plugin.
Based on the plugin and task loaded in the previous step, a DAG graph is constructed based on the dependencies of the task execution.

5.3 -> Execution

Execute the selected task.
Dependencies between tasks determine the order in which tasks are executed.
Tasks can be executed in parallel.

5.4 -> Lifecycle and hook points

In the lifecycle of Hvigor, the following multiple hook points are available for you to call certain logic at the corresponding time.

In the image below, all the wireframes marked in green are hook points that can be used.

【Journey of HarmonyOS Next】DevEco Studio User Guide (31)

ZHZL-m — Sun, 29 Jun 2025 01:28:48 +0000

1 -> Synchronize cloud functions and cloud objects

illustrate

For functions deployed prior to DevEco Studio 4.1 Canary 2, JavaScript code is synchronized.

1.1 -> Synchronize a single SCF/CF

After the SCF or Cloud Object is deployed to AGC Cloud, if new changes are made in the cloud, you can synchronize the SCF or Cloud Object from the cloud to the local project. The synchronization mode of SCF and cloud object is the same, as described in the following section, using cloud object as an example.

Right-click on the function directory and select "Sync 'Function Name'". The following uses the cloud object id-generator as an example.

Click "Overwrite" in the confirmation pop-up box, and the "id-generator" function of AGC Cloud will overwrite the updated local cloud object "id-generator".

Wait for the synchronization to complete, and the cloud object id-generator synchronized from the cloud will be generated in the cloudfunctions directory, and the local original cloud object id-generator will be backed up in the same path.

illustrate

If you perform deployment or debugging, DevEco Studio will automatically skip backing up the data. However, for the sake of streamlining the package, it is recommended that you delete the useless backup data in time after comparing the code differences.

1.2 -> Batch synchronization of SCFs and cloud objects

Batch synchronization of SCFs/Objects synchronizes all SCFs/Objects from the current project in AGC Cloud to the local project.

Right-click on the "cloudfunctions" directory and select "Sync Cloud Functions".

A pop-up window prompts that a cloud function/cloud object with the same name exists in the local project.

If you select Skip, the local functions or objects with the same name will be skipped during synchronization.
If you select Overwrite, the SCF/CF object in AGC Cloud will overwrite and update the local SCF/CF object with the same name.

If you select "Skip" and wait for the synchronization to be completed, all SCFs/Cloud objects in the project synchronized from the cloud will be generated in the "cloudfunctions" directory.

As shown in the following figure, the "test-cloud-function" synchronized from the cloud is added to the "cloudfunctions" directory, and the existing cloud functions/cloud objects in the above figure have not been overwritten and updated.

If you select "Overwrite" and wait for the synchronization to complete, all SCUs/cloud objects in the project synchronized from the cloud will be generated in the "cloudfunctions" directory. Local SCF or cloud objects with the same name are also overwritten and updated, and the original SCF/CF objects before the update are backed up in the same path.

As shown in the following figure, the cloud object "test-cloud-function" synchronized from the cloud is added to the "cloudfunctions" directory, and several existing cloud functions/cloud objects in the local area are also overwritten and updated, and the backup file "xxxx-backup time.backup" is generated.

illustrate

2 -> Synchronize the cloud database

illustrate

Currently, only object types can be synchronized.

2.1 -> Synchronize individual object types

After the object type is deployed to the AGC cloud, if a new change occurs, the object type in the cloud can be synchronized to the local computer.

Right-click the object type JSON file (take "objecttype1.json" as an example) and select "Sync 'objecttype1.json'".

Click "Overwrite" in the confirmation pop-up box, and the object type "objecttype1.json" in the AGC cloud will overwrite and update the local object type "objecttype1.json".

Wait for the synchronization to complete, and the object type "objecttype1.json" synchronized from the cloud will be generated in the "objecttype" directory.

If the deployment is performed in the future, DevEco Studio automatically skips the backup data. However, for the sake of streamlining the package, it is recommended that you delete the useless backup data in time after comparing the code differences.

2.2 -> Batch synchronization of object types

You can synchronize all object types under the current project in the AGC cloud to the local computer with one click.

Right-click the objecttype directory and select Sync Object Type.

A pop-up window prompts that an object type with the same name already exists in the local project, as shown in the following figure "Post.json" and "objecttype1.json".

If you select Skip, the local object type with the same name will be skipped during synchronization.
If you select Overwrite, the object type in the AGC cloud will overwrite and update the local object type with the same name.

If you select "Skip" and wait for the synchronization to be completed, all object types in the project will be generated in the "objecttype" directory, and all the existing local object types will be generated in the "objecttype" directory.

As shown in the figure below, the "test_object.json" synchronized from the cloud is added to the "objecttype" directory, and the existing "Post.json" and "objecttype1.json" are not overwritten and updated.

If you select "Overwrite", after the synchronization is completed, all object types synchronized from the cloud will be generated in the "objecttype" directory, and the existing object types will also be overwritten and updated.

If there is a discrepancy between the cloud and local objects with the same name, the original local object types are backed up in the same path.
If the content of the object type with the same name is exactly the same in the cloud and on-premise, no backup is generated.
As shown in the figure below, three object type files are generated in the "objecttype" directory: "test_object.json", "Post.json", and "objecttype1.json", where "test_object.json" is the object type newly synchronized from the cloud; The "objecttype1.json" already exists locally and is consistent with the content in the cloud, and no backup is generated. The Post.json already exists locally but is different from the cloud content, so it is overwritten and updated, and the original backup of the Post.json is Post.json-backuptime.backup.

illustrate

3 -> One-click synchronization of cloud-side code

illustrate

For functions deployed prior to DevEco Studio 4.1 Canary 2, JavaScript code is synchronized.

Right-click on the Cloud Development Project ("CloudProgram") and select "Sync Cloud Program".

A pop-up window prompts that an object type with the same name/SF/CF exists in the local project.

If you select Skip, the local object type with the same name, SCF, or CF will be skipped during synchronization.
If you select Overwrite, the object type/function/cloud object of AGC cloud will overwrite and update the local object type with the same name/SCF/cloud object.

If you select "Skip" and wait for the synchronization to be completed, all object types in the project synchronized from the cloud will be generated in the objecttype directory, and all SCFs/cloud objects in the project synchronized from the cloud will be generated in the "cloudfunctions" directory.

As shown below:

The "test_object.json" synchronized from the cloud has been added to the "objecttype" directory, and the existing "Post.json" and "objecttype1.json" have not been updated locally.
The test-cloud-function object synchronized from the cloud is generated in the cloudfunctions directory, but the existing id-generator, my-cloud-function, and my-cloud-object are not overwritten and updated.

If you select Overwrite, after the synchronization is complete, all object types in the project synchronized from the cloud will be generated in the objecttype directory, and all SCFs/cloud objects in the project synchronized from the cloud will be generated in the cloudfunctions directory, and the existing local functions/cloud objects/object types will also be overwritten and updated.

In the "objecttype" directory, three object type files are generated: "test _object.json", "Post.json", and "objecttype1.json", where "test _object.json" is the object type that is newly synchronized from the cloud. The "Post.json" already exists locally and is consistent with the content in the cloud, and no backup is generated. "objecttype1.json" already exists locally but is different from the content in the cloud, so it is overwritten and updated, and the original backup of "objecttype1.json" is "objecttype1.json-backuptime.backup".
The cloud object "test-cloud-function" synchronized from the cloud is generated in the "cloudfunctions" directory, and the existing "id-generator", "my-cloud-function" and "my-cloud-object" are also overwritten and updated, and the backup file "xxxx-backuptime.backup" is generated.
illustrate

【Journey of HarmonyOS Next】DevEco Studio User Guide (30)

ZHZL-m — Sun, 29 Jun 2025 01:24:52 +0000

1 -> Deploy the cloud-side project

After all SCF and CDB are developed, you can deploy the entire cloud project resources to the AGC cloud.

Right-click on the CloudProgram and select Deploy Cloud Program.

You can view the packaging and deployment progress of the cloud project on the right side of the status bar at the bottom.

Wait patiently until the "Deploy successfully" message appears, indicating that the cloud project has been successfully deployed.

Select Tools > CloudDev in the menu bar.

In the CloudDev panel that opens, click Go to console to open the AGC Serverless sub-console of the current project.

Go to the SCF and TencentDB menus respectively to view the SCF and TencentDB resources that you just deployed.

2 -> Obtain cloud development resource support through the CloudDev panel

DevEco Studio provides the CloudDev cloud development management panel. This panel integrates the AGC Cloud Development Sub-Console, Documentation, and Community Portal, allowing you to directly access the AGC Cloud Development Sub-Console for service and resource management, and easily jump to various guidance documents and community forums to obtain technical support, providing an end-to-end experience of development, commissioning, deployment, management, and technical support.

Select Tools > CloudDev in the menu bar.

In the open cloud development management panel, you can easily access various cloud development resources.

illustrate

If you have not already logged in, click Sign in to log in to your Huawei developer account.

As shown in the figure below, you can access the corresponding menu for service or resource management on demand.

3-> Generic cloud development template

3.1 -> Scope of application

3.2 -> Renderings

The following is the rendering of the main functional modules of the general cloud development template.

4 -> Summary

To deploy a HarmonyOS cloud-side project on DevEco Studio, you need to download and install DevEco Studio from the official website of the Huawei Developer Alliance, select HarmonyOS SDK and Cloud Kit SDK, configure the JDK path, register a Huawei Developer account, and create a project in the HUAWEI CLOUD console to obtain the configuration information.

Next, create a HarmonyOS project, select a Cloud Engine template, add HUAWEI CLOUD service dependencies to the project, and synchronize the Gradle configuration.

When developing cloud-side business logic, create an SCF class in a specified directory, mark methods that can be called remotely with corresponding annotations, integrate specific cloud services such as CloudDB and Object Storage as required, introduce SDK dependencies, and invoke services through the HUAWEI CLOUD client in SCF.

To configure cloud project parameters, you need to add the AppID, Region, and API Key of the cloud service to the config.json, click the Run button to start the local cloud engine debugging environment, use Postman or a browser to verify the SCF results, and use the debugging tool to troubleshoot problems.

During packaging, click Build to generate a deployment package in .hap format, log in to the HUAWEI CLOUD console to upload the deployment package, configure the instance type, complete the deployment, and record the access address.

During joint debugging, you can call SCFs in the CloudClient class in the HarmonyOS client project, monitor the running logs and performance metrics of cloud services in the HUAWEI CLOUD console, and repackage and overwrite the upload if you need to update them.

During the entire process, you need to pay attention to rights management, security hardening, and version compatibility to ensure the smooth deployment and operation of cloud-side projects.

【Journey of HarmonyOS Next】DevEco Studio User Guide (29) -> Developing a Cloud Database

ZHZL-m — Sun, 29 Jun 2025 01:21:44 +0000

1 -> Development process

ApsaraDB is a device-cloud collaborative database product that provides collaborative management of device-cloud data, a unified data model, and a variety of data management APIs. A cloud database uses an object-based data storage structure. Data is stored in different storage areas in the form of objects, and each object is a complete data record. ObjectType is used to define the collection of stored objects, and different object types correspond to different data structures. A zone is a separate data storage area, each with the exact same object type definition.

You can use DevEco Studio to develop a cloud database under the device-cloud integration cloud-side project, and the overall process is as follows:

Create Object Type: Create an object type that stores data entries.
Add data entries: Add data items to the object type you just created, and configure the storage area where the data is located.
Deploy the cloud database: After the data is successfully added, you can directly deploy the data to the AGC cloud. You can also wait for all object types and data items to be developed before deploying them to the AGC cloud in batches.

2 -> Create an object type

ObjectType is used to define the collection of stored objects, and different object types correspond to different data structures. Each time an object type is created, ApsaraDB instantiates an object type corresponding to its structure in each bucket to store the corresponding data.

To create an object type, perform the following steps:

Right-click the clouddb/objecttype directory and select New > Cloud DB Object Type.

Enter the object type name (objecttype1 is used as an example) and click OK.

illustrate

The object type name must meet the following specifications:

It can contain only letters (A-Z or a-z), numbers (0-9), and underscores (), and at least the letter type.
Must start with a letter, end with a letter or number, not with "sqlite", not with an underscore ().
The following system reserved names are not allowed: naturalbase_metadata, ObjectTypeInfoHelper, t_data_upgrade_info, t_index_schema, t_nstore_config, t_schema_negotiate_info, t_metadata_schema, t_nstore permission、t_system_config。

In the clouddb/objecttype directory, generate and open the JSON file objecttype1.json.

For example, we can configure the following fields for the "objecttype1" object type.

Configure the index, the fields contained in the index, and the sorting method of the fields contained in the index for the object type in Indexes.

For example, we can configure the following two indexes for the "objecttype1" object type.

In permissions, set whether each role has the Read, Upsert (including adding and modifying), and Delete permissions of the object type.

illustrate

Each role can only perform operations with the corresponding permissions, and the cloud side of operations that exceed the scope of the permissions will return a "permission denied" error. Since the initialization code of the device-cloud integration project does not have an AccessToken configured, the Upsert and Delete permissions are added to the World role in CloudProgram/clouddb/objecttype/Post.json.

For example, we can configure the permissions for the object type "objecttype1" for each role in the following table.

3 -> Add data entries

After you create an object type, you can add a DataEntry to the object type and configure the storage area where the data is located.

Supports manual creation and automatic generation of data entry files.

3.1 -> Manually create a data entry file

Right-click the clouddb/dataentry directory and select New > Cloud DB Data Entry.

Select the object type to which you want to add data entries in the Associated Cloud DB Object Type column, define the file name of the data entry in the Enter Cloud DB Data Entry Name column, and click OK.

For example, if you select objecttype1, the default name of the data entry file is d_objecttype1.

As shown in the following figure, the new data entry JSON file "d_objecttype1" is generated and opened in the clouddb/dataentry directory, which presets the name of the object type (objecttype1) and the field name of the object type (id, bookName, author, price, publishTime, and shadowFlag) in the clouddb/dataentry directory.

Configure the values (i.e., data) of the store and fields.

cloudDBZoneName: indicates the name of the storage area. In the preceding example, default indicates that data entries are added to the default bucket. You can modify it, as shown in the following figure: cloudDBZoneName1. In addition, this field needs to be referenced when accessing cloud database coding using APIs.
objects: Sets the values of all fields in the current object type, that is, writes data. An object is a piece of data, and you can create an object to assign a new value to the field, or modify the value of a field under an object (the value of the primary key or encrypted field cannot be modified). As shown in the figure below, two pieces of data are written.

3.2 -> Automatically generate data entry files

Right-click the object type JSON file and choose Generate Data Entry.

For example, objecttype1 contains six fields: id, bookName, author, price, publishTime, and shadowFlag.

In the New Cloud DB Data Entry dialog box, define the name of the data entry file to be generated. The default value of d_objecttype1 is used as an example.

As shown in the following figure, the clouddb/dataentry directory automatically generates a data entry file "d_objecttype1" for the object type "objecttype1", which has preset the object type name ("objecttype1") and the field name of the object type ("id", "bookName", "author", "price", "publishTime", shadowFlag”)。

Configure the values (i.e., data) of the store and fields.

4 -> Deploy a cloud database

After a data entry is created, you can deploy it directly. You can also wait for all object types and data items to be developed before deploying them to the AGC cloud in batches.

illustrate

The number of storage areas deployed to AGC Cloud must not exceed 4, otherwise the deployment will fail and the message "clouddb deploy failed. Reason is the number of CloudDBZone exceeds the limit.” Mistake. If there are currently 4 storage areas in the AGC Cloud, please deploy the data to the existing storage area, or delete the existing storage area and deploy a new storage area. It should be noted that if you delete a storage area, the data in the storage area will also be deleted and cannot be recovered.
Do not modify fields such as fieldType in the object type locally after they are deployed to the AGC cloud. For example, if fieldType is set to String, and the objectType is successfully deployed, and the fieldType is changed to Integer locally, the deployment will fail again, and the message "clouddb deploy failed. Reason is existing fields cannot be modified.” Mistake. If you want to change fields such as fieldType, delete the object type deployed in the cloud. It should be noted that if you delete an object type in the cloud, the data added to the object type will also be deleted and cannot be recovered.
To deploy a cloud database, perform the following steps:

Right-click the clouddb directory and select Deploy Cloud DB.

You can view the progress of cloud database packaging and deployment on the right side of the status bar at the bottom.

Wait patiently until the "Deploy successfully" message appears, indicating that the cloud database has been successfully deployed.

illustrate

After the ApsaraDB is deployed, DevEco Studio automatically downloads the schema file of the ApsaraDB for the AppScope/resources/rawfile/schema.json path, which is a configuration file that must be introduced into the ApsaraDB for the device.

Select Tools > CloudDev in the menu bar.

In the CloudDev panel that opens, click Go to console under Serverless > Cloud DB to enter the cloud database service page of the current project.

Click the Object Type, Storage Area, and Data tabs respectively to view that the locally developed cloud database resources have been successfully deployed to the AGC cloud.

After the deployment is successful, you can access the cloud database from the device side.

You can also edit the deployed cloud database resources in the AGC console.

Demo and cloudDBZoneName1 are stored in the storage area to which object type Post and objecttype1 belong.

Data entries in "d_Post.json", data entries in "d_objecttype1.json":

illustrate

A JSON file of an object type or data entry is actually an object type or data entry contained in a JSON file. As a result, the AGC console will see object types or pieces of data, not JSON files.

【Journey of HarmonyOS Next】DevEco Studio User Guide (29)

ZHZL-m — Sun, 29 Jun 2025 01:16:14 +0000

1 -> Development process

You can use DevEco Studio to develop a cloud database under the device-cloud integration cloud-side project, and the overall process is as follows:

2 -> Create an object type

To create an object type, perform the following steps:

Right-click the clouddb/objecttype directory and select New > Cloud DB Object Type.

Enter the object type name (objecttype1 is used as an example) and click OK.

illustrate

The object type name must meet the following specifications:

In the clouddb/objecttype directory, generate and open the JSON file objecttype1.json.

For example, we can configure the following fields for the "objecttype1" object type.

Configure the index, the fields contained in the index, and the sorting method of the fields contained in the index for the object type in Indexes.

For example, we can configure the following two indexes for the "objecttype1" object type.

In permissions, set whether each role has the Read, Upsert (including adding and modifying), and Delete permissions of the object type.

illustrate

For example, we can configure the permissions for the object type "objecttype1" for each role in the following table.

3 -> Add data entries

After you create an object type, you can add a DataEntry to the object type and configure the storage area where the data is located.

Supports manual creation and automatic generation of data entry files.

3.1 -> Manually create a data entry file

Right-click the clouddb/dataentry directory and select New > Cloud DB Data Entry.

Select the object type to which you want to add data entries in the Associated Cloud DB Object Type column, define the file name of the data entry in the Enter Cloud DB Data Entry Name column, and click OK.

For example, if you select objecttype1, the default name of the data entry file is d_objecttype1.

Configure the values (i.e., data) of the store and fields.

3.2 -> Automatically generate data entry files

Right-click the object type JSON file and choose Generate Data Entry.

For example, objecttype1 contains six fields: id, bookName, author, price, publishTime, and shadowFlag.

In the New Cloud DB Data Entry dialog box, define the name of the data entry file to be generated. The default value of d_objecttype1 is used as an example.

Configure the values (i.e., data) of the store and fields.

4 -> Deploy a cloud database

After a data entry is created, you can deploy it directly. You can also wait for all object types and data items to be developed before deploying them to the AGC cloud in batches.

illustrate

Right-click the clouddb directory and select Deploy Cloud DB.

You can view the progress of cloud database packaging and deployment on the right side of the status bar at the bottom.

Wait patiently until the "Deploy successfully" message appears, indicating that the cloud database has been successfully deployed.

illustrate

Select Tools > CloudDev in the menu bar.

In the CloudDev panel that opens, click Go to console under Serverless > Cloud DB to enter the cloud database service page of the current project.

Click the Object Type, Storage Area, and Data tabs respectively to view that the locally developed cloud database resources have been successfully deployed to the AGC cloud.

After the deployment is successful, you can access the cloud database from the device side.

You can also edit the deployed cloud database resources in the AGC console.

Demo and cloudDBZoneName1 are stored in the storage area to which object type Post and objecttype1 belong.

Data entries in "d_Post.json", data entries in "d_objecttype1.json":

illustrate

A JSON file of an object type or data entry is actually an object type or data entry contained in a JSON file. As a result, the AGC console will see object types or pieces of data, not JSON files.

【Journey of HarmonyOS Next】DevEco Studio User Guide (28) -> Developing Cloud Objects

ZHZL-m — Sat, 28 Jun 2025 18:26:59 +0000

1 -> Development process

In addition to traditional cloud functions, you can also develop cloud objects under the cloud-side project of device-cloud integration. A cloud object is a special kind of cloud function, which is essentially an encapsulation of cloud function, and the client can directly use the method of this object by importing a cloud object, providing a development experience of directly calling cloud code on the device side. Compared with ordinary SCF, the code of cloud objects is more concise and the logic is clearer, and it is recommended to use cloud objects instead of traditional SCF in most scenarios. The development process is roughly as follows:

Create a cloud object: You can create a cloud object directly in DevEco Studio.
Develop cloud objects: After the cloud objects are created, you can start writing cloud object business code.
Debugging Cloud Objects: You can debug cloud objects to test whether the cloud object code is running correctly.
Deploy cloud objects: After the cloud object code development and debugging are completed, you can deploy the cloud object to the AGC cloud, which supports single deployment and batch deployment.
illustrate

Generally, it is recommended to debug cloud objects before deploying them to the cloud, but in some business scenarios, you need to deploy cloud objects before debugging. Perform the following operations based on your business needs.

2 -> Create a cloud object

First, you need to create a cloud object in the cloud-side project.

Right-click on the cloudfunctions directory and select New > Cloud Function.
Select Cloud Object in the "Select the Cloud Function Type" column, enter the name of the cloud object (e.g. "my-cloud-object"), and click "OK".

Like the function name, the name of an object must be between 2 and 63 characters in length and can only support lowercase letters, digits, and hyphens (-), with the first character being lowercase letters and ending with hyphens (-).

The cloudfunctions directory generates a new cloud object directory, which contains the following files:

function-config.json configuration file contains information such as handlers and triggers.
handler: the portal module of the cloud object and the class exported from the cloud object, via the "." Connect.
functionType: indicates the function type, 0 indicates the cloud function, and 1 indicates the cloud object.
triggers: Defines the type of triggers used by cloud objects, and currently only HTTP triggers are supported for cloud objects.
illustrate

It is not recommended to manually modify the configuration file "function-config.json" of the cloud object, otherwise it will cause the cloud object to fail to deploy or other errors.

Cloud object entry file xxx.ts (for example, myCloudObject.ts): Write cloud object code in this file.

Cloud Object Dependency Profile "package.json": Add dependencies to this file.

3 -> Develop cloud objects

Once the cloud object is created, you can write the methods you need to implement directly in the cloud object. For example, you can use cloud objects to implement two methods: add and subtract.

Open the cloud object entry file (in this case, "myCloudObject.ts" is used as an example) and add the add and subtract methods.

export class MyCloudObject {
    add(num1: number, num2: number) {
        return { result: num1 + num2 };
    }
    subtract(num1: number, num2: number) {
        return { result: num1 - num2 };
    }
}

note

Cloud objects are stateless. After a cloud object is deployed to the cloud side, each call may be a different backend node, so it makes no sense to define class member variables on the cloud object. It is wrong to assign a class member property from one Method and then expect to get the class member property from another Method.
There is no need to write constructors for cloud objects. When the cloud side receives a request for a function of a cloud object, it calls the default parameterless constructor of the cloud object.
The input of the cloud object method is deserialized from JSON, which can only be string, number, or Object, and does not support date, Uint8Array, etc. If you need to pass Date or Uint8Array in the process of writing cloud object code, it is recommended to define it as a number or array, and explicitly call the constructor of Date or Uint8Array in the Method to achieve the purpose.
The output of a cloud object's method does not currently support a single number return.
The input and output of methods of cloud objects can use custom objects, and cannot use objects or types defined by third-party dependencies. Note that it is not that cloud objects cannot have third-party dependencies, but that the input and output of cloud objects cannot have third-party dependencies, otherwise in the "Generator Invoke Interface" stage, they will fail because they cannot find dependencies, the fundamental reason is that the device-side code runs in the HarmonyOS support ark runtime, while the cloud-side runs in the Node.js, and the dependency management of the two is different.

(Optional) If there are dependencies on cloud objects, you can add the required dependencies under "dependencies" in the "package.json" file, and then click "Sync Now" in the upper right corner.

illustrate

You can also install dependencies by right-clicking on the package.json file and selecting the "Run 'npm install'" menu.

All installed dependencies are stored in the "node_modules" directory of the current cloud object.

4 -> Debugging cloud objects

Once the cloud object is developed, you can debug it to verify that the cloud object code is working properly.

Currently, DevEco Studio supports local and remote object debugging.

Debugging Cloud Objects by Using Local Invocation: Debugging Locally Developed Cloud Objects in DevEco Studio. It supports single debugging and batch debugging, and supports two modes, Run and Debug, with rich debugging functions, and is often used in the process of cloud object development or problem locating.
Debugging cloud objects by using remote invocation: Deploy cloud objects to AGC Cloud, and then directly invoke cloud objects in DevEco Studio. This method is mainly used to test the operation of cloud objects in the cloud, or to supplement the test of problems that cannot be found in the local invocation mode due to various factors.

4.1 -> Prerequisites

Make sure you're logged in.
If the project has code logic that involves cloud objects calling the cloud database, you need to deploy the entire cloud project to the AGC cloud before debugging, otherwise there will be no relevant data and environment variables in the cloud.

4.2 -> Debugging cloud objects by local calls

You can debug locally developed cloud objects in DevEco Studio, support single debugging and batch debugging, and support two modes: Run and Debug.

The single debugging and batch debugging processes are the same, except that a single debugging starts local debugging for only one cloud object at a time, and then only that cloud object can be called; Batch debugging starts local debugging for all cloud objects in the CloudFunctions directory at one time, and then calls each cloud object one by one.
The difference between Run mode and Debug mode is that Debug mode supports the use of breakpoints to track the running status of cloud objects, while Run mode does not.
The following section uses my-cloud-object in Debug mode as an example to describe how to debug a local cloud object in DevEco Studio.

Right-click the my-cloud-object directory and select Debug 'my-cloud-object'.

illustrate

If you want to debug multiple cloud objects in batches, right-click the cloudfunctions directory and select Debug Cloud Functions. If there are both SCFs and Cloud Objects in the "CloudFunctions" directory, all SCFs and Cloud Objects will be started.

In the CloudFunctions window at the bottom of the notification bar, view the debugging logs. If the message "Cloud Functions loaded successfully" is displayed, the cloud object has been successfully loaded to the HTTP server running locally and the corresponding function URI is generated.
If you need to set a breakpoint for debugging, select a valid line of code to set a breakpoint in the function code, and click the left mouse button after the line number (as shown in line 3 in the figure below) to set the breakpoint (as shown in the red dot in the figure below).

When a breakpoint is set, debugging can break at the breakpoint and highlight the line.

Select "View > Tool Windows > Cloud Functions Requestor" in the menu bar and use the Cloud Functions Requestor to trigger a cloud object call.
In the Cloud Functions Requestor panel that appears, set the trigger event parameters.

Cloud Function: Select the cloud object to be triggered, in this example, the cloud object my-cloud-object is used as an example.
Environment: Select the environment to be called by the cloud object. In this case, Local is selected to indicate a local call.
Method: Required: Enter the method name of the cloud object, such as add.
Event: a list of method parameters, in JSON array format, representing the input parameters of the Method. If the add method receives two number parameters, num1 and num2, then "[1, 2]" is used to construct num1=1 and num2=2.
note

If one of the input arguments of a Method is of type array[], then the Event will contain at least two layers of square brackets '[', and the outer square brackets represent the list of parameters.

(Optional) Click "Save" to save the current triggering event.

Click on the top right corner

You can expand the saved trigger event, and then you can directly click "Load" to load the event. For trigger events that do not need to be saved, you can also click "Delete" to delete.

Click "Trigger", the method of executing the cloud object will be triggered, and the execution result will be displayed in the "Result" box.

illustrate

The Logs panel to the right of the Result box is only used when debugging cloud objects by calling them remotely.

Click on the menu bar

to stop debugging.

After modifying the cloud object code based on the debugging results, click

Restart debugging in Debug mode until there are no issues.

Refer to steps 5~9 to complete the debugging of other methods of cloud objects or other cloud objects.

4.3 -> Debugging cloud objects by remote calling

You can deploy cloud objects to the AGC cloud, and then call the cloud cloud objects in DevEco Studio to test the running of cloud objects in the cloud, or to supplement the problems that cannot be found in local debugging due to various factors.

Deploy the cloud object to be debugged to AGC Cloud by referring to Deploy Cloud Objects.
Select "View > Tool Windows > Cloud Functions Requestor" in the menu bar and use the Cloud Functions Requestor to trigger a cloud object call.
In the Cloud Functions Requestor panel that appears, configure the trigger event parameters.

Cloud Function: Select the cloud object to be triggered, in this example, "my-cloud-object" is still used.
Environment: Select the environment to be called by the cloud object. If you select Remote, you can make a remote call.
Method: Enter a method name for the cloud object, for example, add.
Event: a list of method parameters, in JSON array format, representing the input parameters of the Method in order, for example, the add method receives two number parameters, num1 and num2, then fill in "[1, 2]" to indicate the request to construct num1=1 and num2=2, for example, "[1, 2]".
note

If one of the input arguments of a Method is of type array[], then the Event will contain at least two layers of square brackets, such as '[[1, 2], 3]', and the outer square brackets represent the list of parameters.

Click "Trigger", the cloud object method will be executed, and the execution result will be displayed in the "Result" box.
Click the "Logs" tab to view the printed logs to locate the problem. Modify the cloud object code, redeploy the cloud object, and then perform the remote call again until there is no problem.
Refer to steps 1~5 to complete the debugging of other cloud objects or other cloud objects.

5 -> Deploy cloud objects
After you complete the code development of the cloud object, you can deploy the cloud object to the AGC cloud, which supports single deployment or batch deployment.

A single deployment deploys only the selected cloud objects, while a batch deployment deploys all cloud objects in the entire cloudfunctions directory to the AGC cloud at the same time.

The following section uses my-cloud-object as an example to describe how to deploy a cloud object.

Right-click the my-cloud-object directory and select Deploy 'my-cloud-object'.

illustrate

If you want to deploy multiple cloud objects in batches, right-click the cloudfunctions directory and select Deploy Cloud Functions to deploy all cloud objects in the directory. If both SCF and CF exist in the "cloudfunctions" directory, the SF and CF objects will be deployed to AGC Cloud together.

You can view the packaging and deployment progress of cloud objects on the right side of the status bar at the bottom.

Wait patiently until the "Deploy successfully" message appears, indicating that the current cloud object has been successfully deployed.

Select Tools > CloudDev in the menu bar.
In the CloudDev panel that opens, click Go to console under Serverless > Cloud Functions to enter the SCF page of the current project.
Check that the "my-cloud-object" cloud object has been successfully deployed to AGC Cloud, and the cloud object name is the same as the cloud object directory name of the local project.

After the deployment is successful, you can call the cloud object from the device side.