Document OHOS build and harness workflows

2026-10-16 20:21:12 +08:00 · 2026-10-16 20:01:55 +08:00
parent 198186350d
commit a2f98d4aea
2 changed files with 144 additions and 4 deletions
@@ -0,0 +1,110 @@
+# Building and debugging MMKV for OHOS
+
+Run the commands below from `OpenHarmony`, with DevEco's Node, Hvigor, OHPM,
+and HDC on `PATH` and `DEVECO_SDK_HOME` pointing to the installed SDK root.
+Use the project's profiles and the installed tools' help when versions change.
+
+## Project configuration
+
+| Setting | Value / source |
+| --- | --- |
+| Product | `default` in `build-profile.json5` |
+| Library module | `MMKV` (HAR) |
+| App build target | `entry@default` |
+| Test build target | `entry@ohosTest` |
+| Runtime test module | `entry_test` in `entry/src/ohosTest/module.json5` |
+| Bundle | `com.tencent.mmkvdemo` in `AppScope/app.json5` |
+| Main ability | `EntryAbility` in `entry/src/main/module.json5` |
+
+The current profile declares compatible SDK `5.0.0(12)` and target SDK
+`6.0.0(20)`. These are different from the attached device's API level.
+`MMKV/build-profile.json5` selects arm64-v8a and x86_64, static OHOS STL, and
+unstripped native symbols. Its CMake build uses C++20 and links Core,
+`libace_napi.z.so`, and `libhilog_ndk.z.so` into `libmmkv.so`.
+
+## Build and signing
+
+Install dependencies when needed:
+
+```sh
+ohpm install
+```
+
+Build the library without signing:
+
+```sh
+hvigorw --mode module -p module=MMKV@default -p product=default \
+  -p buildMode=debug -p enableSignTask=false assembleHar --no-daemon
+```
+
+Build the demo without signing:
+
+```sh
+hvigorw --mode module -p module=entry@default -p product=default \
+  -p buildMode=debug -p enableSignTask=false assembleHap --no-daemon
+```
+
+The root `hvigorfile.ts` imports `sign-config.json` and overrides the signing
+material from that file. The empty fields in `build-profile.json5` do not describe
+the active identity. Keep signing material private and outside version control.
+
+`enableSignTask=false` disables signing tasks but does not bypass this static
+import. If the signing file is missing, configuration fails before compilation.
+For a disposable unsigned build without changing the working tree:
+
+1. Copy the current `Core/` and `OpenHarmony/` source trees into a new scratch
+   directory at the same relative level. Copying only `OpenHarmony` breaks the
+   CMake reference to Core; archiving HEAD would omit uncommitted source changes.
+2. Exclude signing material, `sign-config.json`, `.ohpmrc`, `.idea`, `.hvigor`,
+   `oh_modules`, and generated `build` directories.
+3. Replace only the copy's `OpenHarmony/hvigorfile.ts` with:
+
+   ```ts
+   import { appTasks } from '@ohos/hvigor-ohos-plugin';
+   export default { system: appTasks, plugins: [] };
+   ```
+
+4. Install dependencies in the copy, then run the unsigned build command there.
+   This checks compilation with the signing import removed; it does not verify
+   the original signed-build configuration.
+
+For an authorized signed build, use the existing signing identity/profile and
+omit `-p enableSignTask=false`. Confirm the profile covers the selected physical
+device and matches the installed application's identity.
+
+## Install and launch the demo
+
+Select the intended physical device with `hdc list targets -v` and set
+`DEVICE_SERIAL` to its exact transport serial. After a successful signed build:
+
+```sh
+hdc -t "$DEVICE_SERIAL" install -r \
+  entry/build/default/outputs/default/entry-default-signed.hap
+```
+
+Confirm the artifact path against the build output. Replacement installation
+preserves existing app data; stop on a signing mismatch rather than uninstalling
+the app to work around it.
+
+Launch separately when the demo itself is needed:
+
+```sh
+hdc -t "$DEVICE_SERIAL" shell aa start \
+  -b com.tencent.mmkvdemo -m entry -a EntryAbility
+```
+
+`EntryAbility.onCreate()` calls `testNameSpace()` and writes normal demo stores.
+Installing the main module is sufficient for preparing the test module; do not
+launch the normal demo just to run its isolated tests.
+
+## Tests and native debugging
+
+See the [ArrayBuffer harness guide](MMKV/tests/arraybuffer_bounds/README.md) for
+the portable tests, device build/install commands, runner, selected case count,
+and test storage cleanup. Keep suite-specific details there.
+
+For native crashes, retain `libmmkv.so` and symbols from the matching build and
+collect the relevant application logs/stack. `MMKV/consumer-rules.txt` preserves
+exported bridge/API names. The entry app's release obfuscation and the library's
+consumer rules are separate settings: changing library obfuscation alone may not
+fix a release-only consumer failure.
@@ -3,12 +3,21 @@ the production `encodeBytes` / `encodeArray<T>` callbacks and byte-to-ArrayBuffe
 from `native_bridge.cpp`.
 N-API and MMKV are explicit test doubles; this does not replace an OpenHarmony SDK build or runtime test.

