@hmos-library-adapter/fast 0.0.17-beta.0 → 0.0.17-beta.2

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/SKILL.md

@@ -0,0 +1,399 @@
+---
+name: pc-knowledge-base
+description: 鸿蒙 PC 编译与平台知识核心（语言无关）。包含交叉编译骨干（NDK/sysroot/ABI/签名/部署/状态语义）+ 鸿蒙 PC 平台机制（HNP/PATH/SELinux exec/HMDFS/uid/mount namespace/沙箱路径/hdc/设备 Python/设备 pip/app 域 exec 与 JIT 限制）+ GUI 图形栈上屏（XComponent/OWB 视窗桥）与 HAP 应用形态 + 库适配经验案例库。当交叉编译 C/C++/Rust/Node N-API/Java JNI 到鸿蒙、把桌面 GUI 应用搬上鸿蒙、打 HAP、需理解平台机制、查适配案例时使用。触发词：交叉编译、NDK、clang、aarch64-unknown-linux-ohos、musl、sysroot、工具链、ohos-cross.ini、CMake toolchain、meson cross-file、ELF 签名、binary-sign-tool、strip、RPATH、RUNPATH、LD_PRELOAD、hdc 部署、无设备离线编译、built-pending-verification、HNP、PATH、SELinux、avc denied、HMDFS、符号链接失败、uid 归属、mount namespace、沙箱路径、设备 Python、设备 pip、设备 Java 运行时、BiSheng、毕昇 JDK、运行时供给、运行时缺失、平台机制、platform、adaptation、XComponent、OHNativeWindow、EGL、GLES、Vulkan、窗口、视窗、GUI、图形栈、上屏、GLFW、Qt6、QPA、QtQuick、GTK、broadway、ArkWeb、HAP、module.json5、Electron、OH-Electron、Swing、AWT、JVM、app 域、JIT、私有 HNP、HNP zip 布局契约、pkg 前缀、目录条目先行、安装器剥离首段路径、9568407、9568269、hnp_zip.c、应用沙箱临时目录、tmpfile、P_tmpdir、/data/local/tmp 不可写、libcheck、check_msg、TEMP 选址、mkstemp、symlink 禁令、aa start 不重跑、force-stop 1010402、冷启动、卸载重装、curl 空信任锚、CURL_CA_FALLBACK、SSL_CERT_FILE、error 60、X509_STORE、CA bundle、certifi、Rust build.rs、CARGO_CFG_TARGET_OS、宿主 cfg 泄漏、windows-gnu、dlltool、raw-dylib、NTFS ADS、libstdc++ 垫片、libc++_shared 随包、杀毒引擎、病毒库、EICAR、CVD 验签、bytecode.cvd、64KB 页对齐、musl 分歧、glibc 差异、errno 文案、strerror 不一致、多字节编码、EILSEQ、stdio 语义、语义分歧、测试预期失败、mknod、mkfifo、命名管道、S_IFIFO、socketpair、故障注入、真实 ELF fixture、测试前置、testenv、常量构造、上游测试、自带测试套件、测试移植、NAPI 壳、边界用例、LLONG 边界、尾随垃圾、往返一致、缓冲截断、关闭后操作、多流轮转、测试覆盖面、冒烟用例、close_range、closefrom、批量关闭 fd、SIGSYS、syscall 436、march、指令档位、armv8、crypto+crc、SVE、LSE、getauxval、AT_HWCAP、指令集探测、SIGILL、非法指令、mcpu、分支保护、构建驱动、无 make、GNU make 缺失、makefile 解析、确定性构建、makefile.gcc、cmpl_clang、Windows 宿主、ld.lld 并行崩溃、make -j1 续编、hvigorw spawn java ENOENT、MSYS2 PATH、pkg-config、pkg-config 模拟器、pkg-config.py、Windows 无 pkg-config、Conan、.pc 文件、meson run_command、test -d、fs.is_dir、glib gtest、g_test_init、glib 静态链接、__assert_fail、enable-ntls、NTLS、TLCP、国密、execv 127、pthread_yield、sched_yield、strftime 时区缩写、有符号溢出 UB、parseLong、CppUnit 1.15、shortDescription。所有带原生的交付形态（native-extension/cpp-lib/cli）都复用本核心，语言只加薄 adapter（见 pc-delivery-forms/references/languages/）。
+---
+
+# pc-knowledge-base：鸿蒙 PC 编译与平台知识核心
+
+## 何时用我
+
+- `pc-delivery-forms` 按交付形态执行交叉编译时（它引用本核心，只补形态必做项与语言薄差异）
+- 需要处理 NDK 工具链、sysroot、ABI 对齐
+- 需要 ELF 签名、hdc 部署、真机测试
+- 无设备时的离线交叉编译兜底
+- 需要理解鸿蒙 PC 平台机制（HNP/PATH、SELinux exec、uid、mount namespace、HMDFS、沙箱路径、hdc、设备 Python 运行时、设备语言运行时探测与供给、设备 pip 部署、app 域 exec/JIT 限制、POSIX/NDK 能力边界）
+- **宿主运行时 / Electron 技术域**问题：产物被 Electron-OH 内置 Node 加载（addon 编译/libshim 垫片/libuv 转发/io_uring shim）、查 Electron→鸿蒙迁移指南——`electron/`
+- 要把**桌面 GUI 应用/图形库**搬上鸿蒙（XComponent 上屏缝、OWB 视窗桥、GLFW/Qt6/GTK/Swing 后端）或**打成 HAP**（私有 HNP、Electron 壳、权限申请）
+- 查已有真实适配案例（ripgrep/parcel-watcher/node-pty/cpprestsdk/opencode/nmap/git/VLC/Qt6/GLFW/VisualVM）
+
+> 本 skill 是**编译骨干 + 平台机制 + 适配经验的综合权威归属**。语言差异在 `pc-delivery-forms/references/languages/` 里。错误图谱在 `pc-error-atlas`。**其他 skill 只引用本核心，不重复写。**
+
+## 知识分类规则（与个人知识库一致）
+
+内置知识按"视角/是否库特有"分两个目录，和个人知识库（`$PC_ADAPT_KNOWLEDGE_ROOT/memory/`）用同一套规则：
+
+### platform/ — 平台公共机制
+
+**"换个库还成立吗？成立 → platform/"**
+
+鸿蒙 PC 环境本身的系统底座机制：进程视角/mount namespace、uid 与文件归属、HNP/PATH、SELinux exec 限制、HMDFS 文件系统行为、hdc 操作、沙箱路径映射、设备 Python 运行时、设备 pip 部署等。和具体跑什么库无关。
+
+### adaptation/ — 库适配经验
+
+**"主要服务于某个库的落地吗？是 → adaptation/"**
+
+具体三方库在鸿蒙 PC 上适配的工程经验：交叉编译踩坑、部署方案、打包分发等。库强相关。
+
+### electron/ — Electron 技术域知识
+
+**"Electron 生态特有的机制/工具/判定知识 → electron/**
+
+Electron 应用与 Electron addon 适配鸿蒙的**技术域**知识（跨库成立、跨宿主不一定）：宿主运行时机制（Electron-OH 引擎/三关治理）、addon 编译（libshim 垫片链接）、API 判定数据、vendored 指南、示例源码、配套 shim。**其余技术栈用不到的知识落这里，不进 platform/**（platform 只放跨技术栈的平台底座）：
+
+```
+electron/
+├── addon-build.md            Electron-OH addon 编译权威（libshim.a 链接/node_api.h/HIDE_NAPI_AND_UV/
+│                             libuv 补充转发 examples//产物验证）
+├── guides/                   vendored 指南（Electron→鸿蒙迁移总指南、electron-builder 打包原理）
+├── bin/liburing_block.so     io_uring SIGSYS 拦截 shim（打私有 HNP 用；Electron-OH 主进程不受影响）
+└── examples/uv-supplement/   libuv 补充转发源码示例（addon-build.md 的配套件）
+```
+
+**不归这里**（各自轴的权威归属）：能力域替换方案（托盘/剪贴板等 → `pc-capability-domains`）、app 形态工程流程（→ `pc-delivery-forms/references/forms/`）、错误图谱条目（→ `pc-error-atlas`）。机器资产也不在此层（双版本应用模板在 `templates/hap/electron-app/`、napi 垫片在 `templates/build-tools/`）。
+
+### references/ — 同步参考文档（生成物）
+
+铁律手册、musl/glibc 逐接口对照、平台机制专题（构建系统/文件系统/调试方法论等）共 12 篇，由知识库同步管道拷贝生成（禁手改），索引见 `references/README.md`。
+
+> 边界情形按主要意图归类。跨类引用用相对路径。新增经验按此规则归入对应目录，并更新下方索引。
+
+### 知识双源与检索
+
+查「关于 X 有没有已知知识」优先用统一检索——跨**内置全部 skill 的 references + 错误图谱行级条目 + 个人知识库**，直接索引文档自身（frontmatter/标题/文件名），不依赖任何索引表的完备性：
+
+```bash
+ohpt-agent knowledge -s "<关键词>"   # 返回条目路径清单（渐进式披露第 0 层），再 Read 你需要的那一个
+```
+
+无 ohpt 时手工降级（内置+个人两边都读）：
+
+```bash
+ROOT="${PC_ADAPT_KNOWLEDGE_ROOT:-$HOME/.local/share/ohos-agent-pc-adapter/knowledge}"
+ls platform/ adaptation/ 2>/dev/null
+ls "$ROOT/memory/platform/" "$ROOT/memory/adaptation/" 2>/dev/null
+```
+
+### 第三条通道：API 与文档查证 skills
+
+除内置 references 与个人知识库外，**鸿蒙 API 签名与开发文档原文**走随包查证 skill 通道（兼容全局安装，用 Skill 工具加载而非 `ohpt-agent knowledge`）：
+
+- `harmonyos-sdk-api-lookup` — `api-references/` API 参考文档，查签名/类型/枚举/权限
+- `harmonyos-docs-lookup` — 官方开发指南/Kit 教程/场景规则
+
+安装与使用细则见 `harmonyos-pc-resources` skill 的「适配前置」节（权威归属在此，本节不复述）。适配全程不确定的鸿蒙 API/权限/Kit 语义必须先查证，不许猜测。
+
+## 编译场景
+
+三种编译场景，工具链配置不同：
+
+| 场景 | 编译机 | 目标机 | 工具链 | 当前状态 |
+|------|--------|--------|--------|---------|
+| **交叉编译** | Linux/Mac/Windows（x86_64） | 鸿蒙 PC（aarch64） | OHOS NDK clang + sysroot + 环境变量注入 | ✅ 本 skill 以下内容 |
+| **本机编译** | 鸿蒙 PC（aarch64） | 同一台鸿蒙 PC | 设备自带 clang（DevBox），无需 NDK/sysroot | ⏳ 扩展口（见下） |
+| **容器本机编译** | 主机 + Docker QEMU ARM64 | 鸿蒙 PC（aarch64） | 容器内原生 clang，QEMU 模拟 ARM64 | ⏳ 扩展口（见下） |
+
+> 语言特有知识（Python 分层降级流程、crossenv、设备 Python 运行时等）在各语言 reference 文件里，不在本 skill 重复。
+
+### 本机编译（鸿蒙PC上直接编）
+
+> ⏳ 扩展口：本机编译知识待补充。以下为预留骨架。
+
+- 环境准备：（待补：DevBox/HiShell/Harmonybrew/ohos-pip-autosign）
+- 工具链：本机 clang，不需 NDK sysroot
+- 签名规则差异：纯编译输出免签，`patchelf`/`llvm-strip`/`llvm-objcopy` 修改后必须重签
+- 特有坑：（待补：subprocess PATH 不继承、musl 显式 `-lpython3.12`、toybox 兼容性）
+
+### 容器本机编译（Docker ARM64 兜底）
+
+> ⏳ 扩展口：容器编译知识待补充。作为交叉编译和本机编译的兜底方案。
+
+- 原理：在 x86 主机上用 Docker + QEMU 启动 ARM64 鸿蒙容器，容器内是原生 ARM64 环境，所有构建系统（setuptools/meson/maturin）都当"本机编译"处理，不需要交叉编译工具链
+- 适用：交叉编译搞不定的复杂构建（meson/maturin/crossenv 不认），且主机有 Docker
+- 限制：QEMU 模拟执行慢（编译耗时数倍）；需 Docker 环境
+- 特有坑：（待补：QEMU 性能、容器内 hdc 访问设备、产物取出）
+
+## 通用约束
+
+- 鸿蒙 PC 三元组：`aarch64-unknown-linux-ohos`
+- **各语言的鸿蒙目标**（唯一权威）。判据列即 `ohpt-agent env --runtime <eco>` 落 `runtime_<eco>_host` 的判定；
+  stock 工具链没有鸿蒙目标，用它的普通 target 产的二进制**不是鸿蒙构建**。移植版获取入口查
+  `harmonyos-pc-resources` 的 `【运行时】开源运行时汇总.md`。
+
+  | 语言 | 鸿蒙目标 | 判据（宿主是否真能产鸿蒙产物） |
+  |---|---|---|
+  | C/C++ | `--target=aarch64-linux-ohos` + NDK sysroot | NDK 在位（见下节 `$DEVECO_SDK_HOME`） |
+  | Rust | `cargo build --target aarch64-unknown-linux-ohos` | `rustup target list --installed \| grep aarch64-unknown-linux-ohos` |
+  | Go | `GOOS=openharmony GOARCH=arm64`（**移植版 Go**，GOROOT 指向它 + `GOTOOLCHAIN=local`） | `go tool dist list \| grep openharmony/arm64` |
+
+- **构建系统 → 鸿蒙调用方式**（唯一权威）：
+
+  | build_system | 调用方式 |
+  |---|---|
+  | autotools | patch `config.guess`/`config.sub`（E007）；`./configure --host=aarch64-unknown-linux-ohos --prefix=…`；`make install DESTDIR=dist/lib/`。**Windows 宿主必须树内构建 + libtool 链接改 clang 直链**（树外构建秒死、libtool 链接必挂——死法诊断与配方见 `adaptation/鸿蒙PC-autotools库Windows宿主树内构建与直链交叉编译.md`，release tarball 全程不需要 MSYS2） |
+  | cmake | `-DCMAKE_TOOLCHAIN_FILE=ohos.toolchain.cmake -DOHOS_ARCH=arm64-v8a` |
+  | meson | cross-file 里 `system=linux` 规避 E090；`meson setup --cross-file build/ohos-cross.ini` |
+  | makefile | 直接用 OHOS clang/clang++ 覆盖 `CC`/`CXX` |
+
+- libc：**musl**（无 glibc 扩展）
+- 编译器：clang / clang++ / llvm-ar / llvm-ranlib / llvm-strip
+- `#ifdef __OHOS__` 是标准平台守卫；禁止用 `#ifndef __linux__`
+- **有符号溢出 UB 在 clang -O2 下现形**：`if (x < 0)` 式溢出检查依赖有符号溢出（UB），-O2 被优化成恒假——溢出位该抛的异常不抛（Java 风格 `parseLong` 移植高发，`-O0` 正常 `-O2` 挂是信号）。改用明确定义的比较（如 `== MIN_VALUE`），别靠 UB。
+- 工具链路径已写在 `.ohos-adaptation-pc/../build/ohos-cross.ini`（meson cross-file，含 clang/clang++/ar/strip 绝对路径与 sys_root）——直接用作 `meson setup --cross-file`，或据其取路径拼 CMake `-DCMAKE_TOOLCHAIN_FILE`/编译器路径。**不要去搜/读工具链包装脚本**（meson/clang 会自己调用并报错，按错误处理）。
+
+## 定位 DevEco SDK（本文档全局约定，其余文档只引用变量）
+
+各文档一律用 **`$DEVECO_SDK_HOME`** 指代 DevEco SDK 根，**不写宿主机绝对路径**（因平台/装法而异，跨机即废）。常用子路径：
+
+| 用途 | 路径 |
+|---|---|
+| NDK | `$DEVECO_SDK_HOME/default/openharmony/native` |
+| LLVM 工具（`llvm-readelf`/`llvm-objcopy`/`llvm-objdump`） | `$DEVECO_SDK_HOME/default/openharmony/native/llvm/bin` |
+| toolchains（`hdc` 等） | `$DEVECO_SDK_HOME/default/openharmony/toolchains` |
+
+怎么设：DevEco Studio 里 **Settings → OpenHarmony SDK** 看实际位置，或已装过 hvigor 的环境直接 `echo $DEVECO_SDK_HOME`。各平台默认位置不同（**示例**：macOS 是 `/Applications/DevEco-Studio.app/Contents/sdk`；Windows/Linux 在各自安装目录下的 `sdk`）——**以你机器的实际值为准，别照抄**。
+
+`build/env.sh` 里 fail-fast，其余路径由它派生：
+
+```bash
+export DEVECO_SDK_HOME="${DEVECO_SDK_HOME:?请先 export DEVECO_SDK_HOME}"
+```
+
+> ⚠️ 两个实测坑：
+> - **`llvm-readelf` 等默认不在 PATH**。直接敲会 `command not found`；若再叠个 `2>/dev/null`，就把「工具不存在」伪装成「没有匹配」的假阴性。用绝对路径调，或先把 `llvm/bin` 加进 PATH。
+> - **`toolchains/` 里的 `diff` 是坏桩**，且该目录常在 PATH 首位 → 系统 `diff` 被遮蔽。详见 `adaptation/鸿蒙PC-autotools-C二进制-goaccess.md`。
+
+### 环境能力探测判定程序
+
+Node 三方库额外宿主环境由 env/gate 同源派生：Electron demo 检查 electron_runtime（工程及核心引擎资源）+ sdk/hvigorw，原生扩展另检查 electron_toolchain/ndk。配置与降级语义见 pc-node-library/references/examples.md；未探测先刷新，不得当作确缺。其他项目保持原有宿主规则。
+
+宣告「环境缺少 SDK/hvigor/设备」前**必须先探测**，结果落 `.ohos-adaptation-pc/00-env.json`（装了 ohpt 用 `ohpt-agent env -w <workspace>` 一步完成并自动落盘；下面是无 ohpt 的手工等价）：
+
+| 命令 | 判定 |
+|---|---|
+| `echo $DEVECO_SDK_HOME` | 非空且目录存在 = SDK 在位；未设 ≠ 不存在——再按上文各平台默认位探测一次才可下结论 |
+| `which hvigorw`（Windows：`where hvigorw.bat`） | 命中 = 可构建 HAP；未命中再探 `$DEVECO_SDK_HOME/../tools/hvigor/bin`（command-line-tools 装法为 `../hvigor/bin`） |
+| `hdc list targets` | 有条目 = 鸿蒙 PC 设备可用；`[Empty]`/超时 = 当前不可用（**易变状态**，每次设备操作前复测）。无真机则设备验证整段留待有机时补，别在产物里自报已验（能力边界见 `platform/鸿蒙PC-hdc能力边界与取证通道.md`） |
+| `ohpt-agent env --runtime <eco>`（宿主侧跑上文目标表的判据列） | 落 `runtime_<eco>_host` 一个键：编译型生态（go/rust）的 `found` 表示「**宿主工具链具备鸿蒙目标**」而非「装没装」——stock 工具链会 found=false 并在 note 里说明。**设备侧不探**：鸿蒙 PC 上运行时一律自带，「设备有没有」不改变决策，程序见 `platform/鸿蒙PC-设备语言运行时探测与供给.md` |
+| SDK OpenHarmony 签名材料在位（`ohpt-agent env` 探为 `signing` 能力：`$DEVECO_SDK_HOME/…/toolchains/lib/OpenHarmony.p12` 等） | 有 = 能 **`ohpt-agent sign-demo`** headless 自签 demo HAP（零账号、任意 bundle，设备信任 OpenHarmony 根）；无 = 连 SDK 都没有才需兜底（走账号签名）。仅当**需装 HAP 验证**（`delivery_form=app` 或命中 GUI 面能力域）时才是前置。路线见 `platform/鸿蒙PC-HAP调试签名与设备安装信任链.md`（**HAP 装机签名 ≠ 下文 ELF `.so` 签名**） |
+  | **宿主构建工具链**（Windows 宿主 + 01-scan 的 `build_system` 非 trivial 时必探）：autotools → MSYS2 `autoreconf/automake/libtool/make/pkgconf`；cmake → `cmake`；meson → `meson` + pkg-config 模拟器；make → GNU make | 命中 = 可进 configure/构建；未命中 = **先在宿主装齐再进 port 阶段**（libetpan 实证：MSYS2 缺失废掉两轮 port-attempts，见 `adaptation/鸿蒙PC-Windows宿主构建环境四坑.md` 坑 7）。Windows 宿主无 pkg-config 时 meson 场景用 `templates/build-tools/pkg-config-shim/` 模拟器（坑 5）。**autotools 的「未命中」按源码形态分流**：git checkout（需 autoreconf 现生成 configure）才真需 MSYS2；**release tarball 的 configure 已预生成，Git Bash 树内即可全流程**（make 编译 + 直链绕 libtool，见 `adaptation/鸿蒙PC-autotools库Windows宿主树内构建与直链交叉编译.md`）——别把「MSYS2 缺失」当 autotools 项目的死刑 |
+
+
+## HMDFS 限制
+
+- `/tmp` 只读 → 用 `$TMPDIR` 或 `/data/local/tmp`
+- 不支持 `ln -sf` 覆盖 → `rm -f` 后 `ln -s` 或 `cp`
+- 不支持硬链接 → 用 `cp`
+- `chmod` 效果弱（依赖 chmod 的测试断言可跳过）
+
+> 机制详解见 `platform/鸿蒙PC-进程视角与mount-namespace.md`。
+
+## SELinux exec 限制
+
+- 子进程调用 `hnp_file` 类型工具可能被拦截 → 用 `cmd | cat` 绕过
+- 可执行二进制需 ELF 签名：**默认宿主链接期自签** `LDFLAGS='-Wl,--code-sign'`；设备侧 `binary-sign-tool -selfSign 1` 只有装了 DevBox 的机器才有（见下"签名"节）
+- `.so` 扩展模块**不需要** ELF 签名（dlopen 加载）——但零售设备可能强制，见下"签名"节
+
+> 机制详解见 `platform/鸿蒙PC-HNP二进制SELinux-exec限制.md`。
+
+## musl 兼容
+
+常见缺失函数：`secure_getenv` / `getpass` / `pthread_cancel` / `pthread_attr_setaffinity_np` / `struct ucred` / `SO_PEERCRED` → 补 stub 或 `#ifdef __OHOS__` 守卫。`<sys/unistd.h>` 不存在 → 切 `<unistd.h>`。
+
+`pthread_yield` 是 glibc 扩展、musl 无——**autoconf 检测 `HAVE_PTHREAD_YIELD` 会误判为真**（编译过、链接期才报 undefined reference）：在 config.h 取消该定义、保 `HAVE_SCHED_YIELD=1` 让代码走 `sched_yield()`。凡 autotools 检测 pthread_yield 的库都中招。
+
+结构体字段名差异：musl 的 `struct termios` 用 `__c_ispeed/__c_ospeed`（glibc 为 `c_ispeed/c_ospeed`）——JNI/FFI 直接读写 termios/winsize 等 libc 结构体时必查，用 `__MUSL__`/`__OHOS__` 宏切换字段名（jansi 实证，见 adaptation 案例）。
+
+**换名不是缺失**：glibc 导出 `program_invocation_short_name`，musl 导出 `__progname`（libc 初始化的 BSS 符号）——报 undefined reference 时先 `llvm-nm -D sysroot libc.so` 确认 musl 的对应名，往往补一个 `HAVE___PROGNAME=1` 探测项就走上游已有的 `#elif` 分支，**无需改源码**（libbsd 实证，详见 adaptation/鸿蒙PC-autotools库CMake替代交叉编译.md 的探测项实测法）。
+
+**overlay 头委托**：BSD 系库常用 `#include_next <md5.h>` 把系统头「叠」在自己头上面——musl 不提供该头时直接编炸。修法：委托外面包 `#if defined(__has_include_next) && __has_include_next(<md5.h>)` 守卫，缺失时回落库自带实现。**依赖判定连带**：这类头是纯 overlay（`MD5_CTX` 等类型定义在被委托方的头里）——开了对应 ABI 开关（如 `LIBBSD_ABI_MD5=1`）就必须 vendor 被委托库（libmd），否则头有声明、实现没有，自相矛盾。
+
+## 依赖处理（拓扑序）
+
+- 按 `01-scan.json` 的 `library_closure.nodes` 拓扑序编译：被依赖的先编。
+- 每个依赖隔离在 `deps/<dep>-<ver>/dist/`，主库用 `-DCMAKE_PREFIX_PATH` 或 `PKG_CONFIG_PATH` 引用。
+- 复用优先：`status=reuse` 的依赖按四级获取序取产物（同轮已编 `dist/` → 个人库拷回 → 中心制品仓拉取，见 `pc-registry`），不重编；`status=recipe-build` 从我们新仓 clone 配方；`status=fresh-adapt` 从上游 clone 全新编。
+- 常见依赖处理：OpenSSL 加 `no-asm`；ncurses 加 `--without-shared`；Boost 禁用 b2/bjam 改用 CMake。
+
+## 交叉编译产物落位
+
+目录归属的单一真源是 `pc-workspace-layout`（本文不复述）。交叉编译只加一条：
+**在临时区 `git apply patches/` 再编，不污染 `source/`**。
+
+## 签名（看设备策略）
+
+> **本节讲二进制/ELF `.so` 签名（dlopen/exec）。装 HAP 是另一套**——`bm install` 校验 PKCS7 profile 信任链，**自签必拒、root 也拦、`install_no_sign` 在 user 版不生效**，「放宽签名」只对 `.so` 成立。需装 demo/应用 HAP 验证 GUI 时见 `platform/鸿蒙PC-HAP调试签名与设备安装信任链.md` / E120。
+
+dlopen 的 `.so` **在鸿蒙 PC 上一律需要 ELF 签名**（强制代码签名；设备自带扩展有 `.codesign` 段，
+`llvm-readelf -S <设备 lib-dynload/*.so> | grep -i codesign` 可验），未签名 `.so` 加载失败。两条签法：
+- **链接期自签（默认，首选）**：`LDFLAGS='-Wl,--code-sign'`；注意 post-link `strip` 会破坏签名段。
+- **设备自签**：装了 DevBox 的设备，其 HiShell PATH 上有 `binary-sign-tool`，`-selfSign 1` 自签即可被该设备接受：
+  ```bash
+  llvm-objcopy --remove-section .codesign "$so"
+  binary-sign-tool sign -inFile "$so" -outFile "$so" -selfSign 1
+  chmod +x "$so"
+  ```
+  操作走 `pc-device-verify` skill（HiShell 在装好的包里给所有 `.so` 自签后 import/跑用例）。
+
+> 实测结论（鸿蒙 PC）：未签名 `.so` 加载报 `Permission denied`（OHOS 代码签名强制，chmod 无用）；DevBox `binary-sign-tool -selfSign 1` 自签后正常加载。设备端操作见 `pc-device-verify` skill。
+
+## 本机只查产物，运行只在设备
+
+**本机**仅静态检查：
+```bash
+file <artifact>   # 应为: ELF 64-bit LSB ... ARM aarch64
+```
+**绝不在本机运行/import 目标产物**（aarch64-ohos/musl，本机 Windows/x64 跑不起来）。跑用例一律 hdc 送设备：
+```bash
+hdc list targets                         # 无在线设备 → 记 blocker、status=built-pending-verification
+hdc file send dist/lib/<artifact> /data/local/tmp/<lib>/
+hdc shell "cd /data/local/tmp/<lib> && <device run command>"
+```
+本机交叉编译成功 = `build_status=pass`；设备跑通才填 `test_run`。
+
+## 运行时库加载
+
+交叉编译时 `-L` 找到的系统库（如 `libcrypto.so`），运行时设备上可能不在标准路径 → `dlopen`/`import` 报 `cannot open shared object file`。三种解法：
+
+| 方案 | 命令 | 适用场景 |
+|------|------|---------|
+| `LD_PRELOAD` | `LD_PRELOAD=/path/to/libcrypto.so <target>` | 临时测试、少量库 |
+| `LD_LIBRARY_PATH` | `export LD_LIBRARY_PATH=/path/to/libs:$LD_LIBRARY_PATH` | 多个库共用一套依赖 |
+| 系统库集成 | `.so` 放入 `/usr/lib` 或 `/system/lib` | 生产部署 |
+
+> 编译时链接成功 ≠ 运行时能找到——这是常见陷阱，`dlopen`/`import` 报 `undefined symbol` 时先查这个。
+
+## RUNPATH $ORIGIN 问题
+
+musl 动态链接器对 RUNPATH 中 `$ORIGIN` 的支持有 bug → 运行时报 "Error loading shared library" 但库文件确实存在。
+
+诊断：`llvm-readelf -d module.so | grep -E "RPATH|RUNPATH"`，若显示 RUNPATH 且含 `$ORIGIN`，可能有问题。
+
+解法：用 `patchelf --force-rpath` 将 RUNPATH 转换为 RPATH：
+```bash
+patchelf --force-rpath --set-rpath '$ORIGIN/../package.libs' module.so
+```
+
+## 状态语义（adapt 必须用新语义）
+
+- `built-and-verified`：产物 + 真机验证跑通，且**原库用例在设备上真跑过（≥1 条）并全部通过**（不是 pass_rate=1）
+  - 用例取原库自带的（`test_source=reused`）；原库没有测试套件，就在 `tests-generated/` 补几个冒烟用例（`generated`）——schema 要求终态时 `total_cases ≥ 1`、`passed ≥ 1`、`test_source != none`，**没跑用例就写不出终态**。设备侧未通过的逐条进 `test_run.regressions`（非空即写不出终态）。
+  - `pass_rate = passed / (passed + failed)`，**skipped 不计入分母**；仅作报告数值，**不是 built-and-verified 的判据**。
+  - ⚠️ 这几个值是 `03-adapt.json` 的 **`status`** 字段（enum：`built-and-verified｜built-pending-verification｜partial｜failed｜skipped`）。`04-summary.json` 的 **`adaptation_status`** 是**另一套** enum（`success｜partial｜failed｜infeasible｜blocked`），**两者别串**：03-adapt 写 `status=success` 会被 PostWrite Hook 的 schema 校验直接拒。
+- `built-pending-verification`：产物 + runbook 齐备，验证交设备主人（`build_status=pass` + `test_run.executed=false`，本机无设备）——**不是 failed/partial**，正名"产物已就绪待验证"
+- `partial`：有未修复的**未通过用例**，或部分编通/部分产物
+- `failed`：编不出/无产物
+
+> 旧设计把"本机编得出但没设备"判成 `partial`，低估成果。新语义用 `built-pending-verification` 正名。
+
+## 失败升级规则
+
+连续 ≥3 次同类问题无法解决 → `status=partial` + 记卡点 + 落 `03-adapt.json` 交回 orchestrator。不要无限重试。**无论成功/部分/阻塞/失败，结束前一定写出 `03-adapt.json`**（至少含 status 与 remaining_blockers），绝不空手退出。
+
+## 平台机制索引（platform/）
+
+| 机制 | 文件 | 要点 |
+|------|------|------|
+| 进程视角与 mount namespace | `platform/鸿蒙PC-进程视角与mount-namespace.md` | hdc shell 和应用进程文件系统视图不同，跨视图操作走 `nsenter -t <pid> -m` |
+| HNP 包与 PATH | `platform/鸿蒙PC-HNP包与PATH.md` | HNP 包安装位置、应用与 hdc shell 的 PATH 差异 |
+| SELinux exec 限制 | `platform/鸿蒙PC-HNP二进制SELinux-exec限制.md` | hnp_file 标签、hmmac 拦截、cp 到 data_local_tmp 绕过 |
+| uid 与文件归属 | `platform/鸿蒙PC-uid与文件归属.md` | file_manager 与应用 uid 体系、HOME/桌面文件归属 |
+| 设备 Python 运行时 | `platform/鸿蒙PC-设备Python运行时.md` | 设备 Python 3.12.8 路径/ABI/site-packages |
+| 设备语言运行时供给 | `platform/鸿蒙PC-设备语言运行时探测与供给.md` | **一律自带**（app 域够不到别人的）：产物来源表 + 打私有 HNP + device_status 判定程序 |
+| HAP 调试签名与安装信任链 | `platform/鸿蒙PC-HAP调试签名与设备安装信任链.md` | 装 HAP 校验 PKCS7（≠ELF 签名）；自签必拒；DevEco 自动签名复用 / install_no_sign 路线；何时需签、code:9568257 |
+| 设备 pip 部署 | `platform/鸿蒙PC-设备pip部署.md` | TMPDIR/HOME/MPLCONFIGDIR 重定向、离线 wheel、--no-deps |
+| 沙箱与物理路径映射 | `platform/鸿蒙PC-应用沙箱与物理路径映射.md` | 桌面逻辑路径 ↔ hdc shell 真实路径 |
+| hdc 基础 | `platform/鸿蒙PC-连接设备与hdc基础.md` | hdc 命令基础、file send/recv、shell |
+| hdc 能力边界与取证通道 | `platform/鸿蒙PC-hdc能力边界与取证通道.md` | shell 域够得到什么/够不到什么；hilog 取证必须先提级别再冷启动；截图与公共目录两条辅助通道；宿主侧转存字节直写（管道 GBK 乱码假告警）+ 证据解析按 bundle tagpath/时间窗双过滤（共享设备混流） |
+| 从 Mac 访问设备 | `platform/鸿蒙PC-从Mac访问设备网络服务.md` | hdc fport 端口转发、网络可达性 |
+| git 行为定制 | `platform/鸿蒙PC-定制git行为.md` | global gitconfig 路径变更、safe.directory |
+| HiShell 手动兜底 | `platform/鸿蒙PC-不可调试设备用HiShell自动化测试.md` | 自动化走不通时用 HiShell 手动跑测试 |
+| 真机跑官方测试套件 | `platform/鸿蒙PC-真机跑官方测试套件.md` | pytest/cargo test/UnitTest++/CppUnit 真机跑 + 失败三分类；CppUnit 1.15.x API 迁移要点 |
+| POSIX/NDK 能力探针矩阵 | `platform/鸿蒙PC-POSIX-NDK能力探针矩阵.md` | 46 项能力实测（45 OK / 仅 robust mutex 缺）；判底层接口能不能用，不必逐库重测 |
+| app 域 exec 与 JIT 限制 | `platform/鸿蒙PC-app域执行二进制与JIT限制.md` | HAP 内 spawn ELF 四道关+seccomp 黑名单（io_uring/close_range/semget）：只有私有 HNP 可 exec、V8 JIT 写不了可执行内存、SIGINT 优雅退出失效（runner 侧 reset SIG_IGN + 产品侧 __OHOS__ patch 去 foreground gate，pty 造终端实测无效） |
+| **私有 HNP 打包与 exec 平台差异** | `platform/鸿蒙PC-私有HNP打包与exec平台差异.md` | exec 成败只看 zip 内 mode（0667+显式目录条目+hnp.json LF）；6.0 展平目录缺标签 EACCES / 6.1 正常；execv 127 ≠ 平台限制（先 realpath 验 HNP 落地再归因）；hvigor 不收 entry/hnp 需 zip 注入 |
+| app 访问 PC 用户目录 | `platform/鸿蒙PC-app访问PC用户目录.md` | Documents/Download 可申请权限直读写；Desktop 是 system_basic 够不着 |
+| 64KB 页对齐 so 崩溃 | `platform/鸿蒙PC-64KB页对齐so崩溃.md` | 0x10000 对齐 LOAD 段的 .so 在 4KB 页设备 dlopen 直接 SIGSEGV；强制 `-Wl,-z,max-page-size=0x1000` |
+| 窗口几何控制 | `platform/鸿蒙PC-窗口几何控制无native只ArkTS.md` | resize/move/全屏无 native NDK，只 ArkTS `@ohos.window`；native 要走反向桥 |
+| **musl/BSD/glibc 语义分歧表** | `platform/鸿蒙PC-musl与BSD-glibc语义分歧表.md` | 断言平台字面量（错误文案/字节序列/多字节行为/日期时区）前先查；errno/stdio/locale/数值解析/时间格式化五族分歧与断言改写法——写测试预期按 musl 事实，不照抄 BSD/glibc man 手册 |
+| **app 域测试前置条件矩阵** | `platform/鸿蒙PC-app域测试前置条件矩阵.md` | HAP 内跑测试前查前置可不可满足（mknod/命名管道/AF_UNIX 路径/终端/故障注入/真实 ELF fixture/HMDFS 锁语义）＋等价构造法；总纲：纯函数常量构造，别当 IO 函数测 |
+| **aarch64 指令档位与运行时分发** | `platform/鸿蒙PC-aarch64指令档位与运行时分发.md` | 选 `-march` 的唯一权威：安全基线 `armv8-a+crypto+crc`，更高档位（LSE/SVE/sha3…）只能 getauxval(AT_HWCAP/AT_HWCAP2) 运行时分发；编死高档 = 设备上 SIGILL；含档位表、分发模式与诊断路径 |
+| **CLI 工具 main() 平台能力检查降级模式** | `platform/鸿蒙PC-CLI工具main函数平台能力检查降级模式.md` | CLI 工具 `main()` 先查平台能力（libusb_init/XOpenDisplay/SDL_Init…）失败即退，导致参数解析/TCP/格式校验全被锁死：parse_opts 提前 + 能力检查非致命 + have_xxx 守卫 + 回调 NULL 安全；usbredirect 实证 |
+| **随包数据树 LF 归一与 configure 生成物补齐** | `platform/鸿蒙PC-随包数据树LF归一与configure生成物补齐.md` | Windows git 树打 HNP 后设备端声明式配置解析器逐行 `\r` 报 syntax error（配置生成不了→正路径用例连锁失败、pass 集全为否定路径）；git 树缺 bootstrap/configure 生成物报 Not found。打包期递归 LF（NUL 判二进制跳过，禁白名单扩展名）+ 生成物清单 diff 补齐 |
+| **随包 wrapper 脚本 shebang 自指与 busybox seccomp** | `platform/鸿蒙PC-随包wrapper脚本shebang自指与busybox-seccomp.md` | 随包 wrapper `#!/bin/bash` 在设备上 rc=126（bad interpreter，无标准 FHS）；busybox applet 在 app 域 seccomp 被 SIGSYS（rc=159，GNU 同调用通过）——文本处理管道与**网络下载 applet（wget）都实证中招**。shebang 自指 HNP 内 bash 绝对路径 + 验证链关键 applet 用真 GNU ELF 替换（wget→curl shim：参数翻译 + CURL_CA_FALLBACK，摘要工具换 coreutils） |
+| **GNU make 4.4.1 交叉编译（随包 make 解释器）** | `platform/鸿蒙PC-GNU-make-4.4.1交叉编译随包.md` | 随包 CLI 框架需 make 解释器时，autotools 交叉编译四条铁律：config.sub 从 某交叉工具链工程 源码取替换（比标准补丁省事）、`-static` 避 libc++_shared 缺失、`-Wl,--code-sign` 自签、ld.lld 并行崩溃降 `-j1` 续编不重来 |
+| **Vulkan 上屏通路** | `platform/鸿蒙PC-Vulkan上屏通路.md` | GPU 渲染栈 surface→swapchain→present 三段通路结构：②③由系统 swapchain layer + 驱动 ICD 承接（加载器须能发现激活）；**dlopen 与链接互斥（符号冲突）**、gralloc/acquire/release 系统内部接口应用不调、**验证载体只有真窗口表面算数**、app 域 present/fence 同步同源风险 + 最小探针差分 |
+
+> 平台机制速查见 `knowledge/platform-notes.md`（HNP/PATH/SELinux/uid/mount ns/桌面路径/git 一页速查）。
+> 口径提醒：`POSIX-NDK能力探针矩阵` 测的是 **root/NDK 层**——root 能用 ≠ app 域能用，app 域另有 SELinux/seccomp/XPM 限制（见 `app域执行二进制与JIT限制`）。
+
+## 库适配经验索引（adaptation/）
+
+### 编译栈（库 / CLI 交叉编译）
+
+| 库/场景 | 文件 | 要点 |
+|---------|------|------|
+| C++ 库通用 | `adaptation/鸿蒙PC-C++库交叉编译要点.md` | C++ 交叉编译通用要点；§11 compiler-rt builtins 塞 `LIBS` 末尾；别把 NDK sysroot 的桩 `.so` 打进包 |
+| **宿主无 GNU make 的确定性构建驱动（通用）** | `adaptation/鸿蒙PC-宿主无GNU-make的确定性构建驱动.md` | Windows 宿主无 make/WSL 时别手抄命令：Python 驱动解析 makefile 树（include/变量/ifdef/静态清单）复现编译语义、直接驱动 NDK clang；决策序（先找官方生成器）+ 反模式；7zip 323 单元实证 |
+| **Windows 宿主构建环境八坑（通用）** | `adaptation/鸿蒙PC-Windows宿主构建环境四坑.md` | NDK ld.lld 并行链接崩溃（0xC0000005）降 -j1 续编不重来；hvigorw 需 Windows 原生环境（MSYS2 PATH 下 spawn java ENOENT）；hvigor 拒项目路径含 `+` 等非法字符（00306003，junction 绕不开需物理复制）；meson `run_command('test','-d')` 无 test 命令；Windows 无 pkg-config 用模拟器；**NDK 封装脚本 Program Files 断裂（E137）**；**autotools 缺 MSYS2 废 port 尝试（坑 7）**；**PowerShell 一次性维护脚本三连（坑 8）：内联 `node -e` 的 `$1` 被 PS 插值吞掉静默写坏文件、持久 shell cwd 泄漏致验证假阳性、脚本 rmSync 自删目录**；均宿主侧环境问题、非产物缺陷 |
+| **版本脚本裁剪库（通用）** | `adaptation/鸿蒙PC-版本脚本裁剪库的导出面审计.md` | 头声明 ⊆ 产物导出 ∪ libc 委托 的四集对账；已实现却未导出 = map 漏收（libbsd sl_delete 实证）；overlay 委托（asprintf→musl）是合法设计勿误报 |
+| **C 库设备验证测试设计（通用）** | `adaptation/鸿蒙PC-C库设备验证测试设计.md` | 上游套件优先（含编进 NAPI 壳手法）＋按 API 族的边界用例模板库（数值解析/编码往返/fd 生命周期/流操作）＋三分法分测试投入——手挑 happy path 冒烟 = 自选分母 |
+| **CMocka 头文件 uintptr_t 条件宏（通用）** | `adaptation/鸿蒙PC-CMocka头文件uintptr_t条件宏缺__MUSL__守卫重复定义.md` | CMocka 头文件 uintptr_t 条件宏缺 `__MUSL__` 守卫导致 musl 平台重复定义。修法：在 `_UINTPTR_T` 等条件链追加 `&& !defined(__MUSL__)`。可推广到 cJSON 等含类型回退 typedef 的库 |
+| **cpp-lib 双载体验证 OHPTCASE 协议（通用）** | `adaptation/鸿蒙PC-cpp-lib双载体验证OHPTCASE协议配方.md` | 双载体真机验证完整配方：hap（NAPI dlopen 冒烟核心链路）+ cli（测试 ELF 链接期自签 + 私有 HNP fork+execv 逐条直跑 + OHPTCASE 协议上报 + hilog 整条取证）。取证前必须 hilog -b D + aa force-stop 冷启动 |
+| autotools C 二进制（goaccess） | `adaptation/鸿蒙PC-autotools-C二进制-goaccess.md` | autotools 交叉编译 + 静态 ncurses；**config.h 不生成的真凶是 DevEco 的坏 `diff`**（PATH 首位、缺文件返回 0） |
+| autotools 大型应用（nmap） | `adaptation/鸿蒙PC-nmap-autotools交叉编译与真机扫描.md` | config.sub 不认 ohos 用 gnu 三元组、仅 in-tree 构建、精准 shim 目录修工具链；raw socket 在 hdc shell 域全通 |
+| autotools 媒体应用（VLC） | `adaptation/鸿蒙PC-VLC-autotools媒体应用移植.md` | OHOS 当 bionic-linux vendor 仿 android 支线；`open_memstream` 坏；HAP 装载用 SONAME 别 patchelf；真机播 mp4 |
+| git 2.49 | `adaptation/鸿蒙PC-git-适配要点.md` | 直接用 Makefile 变量跳过 configure（绕开 E007）、NO_* 最小化依赖、XPM 要推 Documents 而非 /data/local/tmp |
+| Java JNI 库（jansi） | `adaptation/鸿蒙PC-Java-JNI库交叉编译与设备回归-jansi.md` | NDK 直编复用上游 Makefile 变量；OSInfo os.name 两策略；musl termios 字段名；自签 + junit-console 设备全量回归 |
+| Rust + BoringSSL（quiche） | `adaptation/鸿蒙PC-Rust-BoringSSL-quiche.md` | Rust 交叉编译 + BoringSSL 依赖 + bindgen sysroot + libstdc++→libc++ shim |
+| Python C 扩展（pycosat） | `adaptation/鸿蒙PC-Python-C扩展交叉编译.md` | 基础套路：拉设备头、`-lpython3.12`、`.cpython-312.so` 命名、dlopen 无需签名 |
+| meson+Cython+numpy（PyWavelets） | `adaptation/鸿蒙PC-meson-Cython-numpy扩展.md` | 别硬上 meson 交叉编译，手动 cythonize 逐模块编；numpy 版本必须与设备一致 |
+| 扩展依赖 native 库（pyzmq） | `adaptation/鸿蒙PC-pyzmq-libzmq扩展.md` | 三段式：CMake 编静态库 → cythonize → clang++ 静态链入 |
+| numpy OpenBLAS bug | `adaptation/鸿蒙PC-numpy-OpenBLAS-armv8sve复数点积bug.md` | 设备 numpy wheel 复数点积 bug + OPENBLAS_CORETYPE 绕开 |
+| OpenCL SDK | `adaptation/鸿蒙PC-OpenCL-SDK-适配要点.md` | 零补丁编过；Maleoon 916 支持 OpenCL 3.0；无标准 ICD 要 `OCL_ICD_FILENAMES` 指 passthrough |
+| OpenSSL 系密码库 | `adaptation/鸿蒙PC-OpenSSL系密码库交叉编译.md` | Perl Configure 复用 `linux-aarch64` + 覆盖 CC/CXX/AR/RANLIB，禁用 Linux 特有引擎，`-Wl,--code-sign`；TLS 内存握手测试需服务端自签证书；OpenSSL 国密分支 NTLS 默认禁用需显式 `enable-ntls`（静默能力缺失，llvm-nm 符号级复核） |
+| autotools 库 CMake 替代 | `adaptation/鸿蒙PC-autotools库CMake替代交叉编译.md` | Windows 无 MSYS2 时 CMake 重写：手写 CMakeLists 列源文件 + 手写 config.h 宏 + NDK toolchain + 依赖走 Conan；671/671 编过 |
+| **autotools Windows 树内+直链（通用）** | `adaptation/鸿蒙PC-autotools库Windows宿主树内构建与直链交叉编译.md` | release tarball 无需 MSYS2：Git Bash 树内 configure+make（原生 make 编完全部对象）→ libtool 链接挂改 clang 直链 → 手工 install；CLI/测试同模式直编；**树外构建是死路**（No rule to make target）；与 CMake 替代按分流判据二选一 |
+| CMake FetchContent 多仓库 C++ 库 | `adaptation/鸿蒙PC-CMake-FetchContent多仓库C++库交叉编译.md` | zlib 用上游 fork 拿 ZLIB::ZLIBSTATIC；其中一层工具库打 pthread_cancel 守卫；全静态 + 链接期自签 |
+| CLI 调试器（autotools+autosetup） | `adaptation/鸿蒙PC-CLI调试器-autotools-autosetup交叉编译.md` | `--enable-internal-<内嵌脚本引擎>` + 禁 Linux 专属适配器；autosetup 子模块显式 `CC_FOR_BUILD`；脚本引擎 EvalFile MinGW stat=0 静默失效 + CLI 用例设计要点 |
+| POSIX 系 C++ 类库 | `adaptation/鸿蒙PC-POSIX系C++类库交叉编译与设备验证.md` | `CMAKE_SYSTEM_NAME=Linux` 触发 UNIX 分支；seccomp 禁 SysV IPC 用 Android 桩；HAP 载体 dlopen 验证核心功能 + 原库单元测试套件环境注入清单；TLS 握手失败先查服务端 TLS 空桩、别误判平台缺陷 |
+| **CGAL 高模板库分批（通用）** | `adaptation/鸿蒙PC-CGAL高模板库交叉编译分批策略.md` | 模板 AOT 实例化单 TU 15-30 分钟的时间管理：ninja -j1 可中断续编 + 按产物分批落盘锚点；GMP/MPFR 直取 Conan cgal/6.2 包；并行过高 OOM/ld.lld 崩（0xC0000005），批间 .codesign 校验 |
+| PyGObject/g-i（**反面**） | `adaptation/鸿蒙PC-PyGObject-introspection交叉编译墙.md` | g-ir-scanner host/target 劈叉，交叉编译走不通；typelib 是硬依赖 → 换 GTK C 前端或 ArkUI |
+| usbredir USB 重定向工具 | `adaptation/鸿蒙PC-usbredir-USB重定向工具降级适配.md` | `usbredirect` main() 的 `libusb_init` 在 `parse_opts` 之前，HAP 域无 USB 访问→所有 CLI 功能被锁死；降级重构（parse_opts 提前 + libusb 非致命 + have_usb 守卫 + 回调 NULL 安全）；TCP/设备标识解析可独立测试；补丁 0003 |
+
+### GUI / 图形栈（XComponent 缝 + 工具包后端）
+
+> **先读 OWB**：`通用视窗桥ohos_window_bridge` 是把 XComponent→OHNativeWindow 这道缝抽出来的**可复用公共层**，下面 GLFW/Qt/GTK 各条都坐在它（或同一道缝）上。新库接入只写 L3。
+
+| 库/场景 | 文件 | 要点 |
+|---------|------|------|
+| **通用视窗桥 OWB** | `adaptation/鸿蒙PC-通用视窗桥ohos_window_bridge.md` | 纯 C 公共层：GPU(EGL/Vulkan) + CPU-blit 双上屏 + 事件队列 + VSync；`OWB_OHOS_THREAD_APP` 让存量 `int main()` 零改动上鸿蒙 |
+| XComponent CPU 像素缝 | `adaptation/鸿蒙PC-XComponent-CPU像素渲染与输入缝.md` | SURFACE 型 XComponent + NativeWindow：RequestBuffer→mmap→按 **stride**（非 W*4）写 RGBA→FlushBuffer；普通签名 HAP 即可 |
+| GLFW 鸿蒙后端 | `adaptation/鸿蒙PC-GLFW视窗后端-EGL-XComponent.md` | `_GLFW_OHOS` 平台后端（坐 OWB 上）：平台 ID 要加两处白名单、`-z,max-page-size=0x1000`、设备只有裸 `libEGL.so` |
+| pyGLFW（语言绑定通用式） | `adaptation/鸿蒙PC-pyGLFW-Python绑定库迁移.md` | 绑定库通用公式：原生库共享化 + 用绑定自带「指定库路径」机制零补丁 + 解释器线程壳；打包三坑 |
+| Qt6 CMake GUI（NotepadNext） | `adaptation/鸿蒙PC-Qt6-CMake-GUI应用移植.md` | `qt.toolchain.cmake` 交叉编译、patch 让 `qt_add_executable` 产出 dlopen 用的 `.so`、qrc 两连坑、打签名 HAP |
+| Qt6 QtQuick 补编 | `adaptation/鸿蒙PC-Qt6-qtdeclarative-QtQuick交叉编译.md` | 给鸿蒙 Qt6.5.6 补编 qtdeclarative(QtQml/QtQuick)+QuickControls2 |
+| VLC 原生 Qt6 界面 | `adaptation/鸿蒙PC-VLC原生Qt界面移植.md` | 不重写、直接跑 VLC 自带 Qt 界面：app 域禁 fork/exec 三处补丁、QApplication 主线程分支、视频经 vmem 嵌进界面 |
+| GTK3 broadway + ArkWeb | `adaptation/鸿蒙PC-GTK应用broadway-ArkWeb-HAP.md` | GTK broadway 后端→broadwayd(HTTP/WS)→ArkWeb `Web` 组件显示；真机交互成功 |
+| cmd-pkgs 预编译 GTK（**反面**） | `adaptation/鸿蒙PC-cmd-pkgs预编译GTK栈不可用.md` | glib 静态烤进每个库→多份冲突 GObject 类型系统，救不了；要 GTK 必须从源码自编 |
+| VisualVM / JVM Swing | `adaptation/鸿蒙PC-VisualVM-JVM-Swing应用移植.md` | 复用 OH-AWT 定制 BishengJDK8 嵌进 HAP；签名 profile 必须含 `ALLOW_WRITABLE_CODE_MEMORY`（JVM CodeCache 硬需） |
+
+### 应用形态与部署（HAP / HNP / Electron / Node）
+
+| 库/场景 | 文件 | 要点 |
+|---------|------|------|
+| electron-vite+React → HAP | `adaptation/鸿蒙PC-electron-vite-React应用-OHElectron-HAP.md` | 纯 JS Electron 应用同构迁 OH-Electron 25：代码直塞 resfile，无需 sidecar/HNP；Electron 41→25 五改造 |
+| opencode HAP 化 | `adaptation/鸿蒙PC-opencode-HAP化-Electron壳.md` | OH-Electron 当窗口壳 + HAP 自带 Node24 当 sidecar；私有 HNP 打包 + hvigor 注入 |
+| opencode 部署/打包/WebUI | `adaptation/鸿蒙PC-opencode*.md`（4 篇） | opencode 插件部署/离线打包/WebUI 嵌入/rg exec denied |
+| 纯 JS 库（bcrypt-pbkdf） | `adaptation/鸿蒙PC-纯JS库部署到HNP-node.md` | 纯 JS 库零交叉编译，部署到设备 HNP node v24；`process.platform === 'openharmony'` |
+| systeminformation | `adaptation/鸿蒙PC-systeminformation-平台分支.md` | process.platform 分支 + /proc 取信息 |
+| ipykernel/Jupyter | `adaptation/鸿蒙PC-ipykernel-Jupyter内核.md` | 端到端 Jupyter 内核适配（重依赖树纯 Python 库落地） |
+| PixelTune 子进程 Python 应用 | `adaptation/鸿蒙PC-PixelTune-子进程Python应用.md` | ArkTS-UI + Python/Pillow **子进程后端**通用式：HNP 打库 + forkpty + NAPI execSync + argv/JSON 契约（distill 自社区应用，非本仓真机） |
+| **旧版 gui test-demo 升级 NAPI 用例桥（通用）** | `adaptation/鸿蒙PC-gui-test-demo-旧版OhptCaseRunner升级NAPI桥.md` | 旧 scaffold 的 gui 载体（OhptCaseRunner 写文件+命令行拉起）升级为页面点击即执行：`exports.runCase(caseId)` Promise 桥 + 常驻渲染循环 + `std::once_flag` 去重双 worker + 步骤痕迹结果区 + RunAllPage 页内一把执行。配套 error-atlas E162/E163（指针比较坑 / busy 清位顺序坑） |
+
+> Python 特有的库落地经验在 `pc-delivery-forms/references/languages/python.md`。适配案例速查见 `knowledge/case-studies.md`。这些是"曾经怎么做过"的参考。照着对**当前工作区 source/** 复刻/重建，产物自己重新构建。
+>
+> ⚠️ `platform/`、`adaptation/` 里**不含任何仓外路径**——内置知识全部自足，照着做即可，没有"去某个仓看产物"这一步。唯一例外是 `knowledge/` 速查里块尾的 `<!-- src: … -->`，那只是来源标注、指向原始适配仓，**不随本插件发布**，不要用 Read 去读（会被宿主拒）。
+
+## 错误查找
+
+遇编译/链接/运行错误 → `pc-error-atlas` skill 的错误图谱（542 条 E 码，同步生成物）：grep error-index → 读 E*.md → 查 platform-notes。覆盖工具链(E001/E012/E053)、文件系统(E002/E018/E079)、autotools(E007/E072/E041)、链接(E003/E005/E028)、musl(E020/E081/E085)、CMake/Meson(E090/E092/E096/E103) 等。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-C++/345/272/223/344/272/244/345/217/211/347/274/226/350/257/221/350/246/201/347/202/271.md

@@ -0,0 +1,181 @@
+---
+name: 鸿蒙PC-C++库交叉编译要点
+description: OHOS clang 同时定义 `__linux__` 和 `__OHOS__`；Boost b2 toolset 必须叫 `linux-ohos`；CA bundle 在 `/etc/ssl/certs/cacert.pem`（非标准路径）；musl 缺 `pthread_setcancelstate`；`libc++_shared.so` 设备自带；compiler-rt builtins 要塞 LIBS 末尾；module-mode find_package 报 NOTFOUND 用 -D<Pkg>_LIBRARY/_INCLUDE_DIR 硬指
+metadata:
+  type: adaptation
+  source: new/PC
+---
+
+# 鸿蒙 PC C++ 库交叉编译要点
+
+来自 cpprestsdk 适配（2026-05-20，cpprestsdk 2.10.19）。下次要把 boost/asio 系/openssl 系/其他 C++ 大库适配到鸿蒙 PC（target `aarch64-unknown-linux-ohos`）时，先查这里。
+
+---
+
+## 1. OHOS clang **同时定义** `__linux__` 和 `__OHOS__`
+
+**为什么重要**：绝大多数 `#if defined(__ANDROID__) || defined(__linux__)` 的代码**自动走对路径**，不需要源码改动。
+
+**怎么验证**：
+```bash
+$OHOS_NDK_HOME/llvm/bin/aarch64-unknown-linux-ohos-clang++ \
+  -dM -E -x c++ /dev/null | grep -E "__OHOS__|__linux__|__ANDROID__"
+```
+- `__linux__ 1` ✓
+- `__OHOS__ 1` ✓
+- `__ANDROID__` 不定义
+
+**什么时候要打 `__OHOS__` 守卫**：当原代码对**纯 Linux**和 **Android** 分了不同分支，而你不想被错路由到 Android 分支时（如调 `__android_log_print`）。cpprestsdk 2.10.19 适配下来 **C++ 源码 0 改动**，预计大多数现代 C++ 库都这样。
+
+---
+
+## 2. Boost.Build (b2) 交叉编译两个必踩坑
+
+**坑 A — toolset 命名**：`user-config.jam` 里写 `using clang : ohos : ...` 会路由到 `clang-darwin.jam`（在 macOS host 上）或 `clang-darwin/linux/vxworks.jam` 的错误分支。**必须命名为 `using clang : linux-ohos : ...`**，b2 才会拼出 `clang-linux-ohos` 工具集并路由到 `clang-linux.jam`。
+
+**坑 B — `clang.jam` 的 `init-flags-cross` 强塞 `--target`**：即便 user-config 已经写了 `--target=aarch64-unknown-linux-ohos`，`tools/build/src/tools/clang.jam` 在 `target-os=linux` 路径下会**追加** `--target=arm64-pc-linux`，**两个 `--target` clang 取后者**，结果编出来不是 OHOS ELF。
+
+**修法**：patch 掉那行：
+```diff
+- toolset.add-flags clang-linux <link>... --target=arm64-pc-linux
++ # toolset.add-flags clang-linux <link>... --target=arm64-pc-linux  # patched for OHOS cross
+```
+具体参考 cpprestsdk 的 boost-ohos 构建补丁。
+
+**怎么验证**：build 之后 `file libboost_*.a | head -1` 应该是 `ARM aarch64`；如果显示 `x86_64` 或 `arm64-pc-linux`，就是中招了。
+
+---
+
+## 3. Boost 子集 `--with-libraries=` 推荐起点
+
+cpprestsdk 实测必需：`system,thread,chrono,atomic,date_time,regex,random`。**不**需要 `filesystem/iostreams/locale`。
+
+通用建议：先给最小集，build 失败再补；不要无脑全开 — Boost 全集编译 ≥ 20 分钟，子集 5 分钟。
+
+---
+
+## 4. musl 缺的两个 POSIX 接口
+
+OHOS userland 是 musl libc。常见缺失：
+
+- `pthread_setcancelstate` — Boost.Core `sp_thread_sleep` 用，Android 已有例外，OHOS 同样要打。
+- `pthread_cancel` 配套缺失。
+
+**修法**：在 `boost/core/detail/sp_thread_sleep.hpp` 把 OHOS 加进现有的 Android 例外即可（参考 `patches/0002-boost-ohos-build.patch`）。
+
+下次遇到 `undefined reference to pthread_setcancelstate`，先怀疑这里。
+
+---
+
+## 5. CA bundle 路径**非标准**
+
+设备路径：`/etc/ssl/certs/cacert.pem`（**不是** Linux 习惯的 `ca-certificates.crt`）。
+
+OpenSSL `SSL_CTX_set_default_verify_paths()` 找不到，所有 HTTPS / WSS 客户端会报 `certificate verify failed`。
+
+**两种修法**：
+- 进程级：`export SSL_CERT_FILE=/etc/ssl/certs/cacert.pem`（OpenSSL 1.1.1 优先读它）
+- 代码级：`SSL_CTX_load_verify_file(ctx, "/etc/ssl/certs/cacert.pem", NULL)`
+
+推荐进程级，业务代码无需修改。
+
+---
+
+## 6. `libc++_shared.so` 已在设备 `/system/lib64/`
+
+NDK 自带：`$OHOS_NDK_HOME/llvm/lib/aarch64-linux-ohos/libc++_shared.so`，但应用不用打包：设备有 `/system/lib64/libc++_shared.so`，loader 默认能找到。
+
+**怎么验证**：
+```bash
+hdc shell ls /system/lib64/libc++_shared.so
+hdc shell readelf -d /data/local/tmp/your_bin 2>&1 | grep NEEDED
+```
+DT_NEEDED 里有 `libc++_shared.so` 但不需要在应用包里附带。
+
+**⚠️ 反面：别把 NDK sysroot 的 `.so` 当运行时库打进应用包**。`$NDK/native/sysroot/usr/lib/aarch64-linux-ohos/*.so`（如 `libz.so`）很多是**只供链接的桩**——`llvm-nm -D` 看到所有函数同一地址即是桩，运行时函数空操作/返回垃圾（zlib 桩会让 PNG 解码、qrc 解压全失败）。修法二选一：
+
+1. **打真库**：从设备 pull 真库（`/system/usr/lib/libz.so.1.2.13`、`/system/lib64/platformsdk/`）。详见 [[鸿蒙PC-Qt6-CMake-GUI应用移植]] §11。
+2. **静态链入**（cpp-lib 首选，某图像库 实证）：conan 中心仓 `libz.a` 静态库，`-DZLIB_LIBRARY=<path>/libz.a` 静态链入产物——运行时零额外依赖（某图像库 产物仅依赖设备自带 libc++_shared.so + libc.so），免去随包带设备库。详见 [[鸿蒙PC-图像处理库-CImg图像库交叉编译]] §2.4。
+
+---
+
+## 7. 公开头传递依赖：消费者 `-I` 路径要带原始第三方头
+
+把第三方库静态链接进自己的 `.so` 后，**消费者编译时仍然需要那些第三方库的头文件**（如果你的 `.so` 公开头 `#include` 了它们）。
+
+cpprestsdk 例：`<cpprest/http_client.h>` 内部 `#include <boost/asio/ssl.hpp>`。即便我们把 Boost + OpenSSL 静态打进 `libcpprest.so`，消费者编译时 include 路径还要带 `-I dist/boost/include -I dist/openssl/include`。
+
+**怎么避免**：自己再加一层 facade 头，把所有 boost/openssl 类型隐藏在 PIMPL 后面。代价是工作量，**多数情况下不值得**，直接把 boost+openssl 头跟自己的 dist 一起发就行。
+
+---
+
+## 8. CMake `CMAKE_FIND_ROOT_PATH` 与交叉编译
+
+用 `ohos.toolchain.cmake` 时，`CMAKE_FIND_ROOT_PATH_MODE_{INCLUDE,LIBRARY,PACKAGE}` 默认 `ONLY`，会让 `find_package(OpenSSL)` 跳过 sysroot 外的目录。
+
+**修法**：把它们改为 `BOTH` 并把自己的 `dist/` 加进 `CMAKE_FIND_ROOT_PATH`：
+
+```cmake
+-DCMAKE_FIND_ROOT_PATH_MODE_INCLUDE=BOTH
+-DCMAKE_FIND_ROOT_PATH_MODE_LIBRARY=BOTH
+-DCMAKE_FIND_ROOT_PATH_MODE_PACKAGE=BOTH
+-DCMAKE_FIND_ROOT_PATH="$OHOS_NDK_HOME;dist/boost;dist/openssl;dist/zlib"
+```
+
+否则 cpprestsdk 等库的 `find_package(OpenSSL)` 会找不到你交叉编译产出的静态库。
+
+### 8b. Module-mode `Find*.cmake`（`pkg_check_modules` + `find_library`）—— `CMAKE_FIND_ROOT_PATH=BOTH` 仍可能 NOTFOUND
+
+§8 的 `CMAKE_FIND_ROOT_PATH_MODE=BOTH` 对 **config-mode**（`find_package(Foo CONFIG)` 读 `FooConfig.cmake`）够用；但很多系统库走 **module-mode**（CMake 自带 `FindFontconfig.cmake` / `FindFreetype.cmake`，内部先 `pkg_check_modules` 再 `find_library`/`find_path` 定位实体）。交叉态下 `find_library` 会把 `CMAKE_PREFIX_PATH` / `PKG_*_LIBRARY_DIRS` **重根**到 `CMAKE_FIND_ROOT_PATH` 下再找，**即便设了 `BOTH` 也常报** `Fontconfig_LIBRARY-NOTFOUND` / `FREETYPE_INCLUDE_DIR-NOTFOUND`（libaribcaption 适配实测＝错误图谱 E028；不懂这点会反复重编 6+ 轮试错）。
+
+**最稳的修法：直接命令行显式覆盖 Find 模块要找的实体变量，绕过自动查找**（`<Pkg>` 用 Find 模块内部的变量名，注意大小写）：
+```bash
+-DFontconfig_LIBRARY="$FONTCONFIG_PREFIX/lib/libfontconfig.so" \
+-DFontconfig_INCLUDE_DIR="$FONTCONFIG_PREFIX/include" \
+-DFREETYPE_LIBRARY="$FREETYPE_PREFIX/lib/libfreetype.so" \
+-DFREETYPE_INCLUDE_DIR_ft2build="$FREETYPE_PREFIX/include/freetype2" \
+-DFREETYPE_INCLUDE_DIR_freetype2="$FREETYPE_PREFIX/include/freetype2"
+```
+排查口诀：`find_package` 报 `<Pkg>_LIBRARY-NOTFOUND` / `_INCLUDE_DIR-NOTFOUND` 时，**先判是不是 module-mode**（构建日志里出现 `pkg_check_modules` / `find_library`，或 CMakeCache 里有 `<Pkg>_*-NOTFOUND` 条目）。是就别再纠结 `CMAKE_FIND_ROOT_PATH`，直接 `-D<Pkg>_LIBRARY=… -D<Pkg>_INCLUDE_DIR=…` 硬指；变量名从 host CMake 安装目录的 `Modules/Find<Pkg>.cmake` 或 CMakeCache 的 `*-NOTFOUND` 条目抄。
+
+---
+
+## 9. `-Wno-unused-command-line-argument` 几乎必加
+
+OHOS toolchain 自动注入 `--gcc-toolchain=...`，但是 clang 实际不用，会发 warning。如果上游有 `-Werror`（cpprestsdk 就有），会编不过。
+
+**默认开**：`-DCMAKE_C_FLAGS="-Wno-unused-command-line-argument" -DCMAKE_CXX_FLAGS=...`
+
+---
+
+## 10. strip 收益
+
+OHOS clang 默认带 debug info，stripped vs unstripped 差 30% 左右。生产分发用 stripped + 保留 `.debug` 边车：
+
+```bash
+cp libfoo.so libfoo.so.debug
+$OHOS_NDK_HOME/llvm/bin/llvm-strip --strip-unneeded libfoo.so
+```
+
+stripped 不破坏 SONAME / DT_NEEDED / BuildID，只删 debug section 和符号表（保留导出符号）。
+
+---
+
+## 11. compiler-rt builtins 链接顺序（`undefined symbol: __muloti4` 等）
+
+用 `__int128` / 128 位整数运算的 C++ 代码会引用 compiler-rt builtin（`__muloti4`、`__udivti3`…）。clang **默认**把 `libclang_rt.builtins.a` 放链接行**末尾**，单独 `-shared`（含 `-z,defs`）都能自动链上。**但** libtool 链 module 时把内部静态便利库（autotools `noinst_LTLIBRARIES`，如 VLC 的 `libvlc_mp4.la`）追加在 builtins **之后** → 这些晚到的 `.a` 里的 builtin 引用无人满足，报 `undefined symbol: __muloti4`。
+
+**修法**：把 builtins 塞到 autoconf **`LIBS`**（automake 把 `$(LIBS)` 放链接行绝对末尾，在所有便利库之后）：
+```sh
+export LIBS="-L$(dirname $($CC -print-libgcc-file-name)) -lclang_rt.builtins"
+```
+**别加进 `LDFLAGS`**（在 objects 之前，顺序仍不对）。VLC 移植实例见 [[鸿蒙PC-VLC-autotools媒体应用移植]] §4。
+
+---
+
+## 相关条目
+
+- [鸿蒙PC-进程视角与mount-namespace.md](../platform/鸿蒙PC-进程视角与mount-namespace.md) — hdc shell 与应用进程文件系统视图
+- [鸿蒙PC-uid与文件归属.md](../platform/鸿蒙PC-uid与文件归属.md) — 应用怎么访问桌面文件
+- [[鸿蒙PC-VLC-autotools媒体应用移植]] — 大型 autotools/media 应用移植（OHOS=bionic-linux vendor、android/thread.c 复用、本条 §11 的实例）
+- [[鸿蒙PC-Qt6-CMake-GUI应用移植]] — Qt6/CMake 桌面 GUI 应用移植（§11 有 NDK sysroot 桩 `.so` 的实例）