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