Support HarmonyOS

[cavivie]

Tracking HarmonyOS NEXT support. Full scoping analysis in this comment.

Status (2026-04-21): Phase 1 PRs ready for review + a signed .so that survives dlopen on a real DevEco 6.0.1(21) wearable emulator. See the handoff comment below for the validation state and what's needed from @cavivie.

Blockers (answer before starting)

• Confirm whether perry/ui is needed, or logic-only is sufficient for the reporter's use case → UI required, Phase 2 (B1 ArkTS emitter) is in scope; B2 explicitly out.
• Confirm access to a Huawei dev cert + NEXT device or DevEco Studio emulator for validation → Both confirmed (@cavivie has cert + physical NEXT hardware, will validate intermediate builds).

Phase 1 — toolchain + .so/HAP bundle, no UI

• Add ohos / ohos-simulator variants to Platform enum + rust_target_triple — shipped as harmonyos / harmonyos-simulator (target strings only; Platform enum deliberately not touched, see PR #121). Maps to aarch64-unknown-linux-ohos / x86_64-unknown-linux-ohos.
• OpenHarmony SDK detection (env var OHOS_SDK_HOME or similar) — sysroot + llvm/bin/clang path resolution. Supports DevEco 5.x layout (~/Library/Huawei/Sdk/openharmony/<api>/native/) AND DevEco 6.x layout (/Applications/DevEco-Studio.app/Contents/sdk/default/openharmony/native/).
• Linker invocation: clang --target=aarch64-linux-ohos --sysroot=<sdk>/native/sysroot -D__MUSL__ -shared -fPIC -Wl,-Bsymbolic -Wl,--warn-unresolved-symbols -lace_napi.z -lc -lm -lpthread -ldl.
• Emit .so output mode — --target harmonyos auto-selects lib<stem>.so.
• napi_module_register entry wrapper in perry-runtime behind ohos-napi feature flag. Module registration via .init_array; nm_modname derived at runtime via dladdr to match the actual .so filename.
• Boilerplate ArkTS UIAbility shim generator that loads the .so and invokes the TS entry point. Shipped as plain TypeScript (no @Entry @Component struct) so es2abc --extension ts compiles it directly without ets-loader.
• HAP bundler: module.json5, ets/ (compiled modules.abc), libs/arm64-v8a/*.so, resources (resources/base/{media,string,color}/).
• Integrate hvigor assemble + hap-sign (user-supplied cert via env var, not baked into CI) — partial: signing wired via 7 env vars (PERRY_HARMONYOS_P12/_P12_PASSWORD/_CERT/_PROFILE/_KEY_ALIAS/_KEY_PASSWORD/_SIGN_ALG) and shells out to hap-sign-tool.jar directly (skipping hvigor per design Decision 3). Not yet: DevEco encrypts its auto-signing passwords in build-profile.json5, so users with DevEco-auto-generated certs can't use these env vars directly — would need either a decryption helper or a hvigorw integration. Workaround used for v0.5.129 validation: splice Perry's .so + .ets into an existing DevEco project and let hvigor sign.
• End-to-end: compile hello.ts → .hap → install via hdc → run on emulator — partial. libentry.so loads on DevEco 6.0.1(21) wearable emulator and aa start EntryAbility succeeds without throwing. Whether console.log() actually reaches hdc hilog is unverified — perry-runtime writes to stdout (println!()), which OHOS does not route into hilog by default. Likely needs a stdout→hilog shim. Path to HAP-from-perry (not DevEco splice) is blocked on the signing item above.
• Hand off intermediate build to @cavivie for on-device NEXT validation (resolves KAL unknown below) — ready now. See #121 (PR A, scaffolding) + #122 (PR B, functional, stacked on PR A). The harmony-os branch has 7 commits from main representing the full Phase 1 work.

Phase 2 — TS→ArkTS emitter for perry/ui (option B1) — confirmed in scope

• New perry-codegen-arkts crate mirroring perry-codegen-js/perry-codegen-wasm shape
• Map perry/ui HIR widget tree → ArkTS declarative components (Column/Row/Text/Button/...)
• State reactivity: bridge Perry's State<T> → ArkTS @State/@Link
• Hybrid build: UI compiles to .ets, logic compiles to .so, both packaged in the same HAP
• Widget parity audit against existing native UI targets

Phase 3 — deferred

• Custom GL widget set on XComponent (option B2) — explicitly out for v1 per @cavivie; revisit only if B1 proves unexpectedly complex.

Open unknowns

• Verify aarch64-unknown-linux-ohos binaries actually run on HarmonyOS NEXT's microkernel via KAL — confirmed on DevEco 6.0.1(21) wearable emulator (v0.5.129). Physical-device validation still outstanding.
• Confirm libffi / tikv-jemalloc-sys gap doesn't hit perry-stdlib growth before/during this work — untouched; perry-stdlib cross-compiles green today, but if deps shift this could regress.
• Does TS console.log() reach hdc hilog? Unverified on emulator. Physical-device test from @cavivie would confirm whether the emulator behavior (silent drop) matches devices or is emulator-specific.
• DevEco auto-signing password decryption vs hvigorw integration — pick one to unblock the end-to-end perry compile → hdc install loop without requiring the DevEco-project splice.

[WREQI]

支持这个 是不是还得买个鸿蒙电脑和手机

[proggeramlug]

Thanks for the request — HarmonyOS NEXT support is in scope, but it's a larger piece of work than adding an Apple or Android target because NEXT breaks three assumptions Perry has had since day one. Laying out what I found while scoping it, so we can agree on direction before I start:

1. No standalone main() process. Perry emits ELF executables; HarmonyOS NEXT apps are .so libraries loaded by the ArkTS runtime via napi_module_register, launched by an AbilityStage → UIAbility lifecycle. There's no "run the binary" shipping shape — a new output mode is needed (.so + a boilerplate ArkTS UIAbility shim that calls into it).

2. No native windowing. Every existing UI target (AppKit/UIKit/WatchKit/GTK4/Win32/Android) lets native code create windows imperatively. On NEXT, windows belong to ArkTS components; native code can only render into an XComponent's EGL surface. Three sub-options, each with very different cost:

• A: no perry/ui support for v1, server-side TS only.
• B1: emit ArkTS source from perry/ui HIR (Perry becomes a hybrid TS→ArkTS + native cross-compiler for this target).
• B2: a custom GL widget set on XComponent (large scope, diverges from platform look-and-feel).

3. HAP packaging + Huawei signing. Output is a .hap ZIP built by hvigor and signed by hap-sign with a Huawei-issued cert. Local debug certs exist but expire; CI needs real dev enrollment.

The toolchain side is actually the easy part — aarch64-unknown-linux-ohos is Tier 2 with host tools, prebuilt std via rustup, no nightly, musl-based, and DevEco Studio ships a macOS/Windows emulator.

Proposed phased approach:

• Phase 1: --target ohos produces .so + minimal UIAbility shim + HAP bundle, no UI. Proves out the toolchain.
• Phase 2: TS→ArkTS emitter for perry/ui (option B1 above).
• Phase 3: deferred — custom GL widgets, only if there's demand.

Two questions before I start Phase 1:

1. Do you need perry/ui on HarmonyOS, or is logic-only sufficient for your use case? (Phase 1 unblocks the latter on its own.)
2. Do you have access to a Huawei dev cert and a physical NEXT device (or DevEco Studio emulator) to validate against? I can cross-compile and bundle without one, but can't install/run without signing.

[cavivie]

@proggeramlug Thanks for the detailed scoping—really appreciate you taking the time to map out the napi_module_register and windowing constraints before diving in. That context saves a lot of downstream confusion.

To answer your questions directly:

1. Do I need perry/ui on HarmonyOS?
Yes, UI support is required for our use case. Logic-only won't cut it; I'll need visual output on the device. Between the two options you outlined for native windowing:

• B1 (TS→ArkTS emitter) sounds like the more sustainable path forward if perry/ui HIR is reasonably well-structured. Happy to defer to your judgment on feasibility here.

• B2 (custom GL widget set) I'd consider a non-starter for v1 unless B1 proves unexpectedly complex—I want the app to feel native to the platform, not like a foreign GL canvas.

2. Certificates and devices:
Yes, I have access to both a Huawei developer certificate and physical HarmonyOS NEXT test hardware. I can handle signing and on-device validation for any intermediate builds you want to test against real metal.

[jimmy54]

Need support

[proggeramlug]

@cavivie @godcop @jimmy54 working on it here: https://github.com/PerryTS/perry/tree/harmony-os

feel free to contribute and join in

will update later with concrete progress

[proggeramlug]

Phase 1 handoff — seeking on-device validation @cavivie

Spent a session today going from "no harmonyos support at all" to "Perry-emitted .so loads on a live DevEco 6.0.1(21) emulator without throwing." Everything's on harmony-os branch — 7 commits atop main, already open as PR #121 (scaffolding) and PR #122 (Phase 1 functional).

What's confirmed working (on my macOS host + wearable emulator)

1. Cross-compile: cargo build --target aarch64-unknown-linux-ohos -p perry-runtime -p perry-stdlib produces ~35 MB libperry_runtime.a + ~38 MB libperry_stdlib.a without errors, using DevEco 6's bundled clang + musl sysroot. Zero nightly Rust needed (the triple is Tier 2 with host tools).
2. Link: libentry.so comes out at 8.8 MB, ELF aarch64, NEEDED = [libc.so, libace_napi.z.so] (zero macOS cruft, zero glibc-only libs), .init_array correctly references the NAPI register_module function, mi_malloc_aligned and all other mimalloc symbols resolve to locally-defined addresses.
3. HAP assembly: entry.unsigned.hap (9 MB, 17 members) passes all the structural checks — pack.info/module.json5/app.json5 match what developtools_packing_tool's Java parser expects (validated against audit of its source), ets/modules.abc is a valid PANDA-magic bytecode blob produced by invoking es2abc --extension ts directly (ets-loader's Node+rollup pipeline works around the bare-invocation case for Phase 1's decorator-free UIAbility).
4. Install + launch on emulator: bm install succeeds, aa start -a EntryAbility -b com.example.myapplication launches the ability, onCreate calls perryEntry.run() via the .d.ts-declared import, and it does not throw. The default ArkUI "Hello world" page renders. This is the first time Perry-compiled TypeScript has executed inside a HarmonyOS process.

What's unverified (and where I'd love your help)

• Does console.log() reach hdc hilog? perry-runtime's console.log ends up as println!() → stdout, and OHOS does not route stdout into hilog by default. I can fix this (dup2 fd 1+2 to a pipe and spawn a reader thread that calls OH_LOG_Print) but it's cleaner if I know what the actual device behavior is first. On your physical NEXT: run perry compile /path/to/hello.ts --target harmonyos (will produce libentry.so + ets/ in the output dir), splice into a throwaway DevEco project per the workflow in B.6's commit, hit Run, and check if anything Perry-emitted shows up in hilog. Baseline test TS: console.log("hi from perry") — one line.
• Phone/tablet emulator. My Huawei account isn't real-name verified, so I could only download the wearable system image. If you have a phone emulator or physical phone, does the same install+launch flow work when deviceTypes lists phone instead of wearable? HAP today declares all four (phone, tablet, 2in1, wearable).
• Phase 1's signing story vs DevEco's. I implemented hap-sign-tool invocation from Perry via 7 env vars (matches developtools_hapsigner's sign-app CLI exactly), but DevEco's auto-signing flow encrypts its passwords in build-profile.json5 so Perry-standalone signing is currently blocked on either (a) a decryptor or (b) a hvigorw assembleHap fallback. For today's validation I sidestepped by splicing Perry's .so + .ets into an existing DevEco project and letting hvigor do the signing. If you have a preference between (a) and (b) for the eventual clean perry compile --target harmonyos → hdc install loop, that'd help prioritize.
• API level 21 vs 11. I bumped targetAPIVersion to 21 to match DevEco 6.0.1(21); minAPIVersion stays at 11 (NEXT floor). If you're on a different SDK version this may need override — I've left it hardcoded for v1, user-configurable via $PERRY_HARMONYOS_TARGET_API is a follow-up.

How to try it

git clone -b harmony-os https://github.com/PerryTS/perry.git
cd perry
cargo build --release -p perry

# Prerequisite: DevEco Studio installed at the standard path. No manual OHOS_SDK_HOME needed.
echo 'console.log("hi from perry")' > /tmp/hello.ts
./target/release/perry compile /tmp/hello.ts --target harmonyos -o /tmp/libentry.so

# Output:
#   /tmp/libentry.so                     — compiled .so
#   /tmp/ets/entryability/EntryAbility.ets — ArkTS shim
#   /tmp/entry.unsigned.hap              — HAP (not installable without signing)

To actually install & run, sidestep signing for now by splicing into an existing DevEco project:

# Assuming MyApplication at ~/DevEcoStudioProjects/MyApplication
PROJ=~/DevEcoStudioProjects/MyApplication
cp /tmp/libentry.so $PROJ/entry/libs/arm64-v8a/libentry.so

# One-time project setup: create the .d.ts + oh-package.json5 registration
# so ArkTS can resolve `import perryEntry from 'libentry.so'`. Full snippet
# in commit 41d597c's body. Then edit EntryAbility.ets to call perryEntry.run()
# in onCreate. Click Run in DevEco.

What's deferred to future PRs (not blocking handoff)

• Phase 2 (PR C): perry-codegen-arkts crate + TS→ArkTS emitter for perry/ui. Unblocks real UI. Rough estimate 1-2 weeks from whenever we start.
• perry.toml / package.json integration: bundle name, icon path, API versions. Today all hardcoded / env-var-driven.
• --target harmonyos-simulator x86_64 ABI (libs/x86_64/ vs libs/arm64-v8a/). Emulator is aarch64 anyway so not blocking.
• stdout → hilog shim (as above; will either do it if your physical-device test shows stdout is dropped, or not if it shows up somehow).
• Signing decryptor / hvigorw integration (per your preference, as above).

Commit trail

• 0f7a6a0 v0.5.123 — scaffolding
• 87c70ce v0.5.124 — toolchain, SDK detection, .so link path
• 0cd71e2 v0.5.125 — NAPI entry + ArkTS shim
• 4a9701a v0.5.126 — HAP bundler
• 3042563 v0.5.127 — audit fixes against Huawei source (7 install-blocking bugs)
• b01653f v0.5.128 — DevEco 6.x layout + first working .hap on disk
• 41d597c v0.5.129 — mimalloc .o pickup + first emulator dlopen success

Over to you for physical-device validation when you have a window. No rush — Phase 2 can start in parallel once you confirm Phase 1's emulator baseline holds on real hardware. Happy to iterate on anything that surprises you.