目录

Performing Incremental Debugging

For large apps, the process of rebuilding, pushing packages, and installing after each code modification can be time-consuming. To address this issue, incremental debugging is provided in both DevEco Studio and command line. After code is modified, the debugger can identify code differences and build and push only the incremental package for debugging.

Incremental debugging of C++ code is available for projects developed using API version 11 or later based on the stage model. Incremental debugging of ArkTS code, specifically for modifications to resource files, is available for projects developed using API version 12 or later based on the stage model.

Incremental Debugging in DevEco Studio

[h2]Debugging C++ Code

  1. On the toolbar, select the device to be debugged and click Run or Debug.
  2. After modifying the C++ code, click Apply Changes.

    Then, DevEco Studio initiates an incremental build task, building an incremental package in HQF format. Once the incremental package is built, it will be pushed and installed on the device.

    The Apply Changes feature does not support the creation and deletion of code files, modifications to decorator-related code, or addition of new references using import statements.

[h2]Debugging rawfile/resfile Resource Files

Incremental debugging of resource files in the rawfile folder is supported since DevEco Studio 5.1.0 Release.

  1. On the toolbar, select the device to be debugged and click Run or Debug.
  2. Add or modify resource files in the rawfile or resfile folder under resources of the project directory.

    Currently, incremental debugging of resfile and rawfile resources is limited to the resource files that are explicitly called in the code.

  3. Click Apply Changes to push the incremental package to the device.

    Then, DevEco Studio initiates an incremental build task, building an incremental package in HQF format. Once the incremental package is built, it will be pushed and installed on the device.

Incremental Debugging on Command Lines

[h2]Building an .hqf Package Using hvigorw

  1. Check for the build/config/buildConfig.json file in the target module and its dependent modules. If the file does not exist, run the project in DevEco Studio to generate it.

    If you have performed step 1, skip steps 2 and 3.

  2. Based on the required modules for running and their products and targets, write commands to execute the HAP or HSP build tasks. For example, if the entry module depends on the HSP module library:

    hvigorw --mode module -p module=entry@default,library@default -p product=default assembleHap assembleHsp --info --no-daemon

    For details about how to use the commands, see hvigorw.

  3. Run the hdc commands to install the HAP and HSP modules. For details about how to use the hdc tool, see hdc.

    $ hdc shell mkdir data/local/tmp/99c24fdc44694c05be12491d0a48e139
$ hdc file send library-default-signed.hsp "data/local/tmp/99c24fdc44694c05be12491d0a48e139"
$ hdc file send entry-default-signed.hap "data/local/tmp/99c24fdc44694c05be12491d0a48e139"
$ hdc shell bm install -p "data/local/tmp/99c24fdc44694c05be12491d0a48e139"
$ hdc shell rm -rf data/local/tmp/99c24fdc44694c05be12491d0a48e139
$ hdc shell aa start -a {abilityName} -b {bundleName}
    • abilityName: ability name of the app.
    • bundleName: bundle name of the app.

  4. If any resource file in the rawfile or resfile folder of the HAP/HSP module has been modified, create a changedFileList.json file in the build/default/intermediates/patch/default directory of the module, and list the modified files in the created file. If any resource file for the HAR module has been modified, list the modified files in the module that depends on that HAR module. The following is an example:

    {
  "resources": {
    "resFile": [
      {
        "filePath": "D:\\MyApplication\\entry\\src\\main\\resources\\resfile\\test.txt",
        "resourcePath": "D:\\MyApplication\\entry\\src\\main\\resources"
      }
    ],
    "rawFile": [
      {
        "filePath": "D:\\MyApplication\\entry\\src\\main\\resources\\rawfile\\test.txt",
        "resourcePath": "D:\\MyApplication\\entry\\src\\main\\resources"
      }
    ]
  }
}

  5. After modifying the C++ code, run the .hqf packing command. Once the command execution is completed, you can find the corresponding products entry-default-signed.hqf and library-default-signed.hqf in the build/default/outputs/default output directories of the entry and library modules.

    hvigorw --mode module -p module=entry@default,library@default -p product=default assembleDevHqf --info --no-daemon

  6. Run the hdc command to install the .hqf package.

    $ hdc shell mkdir data/local/tmp/3b7d97cdf4de41c4aecc465ff5069708
$ hdc file send library-default-signed.hqf "data/local/tmp/3b7d97cdf4de41c4aecc465ff5069708"
$ hdc file send entry-default-signed.hqf "data/local/tmp/3b7d97cdf4de41c4aecc465ff5069708"
$ hdc shell bm quickfix -a -f "data/local/tmp/3b7d97cdf4de41c4aecc465ff5069708" -d -o

