| 1 | # HarmonyOS and OpenHarmony |
| 2 | |
| 3 | This page covers Codewhale on HarmonyOS PC and OpenHarmony cross-build setups. |
| 4 | |
| 5 | ## Support Tier |
| 6 | |
| 7 | | Target | Codewhale tier | CI coverage | Distribution | |
| 8 | | --- | --- | --- | --- | |
| 9 | | HarmonyOS PC with a glibc-compatible userspace | Tier 1 Linux ARM64 runtime | Covered by the Linux ARM64 release build | npm and release binaries | |
| 10 | | `aarch64-unknown-linux-ohos` (OpenHarmony) | Tier 2 cross-build target | `codewhale-tui` is checked with a real OpenHarmony native SDK/sysroot | Build from source; no prebuilt release asset | |
| 11 | |
| 12 | Tier 2 means every relevant source change is compile-checked, but maintainers do |
| 13 | not promise a release binary or full device-level runtime testing. The CI job |
| 14 | uses the published OpenHarmony 6.1 native SDK; it deliberately fails if the SDK, |
| 15 | Clang, or sysroot is unavailable rather than substituting host headers or a stub |
| 16 | that could report false success. |
| 17 | |
| 18 | ## Running On HarmonyOS PC |
| 19 | |
| 20 | HarmonyOS PC can use the normal Linux ARM64 package when its userspace is |
| 21 | glibc-compatible: |
| 22 | |
| 23 | ```bash |
| 24 | npm i -g codewhale |
| 25 | codewhale --version |
| 26 | ``` |
| 27 | |
| 28 | You can also download `codewhale-linux-arm64` and |
| 29 | `codewhale-tui-linux-arm64` from the GitHub Releases page and place both |
| 30 | binaries on `PATH`. |
| 31 | |
| 32 | ## Cross-Compiling To OpenHarmony |
| 33 | |
| 34 | The repository does not check in machine-specific SDK paths. Set |
| 35 | `OHOS_NATIVE_SDK` to the OpenHarmony native SDK directory, the directory that |
| 36 | contains `llvm/bin`, `sysroot`, and `build/cmake/ohos.toolchain.cmake`. |
| 37 | |
| 38 | On Windows PowerShell: |
| 39 | |
| 40 | ```powershell |
| 41 | $env:OHOS_NATIVE_SDK="<path-to-openharmony-native-sdk>" |
| 42 | . .\scripts\ohos-env.ps1 |
| 43 | rustup target add aarch64-unknown-linux-ohos |
| 44 | cargo build --target aarch64-unknown-linux-ohos -p codewhale-cli |
| 45 | ``` |
| 46 | |
| 47 | On Linux or macOS: |
| 48 | |
| 49 | ```bash |
| 50 | export OHOS_NATIVE_SDK=/path/to/openharmony/native |
| 51 | . ./scripts/ohos-env.sh |
| 52 | rustup target add aarch64-unknown-linux-ohos |
| 53 | cargo build --target aarch64-unknown-linux-ohos -p codewhale-cli |
| 54 | ``` |
| 55 | |
| 56 | The setup scripts export Cargo's target-specific `linker`, `AR`, `CC`, `CXX`, |
| 57 | `CFLAGS`, `CXXFLAGS`, `CARGO_ENCODED_RUSTFLAGS`, `CC_SHELL_ESCAPED_FLAGS`, and |
| 58 | CMake toolchain variables for `aarch64-unknown-linux-ohos`. They also point |
| 59 | `bindgen` at the SDK's `libclang` and sysroot so `rquickjs-sys` can generate |
| 60 | the OpenHarmony bindings that it does not ship pre-generated. |
| 61 | |
| 62 | On Windows, `ohos-env.ps1` points Cargo at the repository's |
| 63 | `ohos-clang.cmd` launcher. The launcher delegates to `ohos-clang.ps1`, so the |
| 64 | final Rust link—not only C/C++ compilation and bindgen—always carries |
| 65 | `-target aarch64-linux-ohos`, the SDK sysroot, and `-D__MUSL__` while preserving |
| 66 | Cargo's linker arguments and exit status. The launcher re-quotes every |
| 67 | argument before forwarding, so an SDK path containing spaces (for example the |
| 68 | default `D:\DevEco Studio\...` install) keeps its `--sysroot` intact through |
| 69 | the final link. |
| 70 | |
| 71 | ## Compiler Wrappers |
| 72 | |
| 73 | For ad-hoc compiler calls, use the wrappers in `scripts/ohos/`. They read the same |
| 74 | `OHOS_NATIVE_SDK` variable and do not contain local paths. |
| 75 | |
| 76 | Windows PowerShell: |
| 77 | |
| 78 | ```powershell |
| 79 | .\scripts\ohos\ohos-clang.ps1 --version |
| 80 | .\scripts\ohos\ohos-clangxx.ps1 --version |
| 81 | ``` |
| 82 | |
| 83 | Linux or macOS: |
| 84 | |
| 85 | ```bash |
| 86 | sh ./scripts/ohos/ohos-clang.sh --version |
| 87 | sh ./scripts/ohos/ohos-clangxx.sh --version |
| 88 | ``` |
| 89 | |
| 90 | If you want to run the POSIX wrappers directly as `./scripts/ohos/ohos-clang.sh`, make them |
| 91 | executable first: |
| 92 | |
| 93 | ```bash |
| 94 | chmod +x ./scripts/ohos/ohos-clang.sh ./scripts/ohos/ohos-clangxx.sh |
| 95 | ``` |
| 96 | |
| 97 | ## Linker And Toolchain Paths |
| 98 | |
| 99 | The repository does not check in a Cargo linker path or CMake toolchain path. |
| 100 | Cargo cannot expand environment variables inside `linker` or CMake toolchain |
| 101 | path values, so those values are exported by `scripts/ohos-env.ps1` and |
| 102 | `scripts/ohos-env.sh` instead. |
| 103 | |
| 104 | ## Dependency Guard |
| 105 | |
| 106 | Release prep runs a no-SDK dependency check: |
| 107 | |
| 108 | ```bash |
| 109 | ./scripts/release/check-ohos-deps.sh |
| 110 | ``` |
| 111 | |
| 112 | The guard asserts the Windows final-link wrapper contract, proves that OHOS |
| 113 | activates the `rquickjs-sys` bindgen feature, resolves the `codewhale-tui` |
| 114 | dependency graph for `aarch64-unknown-linux-ohos`, and fails if unsupported |
| 115 | host/UI crates re-enter that graph: `nix` 0.28/0.29, `portable-pty`, `starlark`, |
| 116 | `arboard`, or `keyring`. This no-SDK check does not replace a real SDK/sysroot |
| 117 | build, but it catches the known linker, bindgen, `starlark -> rustyline -> nix`, |
| 118 | and PTY/keyring regressions before release. |
| 119 | |
| 120 | Because `portable-pty` is intentionally absent from the OpenHarmony graph, the |
| 121 | persistent `terminal/*` PTY tools are not registered on that target. The |
| 122 | ordinary `exec_shell` tools remain available through their non-PTY process |
| 123 | implementation. |
| 124 | |
| 125 | Linux-only sandbox implementations (bubblewrap, seccomp, and `prctl` process |
| 126 | hardening) are compiled only for |
| 127 | `all(target_os = "linux", not(target_env = "ohos"))`. OpenHarmony therefore |
| 128 | reports no local OS sandbox instead of probing Linux kernel paths or syscalls it |
| 129 | does not support. External OpenSandbox execution remains separately available |
| 130 | when configured. |
| 131 | |
| 132 | Native desktop clipboard libraries and Wayland helpers are also excluded from |
| 133 | the OpenHarmony graph. Text copy degrades to the terminal-client path (OSC 52, |
| 134 | or tmux `load-buffer -w` when inside tmux); paste is supplied by the terminal as |
| 135 | normal/bracketed input. Image clipboard reads are unavailable on this target. |
| 136 | If the terminal cannot accept OSC 52, copy returns a clear "Clipboard |
| 137 | unavailable" error rather than panicking or claiming success. |
| 138 |