Skip to main content
Version: Next

DHAO Workflow

danger

If you are using hybridclr version >= v7.7.0, it is recommended to use the MetaVersion Workflow.

The DHAO workflow is the longest-used workflow for DHE hot updates. Before version v7.6.0 and earlier, only the DHAO workflow was supported.

Principle​

When loading DHE assemblies, you need to know which types and functions have changed to decide whether the runtime should call the original AOT code or interpret and execute the latest hot update code. This difference calculation relies on the original DHE and latest DHE assemblies, and the calculation is very complex and time-consuming, making it impossible to calculate in real-time during runtime, so an offline calculation method is used. The calculated difference information is saved in the dhao file.

The DHAO workflow principle is simple, but since dhao files are calculated based on the latest DHE and original DHE, if there are multiple main packages after official release, you need to generate corresponding dhao files for each main package. When there are many main packages, this process is relatively complex and difficult to manage. The [MetaVersion workflow] completely solves this pain point.

Basic Concepts​

Understanding the DHAO workflow requires understanding the following terms:

  • AOT Snapshot
  • inject rule files
  • manifest.json
  • dhao files
  • spec files

AOT Snapshot​

AOT Snapshot is a collection of files needed to calculate dhao files, which includes the following files:

  • dll files
  • inject rule files
  • manifest.json

AOT Snapshot records the main package AOT information, and its core function is to calculate the dhao files needed for hot updates.

The directory structure of AOT Snapshot is as follows:

  AotSnapshotDir
    ├── *.dll
    ├── InjectRules
    └── manifest.json

AOT Snapshot information is completely determined when building the main package, please add it to the project's version control system.

Inject Rule Files​

By default, code is injected at the beginning of almost all DHE functions. Injected code can greatly alleviate the dirty function contamination problem, but the disadvantage is that it increases code size and brings a small amount of additional overhead. Inject Rule files are used to customize code injection rules, allowing some functions not to be injected. For detailed documentation, see Function Injection Strategy.

manifest.json​

Records information such as the DHE assembly list.

dhao Files​

dhao files record the changed types and functions in DHE assemblies. When executing those changed functions, it will automatically switch to interpretation execution.

dhao files use the .dhao.bytes suffix.

spec Files​

spec files are the readable version of dhao files, this file is not used during runtime. It is recommended to add it to the repository, but do not add it to the hot update resource system, as it serves no purpose!

Build and Hot Update Workflow​

  • Build main package
    • Export main package project or directly build main package
    • Create AOT Snapshot
  • Release hot update
    • Compile hot update dll
    • Calculate dhao files based on AOT Snapshot and latest hot update dll
    • Add hot update dll and dhao files to hot update resource system

Create AOT Snapshot​

danger

The dll in AOT Snapshot must exactly match the binary code in the built main package, please be sure to create it after exporting the project or Build! You cannot use the AOT dll generated by HybridCLR/Generate/All!

Call DhaoWorkflow.CreateAotSnapshot(BuildTarget target, string outputSnapshotDir) to create AOT Snapshot files.

Please add AOT Snapshot to version control for future use.

Generate dhao​

Generation process:

  • Use HybridCLR/CompileDll/ActivedBuildTarget to compile the latest hot update dll.

  • Call DhaoWorkflow.GenerateDhaoFiles(string aotSnapshotDir, string hotUpdateSnapshotDir, string dhaoOutputDir) to generate dhao files.

    aotSnapshotDir is the AOT Snapshot directory created when building the main package. hotUpdateSnapshotDir is the latest hot update dll directory. dhaoOutputDir is the dhao file output directory.

Multi-platform and Multi-main Package​

Due to the implementation principle of dhao, each time a hot update is released, each {main package-platform} combination needs to generate separate dhao files.

danger

Merging dhao files will cause performance degradation, use this feature with caution!!!

If you find it troublesome to provide separate dhao files for each main package, you can consider merging the dhao files of all main packages under the same platform into one dhao file. Call DhaoWorkflow.MergeDhaoFile to complete this work.

Merging dhao files of all main packages into one dhao file has a disadvantage: the final output dhao file records type and function changes as the union of type and function changes in all input dhao files. This means that if a function only changed in an old main package but not in the latest main package, the merged dhao file will mark this function as changed, causing this function to be executed in interpretation mode even in the latest main package. This brings performance degradation.