-Build in a disposable directory and run separately:
+See [the OHOS build guide](../../../BUILDING.md) for the project layout, signing setup, and demo installation.
+The portable harness requires Python 3 and a C++20 compiler; `prepare_callbacks.py` extracts the production callbacks.
+
+Run the portable commands from the repository root (the directory containing `Core` and `OpenHarmony`).
+Set `SCRATCH` to an existing disposable directory owned by the current session, then build:

 ```sh
-cmake -S OpenHarmony/MMKV/tests/arraybuffer_bounds -B "$SCRATCH/arraybuffer-bounds"
-cmake --build "$SCRATCH/arraybuffer-bounds"
-ctest --test-dir "$SCRATCH/arraybuffer-bounds" --output-on-failure
+cmake -S OpenHarmony/MMKV/tests/arraybuffer_bounds -B "${SCRATCH:?}/arraybuffer-bounds"
+cmake --build "${SCRATCH:?}/arraybuffer-bounds"
+```
+
+Run the tests separately:
+
+```sh
+ctest --test-dir "${SCRATCH:?}/arraybuffer-bounds" --output-on-failure
 ```

 ASan and UBSan are enabled by default; set `-DMMKV_TEST_SANITIZERS=OFF` only for a compiler without those sanitizers.
@@ -24,11 +33,24 @@ omitted/undefined expiration, expiration-enabled writes, empty buffers, negative
 It creates unique stores under `filesDir/mmkv_arraybuffer_bounds` and removes only those stores after testing.
 Wrong argument types, simulated N-API failures, and null backing pointers remain covered by the portable harness.

+`entry/src/ohosTest/ets/test/List.test.ets` registers this suite alongside the separate Ability suite;
+40 is the count selected by the `ArrayBufferBounds` class filter, not the entire test module.
+The harness initializes MMKV from the ability-delegator application context. Preserve its unique-store isolation
+when adding cases; never clear the demo's general storage to reset the tests.
+
+The direct `libmmkv.so` import uses the native type package declared in `entry/oh-package.json5` at
+`../MMKV/src/main/cpp/types/libmmkv`. Keep this test dependency instead of widening production APIs for malformed calls.
+
 With DevEco's Node/Hvigor/HDC on `PATH`, `DEVECO_SDK_HOME` configured, and an existing debug signing configuration
 valid for the attached physical device, build from `OpenHarmony`:

 ```sh
 ohpm install
+```
+
+Build in a separate step:
+
+```sh
 hvigorw --mode module -p module=entry@ohosTest -p product=default -p buildMode=debug assembleHap --no-daemon
 ```

@@ -37,8 +59,16 @@ serial explicitly, then install the test module without uninstalling or clearing

 ```sh
 hdc -t "$DEVICE_SERIAL" install -r entry/build/default/outputs/ohosTest/entry-ohosTest-signed.hap
+```
+
+Run the selected suite separately:
+
+```sh
 hdc -t "$DEVICE_SERIAL" shell aa test -b com.tencent.mmkvdemo -m entry_test \
  -s unittest OpenHarmonyTestRunner -s class ArrayBufferBounds -s timeout 15000
 ```

 Check the reported test count and failures; a successful HDC exit alone does not establish that the suite passed.
+`OpenHarmonyTestRunner` logs `onRun end` after scheduling ability startup, before Hypium completes; this is not a
+suite-completion marker. Require the selected suite's completion report and failure/error count, and update the
+expected count when its cases change.