Application patching

Building an application for OpenHarmony can take a significant amount of time. For faster iterations during development, you can patch the application package instead of rebuilding it. When you patch an application package, Tuanjie only processes files you made changes to since the last patch and sends them to the connected OpenHarmony device.

Platform compatibility

Patching an application

To patch an application, you can use the Tuanjie Editor or, if you implement your own build pipeline, the scripting API.

The first time you patch an application, Tuanjie sets up the patch application environment on the device. This means that the first patch takes longer than future patches.

From the Editor

To patch an application from the Tuanjie Editor:

1. Open the Build Settings window (menu: File > Build Settings).
2. Select the OpenHarmony platform from the Platform list.
3. Enable Development Build.
4. Select Patch or, if you want to run the patch after Tuanjie finishes building it, Patch And Run.

Using the scripting API

If you implement your own build pipeline, you can use the scripting API to patch your application. To do this, pass the BuildOptions.BuildScriptsOnly and BuildOptions.PatchPackage options to the BuildPipeline.BuildPlayer method.

For example：

BuildPlayerOptions buildPlayerOptions = new BuildPlayerOptions();
buildPlayerOptions.scenes = new[] { "Assets/Scene1.unity"};
buildPlayerOptions.target = BuildTarget.OpenHarmony;
// Use Patch & Run for all builds for optimal turn-around times.
// (In prior versions, an initial regular Build & Run was necessary.)
buildPlayerOptions.options = BuildOptions.PatchPackage | BuildOptions.AutoRunPlayer | BuildOptions.Development;
BuildPipeline.BuildPlayer(buildPlayerOptions);

How application patching works

When you patch an application, Tuanjie:

• Creates a minimal HAP that contains all compiled TypeScript sources.
• Takes files that have changed since the last patch and stores them in a directory inside the application’s cache folder at: /data/app/el1/bundle/public/<PackageName>/ShadowFiles/.
• Stores native library files, including scripts compiled using Il2cpp, in the application’s data directory at: /data/app/el1/bundle/public/<PackageName>/ShadowFiles/lib.

When the application starts, it checks for a marker file inside the HAP. If the marker exists, the application redirects its file reads to the ShadowFiles directory.

A Build & Run doesn’t clear any of the patch files. Instead, it replaces the HAP install. This disables the redirect to the ShadowFiles directory. This means that subsequent patch builds can re-use unchanged files.

Clear cache

You can use the OpenHarmony storage settings to clear the application’s cache. Clearing the cache removes the patch files installed by the application patching build process.

The steps to clear an application’s cache are different depending on the OpenHarmony device. To find the steps for your device:

1. Go to Get help from your device manufacturer.
2. Find your device manufacturer and follow the link to its support site.
3. Search the support site for steps on clearing an application’s cache.