DEV Community

ZHZL-m
ZHZL-m

Posted on

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

#harmonyosnext #devecostudio

Image description

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

  1. 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.

Image description

  1. 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

  1. 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",
  ...
}
Enter fullscreen mode Exit fullscreen mode

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.

  1. 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
           }
         }
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode
  1. Click on the DevEco Studio icon in the top right corner

Image description

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.

Image description

  1. 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.

Image description

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

Image description

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

Image description

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

Image description

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.

  1. Click on the DevEco Studio icon in the top right corner

Image description

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.

Image description

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"
    }
  ]
}
Enter fullscreen mode Exit fullscreen mode
  1. 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
           }
         }
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode
  1. Select the root directory of the HAR module and click Build > Make Module '' to start the build.

Image description

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

Image description

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

Image description

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.

  1. 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
           }
         }
      }
    ]
  }
}
Enter fullscreen mode Exit fullscreen mode
  1. In the build-profile.json5 of the HAR module, set byteCodeHar to true. 
{
  "buildOption": {
    "arkOptions": {
      "byteCodeHar": true
    }
  }
}
Enter fullscreen mode Exit fullscreen mode
  1. Select the root directory of the HAR module and click Build > Make Module '' to start the build.

Image description

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

Image description

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

Image description

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

  1. This capability is supported only in SDKs running Compatible SDK 5.0.0(12) or later.

  2. 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.

  3. In hvigor-config.json5, enable the Build Signature HAR:

{
  "properties": {
    "ohos.sign.har": true
  }
}
Enter fullscreen mode Exit fullscreen mode

  1. Configure the project signature information, please refer to Configuring the Signature Information for the configuration process.

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

Image description

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

Image description

Top comments (0)