[h2]Building an .hqf Package Using the SDK Tool

  1. Perform a full build of the app and install the app on the device.

    hdc bm install {hap_path} // Use this command when the HAP is on the computer, where hap_path refers to the path of the HAP.
hdc shell bm install -p {hap_path}  // Use this command when the HAP is on the target device.

  2. Use an independent build process to identify the .so files for building an incremental .hqf package. Based on the ABI compilation environment (which can be checked in the abiFilters field of build-profile.json5), gather them into a specific directory. As shown in the example below, when the compilation environment is arm64-v8a, the files are gathered in the change_test directory.

  3. (Optional) Modify resource files. If any resource file in the rawfile or resfile folder of the HAP/HSP module has been modified, create a changedFileList.json file in the build/default/intermediates/patch/default directory of the module, and list the modified files in the created file. If any resource file of the HAR module has been modified, list the modified files in the module that depends on that HAR module. The following is an example:

    {
  "resources": {
    "resFile": [
      {
        "filePath": "D:\\MyApplication\\entry\\src\\main\\resources\\resfile\\test.txt",
        "resourcePath": "D:\\MyApplication\\entry\\src\\main\\resources"
      }
    ],
    "rawFile": [
      {
        "filePath": "D:\\MyApplication\\entry\\src\\main\\resources\\rawfile\\test.txt",
        "resourcePath": "D:\\MyApplication\\entry\\src\\main\\resources"
      }
    ]
  }
}

  4. Prepare a signature file consistent with the installed app.

    You can obtain the corresponding signature file from the project's build-profile.json5 file.

  5. Prepare a patch.json file. The following is an example:

    {
    "app" : {
        "bundleName" : "com.ohos.quickfix",
        "versionCode" : 1000000, // App version
        "versionName" : "1.0.0",
        "patchVersionCode" : 1000000, // Patch version number. Each time you perform incremental debugging, increment the patch version number by 1 to make sure it is always be greater than the previous one.
        "patchVersionName" : "1000000"  // The value must match the patch version number.
    },
    "module" : {
        "name" : "entry",
        "type" : "patch",
        "deviceTypes" : [
            "phone",
            "tablet"
        ],
        "originalModuleHash" : "" // SHA-256 value of the HAP to be fixed; leave it empty
    }
}

  6. In the directory where the HQF packing tool is installed, which is DevEco Studio installation directory\sdk\default\openharmony\toolchains\lib by default, run the following packing command:

    java -jar app_packing_tool.jar --mode hqf --json-path D:\MyApplication\entry\patch.json --lib-path D:\MyApplication\entry\change_test --resources-path D:\MyApplication\entry\src\main\resources --out-path entry-default-unsigned.hqf --force true

    In the preceding command, modify settings of the following parameters and keep the other parameters as they are:

    • json-path: (mandatory) path to the patch.json file, which contains incremental package information. For details, see Step 5.
    • lib-path: path to the .so file to be packed. For details, see Step 2. Note that the ABI compilation environment cannot be included in the path.
    • resources-path: path to the resources folder that contains resources to be packed, including the rawfile and resfile folders.
    • out-path: output path for the .hqf package.

  7. In the directory where the signing tool is installed, which is DevEco Studio installation directory\sdk\default\openharmony\toolchains\lib by default, run the following signing command:

    java -jar hap-sign-tool.jar sign-app -keyAlias "OpenHarmony Application Release" -signAlg "SHA256withECDSA" -mode "localSign" -appCertFile "OpenHarmonyApplication.cer" -profileFile "ohos_provision_release.p7b" -inFile "entry-default-unsigned.hqf" -keystoreFile "OpenHarmony.p12" -outFile "entry-default-signed.hqf" -keyPwd "123456Abc" -keystorePwd "123456Abc"

    In the preceding command, modify settings of the following parameters and keep the other parameters as they are:

    • keyAlias: key alias.
    • appCertFile: debug certificate file in .cer format.
    • profileFile: debug profile file in .p7b format.
    • inFile: .hqf file to sign.
    • keystoreFile: keystore file in .p12 format.
    • outFile: .hqf file that carries the signature information, generated after the signing.
    • keyPwd: key password.
    • keystorePwd: keystore password.

  8. Install the incremental .hqf package.

    $ hdc shell mkdir data/local/tmp/3b7d97cdf4de41c4aecc465ff5069708
$ hdc file send entry-default-signed.hqf "data/local/tmp/3b7d97cdf4de41c4aecc465ff5069708"
$ hdc shell bm quickfix -a -f "data/local/tmp/3b7d97cdf4de41c4aecc465ff5069708" -d -o