@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/adaptation//351/270/277/350/222/231PC-Windows/345/256/277/344/270/273/346/236/204/345/273/272/347/216/257/345/242/203/345/233/233/345/235/221.md

@@ -0,0 +1,170 @@
+---
+name: 鸿蒙PC-Windows宿主构建环境八坑
+description: >-
+  Windows 宿主上交叉编译/打包/维护 OHOS 产物的环境坑合集：
+  ① NDK ld.lld 并行链接多实例访问冲突崩溃（0xC0000005），降 make -j1 从中断处续编即可，已编译产物不受影响；
+  ② hvigorw 打包需在 Windows 原生环境运行，MSYS2 混合 PATH 下 Node spawn java 报 ENOENT；
+  ③ hvigor 校验项目物理路径，含 `+` 等非法字符报 00306003（junction 软链绕不开）；
+  ④ meson run_command('test','-d',...) 在 Windows 宿主因无 `test` 命令失败，改用 fs.is_dir() 替代；
+  ⑤ Windows 宿主无 pkg-config，需模拟器（Python 脚本从 Conan 依赖目录回填 .pc 数据）；
+  ⑥ NDK 目标封装脚本在 Program Files 路径下因 `exec $SOURCE` 未加引号而断裂；
+  ⑦ autotools 项目在 Windows 宿主上缺 MSYS2 时无法 autoreconf 生成 configure；
+  ⑧ PowerShell 会话跑一次性维护脚本：内联 node -e 的 `$1` 被 PS 插值吞掉静默写坏文件、持久 shell cwd 泄漏致验证假阳性、脚本 rmSync 自删目录致重跑 MODULE_NOT_FOUND。
+  均属宿主侧环境问题、非产物缺陷。
+  触发词：Windows 宿主、ld.lld、0xC0000005、并行链接崩溃、make -j1 续编、hvigorw、spawn java ENOENT、
+  MSYS2 PATH、assembleApp、assembleHap、00306003、Invalid project path、项目路径、非法字符、plus、+、
+  meson、run_command、test -d、fs.is_dir、pkg-config、Windows 无 pkg-config、pkg-config 模拟器、
+  pkg-config.py、Conan、.pc 文件、pkg-config 缺失、NDK 封装脚本、aarch64-unknown-linux-ohos-clang、
+  exec $SOURCE、Program Files、cannot create executables、autotools、MSYS2、autoreconf、autoconf、
+  automake、libtool、configure 缺失、PowerShell、node -e、$1 插值、Set-Location、cwd 泄漏、
+  MODULE_NOT_FOUND、静默写坏、git diff --no-index、退出码 1。
+metadata:
+  type: adaptation
+  source: >-
+    usbredir 0.15.0 适配实证（meson run_command + pkg-config 缺失，2026-09）+
+    openocd 0.12.0+dev（hvigor 路径限制，2026-09）+
+    new/PC（密码库可选协议套件重建轮实证，ld.lld 并行崩溃）+
+    libetpan 适配实证（NDK 空格路径封装 + MSYS2 缺失，2026-09）+
+    补丁集重导出实证（PowerShell 维护脚本三连，2026-09-21）
+---
+# Windows 宿主构建环境八坑
+
+> 通用：与具体库无关，凡在 Windows 宿主上交叉编译 OHOS 产物均适用。所有项目均属**宿主侧环境
+> 问题、非产物缺陷**——归因时先排除这些再怀疑产物。
+
+## 1. NDK ld.lld 并行链接崩溃 → 降 -j1 续编
+
+Windows 宿主上 `make -j8` 并行重建时，NDK `ld.lld` 多实例并发在批量链接阶段访问冲突崩溃
+（Exception 0xC0000005，signal 终止）。**已编译产物不受影响**，降 `make -j1` 从中断处续编
+即可完成，无需清理重来。
+
+> 与 E074 区分：E074 是**设备侧** SELinux 禁 FIFO 导致 make jobserver 起不来（make 报
+> `cannot make pipe: Permission denied`）；本条是 **Windows 宿主侧**链接器自身并发崩溃，
+> 现象是 ld.lld 进程异常终止，不是 make 的权限报错。
+
+## 2. hvigorw 打包需 Windows 原生环境
+
+`hvigorw assembleHap`/`assembleApp` 在 MSYS2 混合 PATH 下 Node `spawn java` 报 ENOENT
+（java 在 Windows 原生 PATH 里，MSYS2 环境下解析失败）。从 PowerShell/CMD 原生环境重跑
+即解决——不要把 MSYS2 的 PATH 带进 hvigor 构建。
+
+## 3. hvigor 拒绝项目路径含非法字符（00306003）
+
+`hvigorw assembleHap`/`assembleApp` 会校验**项目绝对路径**，含 `+` 等非法字符时报
+`00306003 Specification Limit Violation — Invalid project path`，只允许字母/数字/连字符
+(`-`)/下划线(`_`)/句点(`.`)/英文括号/空格/`@`。典型：workdir 根目录名带 `+`（如
+`repos-pc/某库`）。**hvigor 校验的是物理路径**：`mklink /J`（目录 junction）软链
+绕不开——node `process.cwd()`/`pwd -P` 会解析回物理路径、仍含 `+`。处置：把 demo 工程**物理复制**
+到无 `+` 目录再构建，或建工作区时就避免在路径里放 `+` 等非法字符。
+
+## 4. meson `run_command('test', '-d', ...)` 失败（Windows 无 `test` 命令）
+
+meson 的 `run_command` 在 configure 期调用宿主 shell 执行外部程序。上游在 meson.build 里
+写 `.git` 存在性判别时用了 `run_command('test', '-d', '.git')`，Windows 宿主（PowerShell/CMD）
+**根本没有 `test` 命令**（POSIX 工具）→ meson setup 直接报错中止。
+
+**解法**：把 `run_command('test', '-d', X)` 全部替换为 `fs.is_dir(X)`（meson 内建模块，
+纯 Python 实现，不依赖宿主外部命令）：
+
+```meson
+fs = import('fs')
+if fs.is_dir('.git')
+```
+
+patch 示例（usbredir 0001 实测，适用于任何 meson 项目在 Windows 宿主交叉编译时遇到的同类问题）：
+
+```diff
+-run_command('test', '-d', '.git')
++fs.is_dir('.git')
+```
+
+也适用于 `run_command('test', '-f', ...)`（文件存在性）→ `fs.exists()` 或 `fs.is_file()`。
+
+> 与 E136 关联：E136 是这条错误的图谱索引，含更详细的排查流程与替代方案对照表。
+
+## 5. Windows 宿主无 pkg-config → 需模拟器
+
+meson 构建中依赖 `.pc` 文件获取编译/链接标志（`dependency('libusb')` 等），
+Windows 原生环境无 `pkg-config` 命令。交叉编译时 meson 通过 cross-file 的 `pkg-config` 字段
+指定外部命令，找不到则报 `Library dependency not found` 或 `Unknown compiler`。
+
+**解法**：用 Python 编写的 pkg-config 模拟器，从 `PKG_CONFIG_PATH`（Conan 依赖目录下的
+`lib/pkgconfig/`）读取 `.pc` 文件，回填 `--cflags`/`--libs`/`--modversion` 等。
+
+配套文件：
+- `pkg-config.py`：纯 Python 实现，支持 `--cflags`/`--libs`/`--modversion`/`--exists`/
+  `--variable`/递归 Requires 解析/`--define-prefix`（自动根据 `.pc` 所在目录推算前缀）。
+- `pkg-config.cmd`：Windows cmd 封装，`python "%~dp0pkg-config.py" %*`。
+
+如何在 meson cross-file 中引用：
+
+```ini
+[binaries]
+# cross-file 的 binaries 段声明 pkg-config 路径
+pkg-config = 'D:/path/to/build/bin/pkg-config.cmd'
+
+[built-in options]
+# 同时设 PKG_CONFIG_PATH 指向 Conan 产出的 .pc 目录
+c_args = ['-DPKG_CONFIG_PATH=<conan-deps>/lib/pkgconfig']
+```
+
+> 该模拟器支持递归解析 Requires/Requires.private，自动过滤 `-l:ld-musl*` 的不兼容引用。
+> 模板位置：`<ohpt-agent>/templates/build-tools/pkg-config-shim/`，可复用至任何 Windows
+> 宿主下的 meson/cmake 项目（改 `PKG_CONFIG_PATH` 即可）。
+
+**CMake 变体（某图像库 实证，E140）**：CMake 项目在 Windows 宿主撞 `find_package(PkgConfig
+REQUIRED)` 配置即失败时，先核对每个 `pkg_check_modules` 是否都服务**可选依赖**
+（FFTW/CURL/X11…）——是，则把 `REQUIRED` 改 `QUIET` 即可让配置通过、对应功能自然裁剪；
+对非 REQUIRED 的 `find_package(PNG/JPEG/TIFF)` 保持原样。**判别口诀：全可选才敢 QUIET。**
+落地样例见 `patches/0001-某图像库-ohos-cross-compile-adaptations.patch`（某图像库 工作区）。
+功能被裁剪时同步裁剪验证用例（某图像库 24 条全用 BMP），避免断言不存在的功能。
+
+## 6. NDK 目标封装脚本在 Program Files 下断裂
+
+DevEco 默认装 `C:\Program Files\Huawei\DevEco Studio\...`，NDK 的
+`llvm/bin/aarch64-unknown-linux-ohos-clang` 封装脚本 `exec $SOURCE/clang` **未给 `$SOURCE` 加引号**，
+路径在空格处断裂 → configure 报 `C compiler cannot create executables`（config.log 里
+`/c/Program: No such file or directory`）。这不是 cc 缺失（E001），是封装脚本自身引用缺陷。
+
+**解法**：自建引号封装脚本放无空格路径（`exec "$NDK/llvm/bin/clang" -target aarch64-linux-ohos
+--sysroot="$NDK/sysroot" -D__MUSL__ "$@"`），`CC/CXX` 指向它。详细见 `pc-error-atlas` E137。
+
+## 7. autotools 项目在 Windows 宿主缺 MSYS2
+
+autotools 项目（configure.ac）在 Windows 宿主上**没有 autoreconf 就生成不了 configure**——
+`./configure` 脚本根本不存在。libetpan 适配实证：阶段 3 两轮 port-attempts 因 MSYS2 缺失未产出，
+health 诊断后才装齐 autoconf/automake/libtool/make/pkgconf。
+
+**解法**：进入 port 阶段前先做**宿主工具链 preflight**——按 01-scan 的 `build_system` 核对：
+
+| build_system | Windows 宿主前置 | 验证命令 |
+|---|---|---|
+| autotools | MSYS2 + autoconf/automake/libtool/pkgconf | `autoreconf --version`（MSYS2 shell 内） |
+| cmake | cmake + ninja/make | `cmake --version` |
+| meson | meson + pkg-config 模拟器 | `meson --version` |
+| make | GNU make | `make --version` |
+
+缺啥装啥（MSYS2 内 `pacman -S autoconf automake libtool make pkgconf`），**装齐再进 configure**，
+别带着缺失进入尝试循环——每一轮尝试都烧 gate 的 port-attempts。
+
+## 8. PowerShell 会话跑一次性维护脚本：静默写坏三连
+
+适配期在 Windows 宿主上写一次性维护脚本（补丁重导出、产物核对类）的三个实证坑（补丁集重导出实证，2026-09-21）：
+
+1. **`$` 插值吞替换组**：`node -e "…replace(re, '$1' + real)…"` 经 PowerShell 双引号传参，`$1` 被 PS
+   当（未定义）变量插值成空串 → 替换结果丢掉捕获组、**静默写坏目标文件**（全程无报错，事后抽查才发现）。
+   非平凡逻辑一律写成 `.mjs` 脚本文件再 `node script.mjs` 执行，不走内联 `-e`。
+2. **持久 shell cwd 泄漏**：某次调用里 `Set-Location` 之后，后续调用的 workdir 参数可能不生效，
+   相对路径解析到残留目录 → **验证出现假阳性**（`git apply --check` 在错误目录 exit=0，误判补丁可套用）。
+   跨调用一律绝对路径、`git -C <dir>`，或在命令块内显式 `Set-Location` 到目标目录再执行判定类命令。
+3. **脚本自删**：脚本里 `rmSync` 清理的临时目录若就是脚本自身所在目录，首次运行成功（已加载进内存）、
+   重跑 `MODULE_NOT_FOUND`——脚本目录与它的工作/临时目录必须分离。
+
+附：`git diff --no-index` 发现差异时退出码 1，execSync 会当错误抛出——捕获后取 `e.stdout`。
+
+## 相关
+
+- [[鸿蒙PC-宿主无GNU-make的确定性构建驱动]] —— Windows 宿主无 make 时的另一条路（Python 驱动复现编译语义）。
+- `pc-error-atlas` E074 —— 设备侧 make -j 并行失败（SELinux FIFO），与本条坑 1 同形不同因。
+- `pc-error-atlas` E136 —— 坑 4 的图谱索引（run_command('test','-d') 在 Windows 宿主缺失 test 命令）。
+- `pc-error-atlas` E137 —— 坑 6 的图谱索引（NDK 封装脚本 Program Files 断裂）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-XComponent-CPU/345/203/217/347/264/240/346/270/262/346/237/223/344/270/216/350/276/223/345/205/245/347/274/235.md

@@ -0,0 +1,57 @@
+---
+name: 鸿蒙PC-XComponent-CPU像素渲染与输入缝
+description: 在 HAP 里用 XComponent SURFACE 把 CPU 像素 blit 上屏 + 接输入回调（GUI 工具包鸿蒙化的平台缝，gdk-ohos/任意 QPA 类后端都靠它）
+metadata:
+  type: adaptation
+  source: new/PC
+---
+
+把任意「自己渲染像素的 GUI 工具包」搬到鸿蒙 PC，平台相关的只有一道缝：**CPU 像素 → XComponent 上屏 + XComponent 输入回调 → 工具包事件**。Qt 的 QPA、要写的 GTK gdk-ohos 后端都坐在这道缝上。2026-06-26 用一个最小 HAP 真机验证通过（nmap GUI/Phase 4 spike）：渐变背景上屏 + 白方块跟随点击。参考 Qt `qtbase/.../platforms/openharmony/qohplatformbackingstore.cpp`。
+
+## 一、ArkUI 侧：SURFACE 型 XComponent 自动加载 native .so
+```
+XComponent({ id: 'xcgdk_surface', type: XComponentType.SURFACE, libraryname: 'xcgdk' })
+```
+- `libraryname:'xcgdk'` → 系统加载 `libxcgdk.so`，调它的 napi 模块 Init，并在 `exports` 上挂 XComponent 实例。**ETS 侧不需要 import 这个 .so、不需要 @types 声明**（删干净 oh-package.json5 里的 `@types/...so` devDependency + lock + oh_modules/@types，否则 CompileArkTS 报 ENOENT stat 那个 .so）。
+- `type` 用 **SURFACE**（不是 Qt 模板的 NODE）才走 onSurfaceCreated→NativeWindow 这条原生 surface 路径。
+
+## 二、native 侧：拿 XComponent + 注册回调
+```c
+// napi 模块 Init(env, exports)：
+napi_get_named_property(env, exports, OH_NATIVE_XCOMPONENT_OBJ, &inst);
+napi_unwrap(env, inst, (void**)&component);          // OH_NativeXComponent*
+OH_NativeXComponent_Callback cb{};
+cb.OnSurfaceCreated/OnSurfaceChanged/OnSurfaceDestroyed/DispatchTouchEvent = ...;
+OH_NativeXComponent_RegisterCallback(component, &cb); // ret==0 即成功
+// 模块用 napi_module_register + __attribute__((constructor)) 注册，nm_modname 必须 == libraryname。
+```
+- `OnSurfaceCreated(comp, void* window)`：**`window` 直接就是 `OHNativeWindow*`**，存下来用于上屏。`OH_NativeXComponent_GetXComponentSize(comp, window, &w, &h)` 拿尺寸。
+- 鼠标/键盘另注册 `OH_NativeXComponent_RegisterMouseEventCallback / RegisterKeyEventCallbackWithResult / RegisterUIInputEventCallback`；触摸用 cb.DispatchTouchEvent 里 `OH_NativeXComponent_GetTouchEvent(comp,window,&te)` 取 `te.x/te.y/te.type`。
+
+## 三、上屏：RequestBuffer → mmap → 按 stride 写 → FlushBuffer（CPU 软件路径）
+```c
+OH_NativeWindow_NativeWindowRequestBuffer(win, &buf, &fenceFd);
+BufferHandle* bh = OH_NativeWindow_GetBufferHandleFromNative(buf);
+uint8_t* p = mmap(bh->virAddr, bh->size, PROT_READ|PROT_WRITE, MAP_SHARED, bh->fd, 0);
+// 逐像素写：W=bh->width, H=bh->height, 行间距 = bh->stride（字节，非 W*4！）
+//   像素是 RGBA8888（4B/px）。实测 2090px 宽 → stride=8448B（≈2112*4，对齐到 64px），size=stride*H。
+//   必须用 p + y*stride + x*4 寻址，绝不能用 y*W*4，否则斜切/花屏。
+Region region{ .rects=nullptr, .rectNumber=0 };       // 整屏刷
+OH_NativeWindow_NativeWindowFlushBuffer(win, buf, fenceFd, region);
+munmap(p, bh->size);
+// 失败回收：OH_NativeWindow_NativeWindowAbortBuffer(win, buf);
+```
+- **关键**：`stride != width*4`，要从 BufferHandle 读真实 stride。这是 CPU-blit 唯一易错点。
+- GTK 接法：cairo 用 `CAIRO_FORMAT_ARGB32` 画到 image surface（`cairo_image_surface_get_data/stride`），再把每行 memcpy 进 NativeWindow buffer（注意 cairo ARGB32 是预乘、字节序 BGRA on little-endian，与 OHOS RGBA8888 通道顺序可能要换；spike 直接写 RGBA 验证过通路，cairo 接入时校通道）。
+
+## 四、CMake / 链接 / 构建
+- `entry/build-profile.json5` 的 `buildOption.externalNativeOptions.path = "./src/main/cpp/CMakeLists.txt"`，`abiFilters:["arm64-v8a"]` → hvigor 自动用 ohos.toolchain.cmake 跑 CMake+Ninja。
+- CMakeLists `target_link_libraries`：`libace_napi.z.so`(napi) `libace_ndk.z.so`(XComponent) `libnative_window.so`(NativeWindow) `libhilog_ndk.z.so`(日志)。头：`<napi/native_api.h>`、`<ace/xcomponent/native_interface_xcomponent.h>`、`<native_window/external_window.h>`（BufferHandle/Region 都在这）。
+- CLI 出签名 HAP：`DEVECO_SDK_HOME=…/sdk node …/hvigor/bin/hvigorw.js assembleHap -p product=default -p buildMode=release --no-daemon`；`hdc install -r` + `aa start -b <bundle> -a EntryAbility`。复用 calculator-ohos 的签名就沿用 bundleName `com.qt.calculator`（窗口标题会显示 "Calculator"，不影响）。
+- 真机日志 tag `A0FF00/<bundle>/<自定tag>`；截图 `hdc shell snapshot_display -f /data/local/tmp/x.jpeg`（后缀必须 .jpeg）。
+
+## GPU/EGL 变体 + 抽象成公共层（2026-07-01 补）
+CPU-blit（三）不是唯一上屏路径。同一道缝的 **GPU 路径**：拿到 `OHNativeWindow*` 后交给 `eglCreateWindowSurface(dpy,cfg,win,...)`（或 Vulkan `vkCreateSurfaceOHOS`，`VK_OHOS_surface` NDK 已带）走硬件 GLES/VK 渲染，帧驱动用 `OH_NativeXComponent_RegisterOnFrameCallback`(VSync, OHOS11+)。这道缝（GPU+CPU 双 helper + 库中立事件队列 + 帧扇出）已抽成可复用公共层 [[鸿蒙PC-通用视窗桥ohos_window_bridge]]，第一个消费者是 GLFW（[[鸿蒙PC-GLFW视窗后端-EGL-XComponent]]，真机 HAP 已打包）。判据：GL/VK 图形库走 GPU 路径、自绘 CPU 工具包(GTK/Qt-raster)走 CPU 路径，都坐同一道缝。
+
+## 结论
+这道缝完全通，且是 **app 域内、普通签名 HAP** 就能跑（无需 root、无需特殊权限）。GUI 工具包鸿蒙化（gdk-ohos 后端、自绘 UI）= 把工具包的「渲染输出」接到三、把工具包的「事件源」接到二，其余工具包逻辑不动。相关：[[鸿蒙PC-Qt6-CMake-GUI应用移植]]（Qt 走同一道缝但 QPA 已现成）、[[鸿蒙PC-nmap-autotools交叉编译与真机扫描]]（同项目 CLI 引擎侧）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-autotools-C/344/272/214/350/277/233/345/210/266-goaccess.md

@@ -0,0 +1,47 @@
+---
+name: 鸿蒙PC-autotools-C二进制-goaccess
+description: 从 Mac 交叉编译 autotools C 程序（goaccess）+ 静态 ncurses 的套路与三个非显然坑
+metadata:
+  type: adaptation
+  source: new/PC
+---
+
+从 Mac 用 DevEco NDK 交叉编译 autotools 的 C 程序（goaccess 1.10.2，43k 行，依赖 ncursesw）。**源码零 patch**，真机 `--version` + 解析 access log → JSON 全对。但踩了三个非显然的坑，都不是源码兼容问题，是**交叉构建工程**问题。
+
+## 与"鸿蒙原生编译"铁律的边界
+
+memory 里的铁律 P-AUTOTOOLS-001"禁止 --build/--host"是针对**在设备上原生编译**。但设备 clang wrapper 失效（[[鸿蒙PC-pyzmq-libzmq扩展]]），只能 **Mac 交叉编译**，此时 `--host=aarch64-linux-ohos --build=aarch64-apple-darwin` 是**必须的**（让 configure 跳过 run-test，只做 compile/link test）。两种场景别混。
+
+## 坑 1：ncurses 静态库交叉编译要跳过 tic
+
+goaccess 需 ncursesw。设备虽有 `/usr/lib/libncursesw.so.6`（系统 zsh 依赖它，**别碰共享库**），但缺头文件。自己交叉编 **静态** libncursesw.a（复用 archives 的 ohos config.guess/sub patch）：
+- 配置：`--without-shared --enable-widec --enable-overwrite`（archives 的 ncurses 6.4 配方）
+- **`--with-fallbacks` 会触发编 `tic`**（terminfo 编译器，需在 build 主机跑），cross 时链接缺 `_nc_fallback2` 失败。**不要加 fallbacks**，并用 **`make libs && make install.libs install.includes`**（只编库装库头，跳过 progs/tic）。
+
+## 坑 2：构建期代码生成工具必须用 host 编译器
+
+goaccess 用 `bin2c`（把 CSS/JS 资源转成 C 头）。autotools 把它当普通 program 用 `$(CC)`=target 编 → 在 Mac 上"cannot execute binary file"。
+对策：**先 host 编 bin2c**：`make CC=clang CPPFLAGS= LDFLAGS= LDADD= LIBS= bin2c`（清空 LDADD 去掉误带的 -lncursesw），再 target `make` 主体——make 见 bin2c 已最新就直接拿来生成 .h。任何 autotools 项目里"自举的 codegen 工具"都这么办。
+
+## 坑 3：config.status 说 `... is unchanged` 但 config.h 根本不存在 —— 真凶是 DevEco 的坏 `diff`
+
+`./configure` 报 OK，但 `config.status` 反复说 `creating src/config.h ... is unchanged` 而文件根本不存在。
+
+**真凶**：**DevEco Studio 的 `toolchains/diff` 是个坏桩**——`$DEVECO_SDK_HOME/default/openharmony/toolchains`（见 `SKILL.md` 的「定位 DevEco SDK」）默认在 PATH 首位，那个 `diff` 对**缺失文件**返回 `exit 0` 且不报错（还不支持 `-q`）。autoconf `config.status` 生成 header 的逻辑是 `if diff "$ac_file" "$tmp/config.h"; then echo "is unchanged"; else mv ...; fi`——坏 diff 让它误判「无变化」→ **一个 header 都不写**。
+
+验证：
+```bash
+diff /nonexistent /dev/null; echo $?              # 坏 diff → 0
+/usr/bin/diff /nonexistent /dev/null; echo $?     # 正常 → 2
+```
+
+**对策**（比手写 config.h 干净）：建 shim 目录放 PATH 最前，`ln -sf /usr/bin/diff shim/diff`（顺带把 `ar`/`ranlib`/`strip`/`nm` 链到 llvm 版，见 [[鸿蒙PC-nmap-autotools交叉编译与真机扫描]] 坑汇总）。一次解决所有子项目（nbase/nsock/libz…）的 header 缺失。
+
+> **更正（2026-06-26，nmap 适配时定位到真因）**：以前以为是 macOS 大小写不敏感 FS 导致 cmp 误判——**错了**，是上面这个坏 diff。
+>
+> 旧对策「**从 config.status 内嵌的 `D["NAME"]="val"` define 表手动生成 config.h**」（脚本 `build/gen-config-h.py`，注意 **反转义** shell 双引号里的 `\"`，否则 `PACKAGE_NAME` 变成 `\"goaccess\"` 编译报 expected expression；生成后 `touch -t` 成最新防 make 重新触发 config.status）**仍可作兜底**，但根因清楚后不需要了。
+
+## 部署
+
+产物是普通 ELF 二进制，strip 后推 `/data/local/tmp/`（data_local_tmp 标签，**exec 无需签名**），`--version` 直接跑。ncursesw 静态链入，NEEDED 仅 libc.so。
+

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-autotools/345/272/223CMake/346/233/277/344/273/243/344/272/244/345/217/211/347/274/226/350/257/221.md

@@ -0,0 +1,59 @@
+---
+name: 鸿蒙PC-autotools库CMake替代交叉编译
+description: autotools 构建的 C/C++ 库在 Windows 宿主（无 MSYS2/autotools）时，可用 CMake 重写构建脚本（或 Python 驱动脚本）替代 autotools 完成鸿蒙交叉编译：手写 CMakeLists 列源文件 + 手写 config.h 宏 + NDK toolchain + 依赖走中心仓 Conan 复用。671/671 编译通过（实证）。手写 config.h 的运行期探测项（AC_CHECK_FUNCS/AC_USE_SYSTEM_EXTENSIONS 产物）必须对 sysroot 实测，纯静态推导会漏项——libbsd 实证漏 _GNU_SOURCE/HAVE_FOPENCOOKIE/HAVE___PROGNAME 三项、4 文件编译失败被误诊为「clang Windows 预处理 bug」。触发词：autotools 替代、CMake 重写、无 MSYS2、config.h 手写、config.h 实测、探测项、HAVE_XXX 走 false、Makefile.am、Linux 宿主无 autotools。
+metadata:
+  type: adaptation
+  source: new/PC（autotools C++ 库实证）+ libbsd 0.12.2（config.h 探测项三重误诊实证，2026-09）
+---
+
+# autotools 库的 CMake 替代交叉编译
+
+来自某消息中间件 C++ 客户端库（autotools 构建）适配。适用于**宿主为 Windows 且无 MSYS2/autotools 环境**的
+autotools 库交叉编译——`.configure --host=...` 走不通（E007/E072）时的一条 bypass 路径。
+
+## 方法（四步）
+
+1. **手写 CMakeLists.txt 替代 Makefile.am**：手动列出所有源文件（数百个源文件全列）。
+2. **手写 config.h 替代 configure 生成**：手工声明 `HAVE_*`、`SIZEOF_*`、`OHOS=1` 等宏（configure 产物
+   的等价物；对照上游 `configure.ac`/`config.h.in` 逐条推导）。**静态推导只够一半**——运行期探测项必须对
+   目标 sysroot 实测（见下节「config.h 探测项实测法」）。
+3. **NDK toolchain**：用 `ohos.toolchain.cmake` 设置交叉编译（`-DCMAKE_TOOLCHAIN_FILE=... -DOHOS_ARCH=arm64-v8a`）。
+4. **依赖走中心仓 Conan 复用**：apr / openssl / cppunit / zlib 已鸿蒙化的依赖直接 `conan` 拉取，
+   不重复自编（见 `pc-registry`）。给库找依赖时加 `CMAKE_FIND_ROOT_PATH_MODE_*=BOTH`（见 [[鸿蒙PC-C++库交叉编译要点]] §8）。
+
+## 结果与适用边界
+
+- 结果：671/671 源文件编译通过，产出主库 `.so`；私有 HNP 执行器通道在零售机 app 域
+  fork+execv 执行成功，2/2 冒烟用例通过。
+- 适用：宿主无 MSYS2/autotools 时。**若宿主有 Linux/MSYS2 环境，优先走正规 autotools 交叉编译**
+  （config.guess/sub 加 HarmonyOS 三元组，见 E007 与 [[鸿蒙PC-CLI调试器-autotools-autosetup交叉编译]]），CMake 重写是
+  维护成本更高的 fallback，只在被迫时用。
+
+## 可复用经验：消息 ID getter 返回空字符串 = musl std::string 差异
+
+消息中间件客户端库的消息 ID getter（CMS 规范 `MessageID` 类）在设备上返回空字符串，属已知 musl C++ `std::string` 构造
+语义与 glibc 分歧（引号位置/构造行为平台差异）。在测试断言里做平台适配，别当库 bug。
+
+## config.h 探测项实测法（libbsd 三重误诊实证）
+
+`configure` 替你做的事里，**只有一部分能靠读 `configure.ac` 静态推导出来**。`AC_CHECK_FUNCS`/`AC_CHECK_HEADERS`
+的运行期探测结果与 `AC_USE_SYSTEM_EXTENSIONS` 产物，取决于**目标 sysroot 的事实**，必须实测：
+
+| 探测项 | 实测法 |
+|---|---|
+| 函数在不在 | `llvm-nm -D --defined-only <sysroot>/usr/lib/libc.so \| grep <符号>`。注意 **glibc 与 musl 符号名可能不同**：glibc 导出 `program_invocation_short_name`，ohos-musl 导出 `__progname`（BSS 符号）——名字不同 ≠ 功能缺失，上游源码通常已有 `#elif defined(HAVE___PROGNAME)` 分支，补 `HAVE___PROGNAME=1` 即可，**无需改源码** |
+| 头文件/类型在不在 | grep sysroot 头文件，**连同守卫宏一起看**：如 `fopencookie`/`cookie_io_functions_t` 在 ohos-musl `stdio.h` 里由 `_GNU_SOURCE` 守卫——特性宏没定义时 `#ifdef HAVE_FOPENCOOKIE` 走 false 是**正确行为**，不是编译器 bug |
+| `AC_USE_SYSTEM_EXTENSIONS` | 一律补 `-D_GNU_SOURCE`（它产出的就是这个，configure 本会自动加） |
+
+**反例（libbsd，2026-09 实证）**：手写 config.h 漏 `_GNU_SOURCE`/`HAVE_FOPENCOOKIE`/`HAVE___PROGNAME`
+三项 → `funopen.c`/`setproctitle.c` 等 4 文件编译跳过 → 被误诊为「clang Windows 版预处理器 bug」烧两轮。
+最小复现证伪 + 补齐三项后同一 Windows 本机全数编通。
+
+**`#ifdef` 走 false 的排查顺序**（先后不可换）：宏拼写（诊断脚本抄错一个字母就造出「已定义不生效」假象）→
+特性宏守卫（头文件里 `_GNU_SOURCE` 等前提）→ 替换式补丁是否真打上（见
+[[鸿蒙PC-宿主无GNU-make的确定性构建驱动]] 的命中断言）→ **最后**才怀疑编译器。
+
+## 相关
+- `pc-error-atlas` E007 / E072 —— autotools config.guess/sub 正规补丁路线。
+- [[鸿蒙PC-CLI调试器-autotools-autosetup交叉编译]] —— autotools 库走正规路线的完整配方。
+- [[鸿蒙PC-私有HNP打包与exec平台差异]] —— 私有 HNP 执行器通道的打包与 exec 差异。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-autotools/345/272/223Windows/345/256/277/344/270/273/346/240/221/345/206/205/346/236/204/345/273/272/344/270/216/347/233/264/351/223/276/344/272/244/345/217/211/347/274/226/350/257/221.md

@@ -0,0 +1,116 @@
+---
+name: 鸿蒙PC-autotools库Windows宿主树内构建与直链交叉编译
+description: Windows 宿主（无 MSYS2/WSL）上 autotools C 库/CLI 交叉编译到鸿蒙 aarch64 的**不重写**路线——release tarball 的 configure 已预生成，Git Bash 树内 configure+make 用原生 make 即可编完全部对象，唯二死点各一步绕行（树外构建的 MSYS 路径问题→回树内；libtool 最终链接挂→clang 直链）。同机同晚对照实证：libunistring 树内 595 对象全编通 built-and-verified，libidn2 树外 make 秒死误判「宿主编不出」停 partial。触发词：树内构建、in-tree、out-of-tree、树外构建、No rule to make target Makefile.am、mingw32-make、MSYS 路径、libtool link、cp: cannot stat、直链、绕过 libtool、clang -shared、soname 手工符号链、手工 install、CLI 二进制直链、gengetopt、tarball configure 预生成、无 MSYS2、Windows autotools、宿主工具链不可用。
+metadata:
+  type: adaptation
+  source: libunistring 1.4.2 + libidn2 2.3.8 同机同晚对照实证（2026-09：树内直链端到端 built-and-verified / 树外误判停 partial）
+---
+
+# autotools 库的 Windows 宿主树内构建与直链交叉编译
+
+> **一句话**：Windows 宿主**不需要** MSYS2/WSL 也能跑 autotools 交叉编译——release tarball 的
+> `configure` 是自包含 POSIX 脚本，Git Bash 树内直跑；`make` 用**原生** make（mingw32-make 亦可）
+> 能编完全部对象；唯二死点各有一步绕行（见分流判据）。「Windows 编不了 autotools」是误判，
+> 真凶是树外构建或 libtool 链接，两者都可绕。
+
+## 分流判据（先判这个，再动手）
+
+| 判据 | 走哪条路 |
+|---|---|
+| **源码形态**：release tarball（`configure`/`Makefile.in`/`gl/` 已预生成） | **本文档**（树内 + 直链），不需要 MSYS2 |
+| **源码形态**：git checkout（需 `autoreconf` 现生成 configure） | MSYS2 preflight（[[鸿蒙PC-Windows宿主构建环境四坑]] 坑 7） |
+| **失败阶段**：`./configure` 本身跑不通（E007/E072） | config.guess/sub 补丁路线（E007）或 CMake 重写（[[鸿蒙PC-autotools库CMake替代交叉编译]]） |
+| **失败阶段**：`make` 报 `No rule to make target '...Makefile.am'` | **你在树外构建**——回树内重跑（死法 ①） |
+| **失败阶段**：`make` 编完全部对象、最后 libtool 链接挂 | 正常现象——clang 直链绕过（死法 ②） |
+| **宿主连 make 都没有**（纯 makefile 工程） | [[鸿蒙PC-宿主无GNU-make的确定性构建驱动]]（Python 驱动复现编译语义） |
+
+## 两种死法（各一步绕行）
+
+### 死法 ①：树外构建 + MSYS 路径（秒死）
+
+`mkdir build && cd build && ../configure` 会把 MSYS 绝对路径（`/d/...`）写进 Makefile 的
+srcdir/VPATH，Windows 原生 make 解析不了 → 立即报
+`No rule to make target '/d/.../Makefile.am', needed by '/d/.../Makefile.in'`。
+**configure 成功不代表 build dir 可用**——libidn2 实证：configure 过、make 一步未编，
+据此误判「宿主无 autotools 工具链、不可解」写进 remaining_blockers（12 天前同机树内构建
+成功过，只因配方零留痕无从复现）。
+
+**绕行：永远树内构建**——cd 进 tarball 解压目录跑 configure，Makefile 全相对路径，
+原生 make 照常工作。nmap 案例「仅 in-tree 构建」同款结论。
+
+### 死法 ②：libtool 最终链接在 Windows 挂（编完才死）
+
+树内 `make -j` 能编完全部 `.lo/.o`（libunistring 实证 595 个全过），但最后的 libtool
+链接步骤在 `.libs/` 内做 cp/ln 时路径处理失败（`cp: cannot stat 'libX.so.N.M.P'`）。
+
+**绕行：make 只用来编译，链接绕过 libtool 直链**（配方第 3 步）。
+
+## 配方（七步，端到端实证）
+
+0) **编译器 wrapper**（一次封装 target/sysroot，顺带避开 NDK 路径带空格的引号问题，见 E137）：
+
+   ```bash
+   #!/bin/bash
+   # build/ohos-clang.sh
+   NDK="$DEVECO_SDK_HOME/default/openharmony/native"
+   exec "$NDK/llvm/bin/clang" --target=aarch64-linux-ohos --sysroot="$NDK/sysroot" "$@"
+   ```
+
+   `AR/RANLIB/NM/STRIP` 用 `$NDK/llvm/bin/llvm-*`；`config.guess` 不识别 OHOS 时 patch 加
+   `__OHOS__` 分支，或 configure 显式 `--host` 即可跳过 host 侧探测。
+
+1) **树内 configure**（cd 进 tarball 解压目录，**不要** mkdir 树外 build 目录）：
+
+   ```bash
+   ./configure --host=aarch64-unknown-linux-ohos --build=x86_64-w64-mingw32 \
+     --prefix=<workspace>/dist/lib --enable-shared --enable-static --disable-doc --disable-nls \
+     CC=<workspace>/build/ohos-clang.sh CXX=<workspace>/build/ohos-clang++.sh \
+     AR="$DEVECO_SDK_HOME/default/openharmony/native/llvm/bin/llvm-ar" \
+     CFLAGS='-O2 -fPIC -g0' LDFLAGS='-Wl,--code-sign -Wl,-z,max-page-size=0x1000'
+   ```
+
+   依赖库（同轨复用制品）用 `--with-<dep>-prefix=<登记制品的 stage/usr 目录>`；Windows 无
+   pkg-config 时直接往 CFLAGS/LDFLAGS 注 `-I/-L`（meson 场景的模拟器方案见四坑坑 5）。
+
+2) **make 编译**：`make -j4 V=1`——预期编完全部对象，死点只在最终链接（死法 ②）。
+
+3) **直链 .so（绕过 libtool）**：
+
+   ```bash
+   cd lib && <ohos-clang.sh> -shared -Wl,--no-undefined -Wl,--code-sign \
+     -Wl,-z,max-page-size=0x1000 -Wl,-soname,libX.so.N \
+     -o .libs/libX.so.N.M.P <lib/.libs 下全部 .o> -lc
+   ```
+
+   版本号/soname 从 Makefile.am 的 `-version-info current:revision:age` 换算（N.M.P）。
+
+4) **手工 install**（替代 `make install`）：soname 符号链（`.so.N → .so.N.M.P`、`.so → .so.N`）
+   + 公共头文件 + `.pc` 拷进 `dist/`；`.la` 可手写最小版（下游主要消费 `.pc/.so/.h`）。
+
+5) **CLI/可执行目标**（如有 `src/*.c` 的 main）：同模式——make 已把 `src/*.o` 编好，
+   `<ohos-clang.sh> <src/.libs 下 .o> <libX.a 或 -lX> -o dist/bin/<tool>` 直链（gnulib
+   libgnu 对象静态链入；gengetopt 产物随 tarball 预生成）。libidn2 的 `idn2` CLI 即此路
+   产物（aarch64 musl PIE），与测试 ELF 同构、经 cli-hnp-runner 真机可跑。
+
+6) **测试直编**（上游 `tests/*.c` 不走 Makefile）：NDK clang 逐个直编，`-include config-ohos.h
+   -DHAVE_CONFIG_H` + 手写最小宏垫片补 gnulib 未生成头（`_GL_ATTRIBUTE_*` 等属性宏约 20 行）
+   + `-I <dist 头文件> -L <dist 库> -lX -l<dep>` 链接制品。
+
+7) **设备双载体验证**（库形态两载体缺一不可）：HAP 载体 dlopen（soname 别名按 E131）+
+   `cli-hnp-runner` 私有 HNP 执行器 fork+execv 真跑测试 ELF，`hilog -x -P <pid>` 取 TAP/RAW。
+   大数据文件（Unicode 测试向量等）随 HNP 部署、运行时路径 filesDir 重建。
+
+## 反例锚点（同机同晚对照，2026-09）
+
+- **libunistring（对）**：树内构建 → make 595 对象全编通 → libtool 链接挂 → 直链绕过 →
+  手工 install → 双载体真机全过 → `built-and-verified`。
+- **libidn2（错）**：树外构建（obj-<lib>/ 目录）→ make 秒死（死法 ①）→ 误判「宿主工具链
+  不可用」→ 停 partial。**错在树外，不在 Windows。**
+
+## 相关
+
+- [[鸿蒙PC-autotools库CMake替代交叉编译]] —— configure 跑不通时的**重写路线**（维护成本更高，按分流判据二选一）
+- [[鸿蒙PC-Windows宿主构建环境四坑]] —— 宿主侧环境坑（ld.lld 并行崩溃 / hvigorw / 路径非法字符 / pkg-config 模拟器）；其坑 7 的 MSYS2 preflight 只适用于 git 源码
+- [[鸿蒙PC-宿主无GNU-make的确定性构建驱动]] —— 宿主连 make 都没有时的 Python 驱动路线
+- [[鸿蒙PC-CLI调试器-autotools-autosetup交叉编译]] —— autotools 正规路线完整配方（Linux/MSYS2 宿主）
+- `pc-error-atlas` E131（HAP 打包 soname 别名缺失）/ E137（NDK 封装脚本空格路径断裂）

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-cmd-pkgs/351/242/204/347/274/226/350/257/221GTK/346/240/210/344/270/215/345/217/257/347/224/250.md

@@ -0,0 +1,50 @@
+---
+name: 鸿蒙PC-cmd-pkgs预编译GTK栈不可用
+description: cmd-pkgs 的预编译 GTK3/glib 栈是坏的（glib 静态烤进每个库→GObject 类型系统冲突），要 GTK 必须从源码自编
+metadata:
+  type: adaptation
+  source: new/PC
+---
+
+2026-06-26 验证 nmap 的 GTK GUI（broadway 路线）时，花大力气确认：**[gitcode OpenHarmonyPCDeveloper/cmd-pkgs](https://gitcode.com/OpenHarmonyPCDeveloper/cmd-pkgs) 的预编译 GTK3 栈无法实际跑起 GTK 应用**。下次想用它做鸿蒙 GTK GUI，别走这条死路——直接从源码交叉编译 glib+GTK。
+
+## 致命问题：glib 被静态烤进每个 GTK 库
+- cmd-pkgs `glib-2.88.0` 包 **只 ship 静态 `libglib-2.0.a`（+ gdb 脚本引用一个并未包含的 `libglib-2.0.so.0.8800.0`）**，没有共享 glib/gobject/gio/gmodule。
+- 结果：`libgtk-3.so`/`libpango-1.0.so`/`libgdk_pixbuf-2.0.so`/`libgdk-3.so` **各自把 glib/gobject 静态链进去并导出**（`llvm-nm -D libgtk-3.so | grep g_object_new` → 8 个；它们的 DT_NEEDED 里**没有** libglib）。
+- 一个进程里同时加载这些库 → **多份互不相容的 GObject 类型系统**：
+  - 无共享 glib：`g_type_register_static: assertion failed (static_quark_type_flags)`（类型系统没初始化）。
+  - 补了共享 glib + LD_PRELOAD：`cannot register existing type 'gchar'` / `_g_value_types_init: assertion (type == G_TYPE_CHAR)`（双重注册）。
+- 库内部对 glib 的调用是**本地绑定、不可 interpose**，所以 **加共享 glib / LD_PRELOAD / 符号合并都救不了**。库本身就是错构建的。
+
+## 还有一堆次级坑（即便上面能绕过也会一个个踩）
+- **坏/空 tarball**：`fontconfig-2.16.0`、`fribidi-1.0.16` 下下来是空的/截断的（`fribidi-1.0.13` 才有 `.so`）。
+- **libpng 只有静态且非 PIC**（`liblibpng16_static.a`），做不出共享 `libpng16.so.16`（要自己从 libpng 源码编，记得带 `arm/*neon*` 否则缺 `png_*_neon` 符号；用 `scripts/pnglibconf.h.prebuilt`）。
+- **cairo 包是 libs-only**（无头文件、无 `libcairo-gobject.so`；后者要自己从 cairo `util/cairo-gobject/{enums,structs}.c` 编，加空 `config.h`）。
+- **baked 绝对前缀路径**：库的 DT_NEEDED/RUNPATH 硬编码 `/storage/Users/currentUser/usr/local/lib`（cmd-pkgs 安装前缀 = 设备用户 `$HOME/usr/local`），从 `/data/local/tmp` 跑要把那个路径 symlink 过去。
+- **缺 SONAME 符号链接**：`hdc file send` 不传符号链接，要在设备上按 `DT_SONAME` 现补 `lib*.so.N` 链。
+- **libz 不在包里**：从设备 `/system/usr/lib/libz.so.1.2.13` 拉。
+
+## 平台正交收获（这些是真的，可复用）
+- **broadway 后端确实是对的方向**：预编译 GTK 是用 **broadway 后端**编的（`libgdk-3` 只有 `gdk_broadway_*`，**无 X11/wayland 依赖**），含现成 `broadwayd`。GTK→浏览器→鸿蒙 ArkWeb(WebView) 这条路架构成立；坏的只是这套预编译产物本身。
+- **XPM exec 限制**：cmd-pkgs 的预编译 ELF（如 `broadwayd`）从 `/data/local/tmp` 直接 exec 被 XPM 拒 `Operation not permitted`（自己用 NDK 编的二进制反而能直接 exec）。**绕法：`/lib/ld-musl-aarch64.so.1 ./broadwayd args`**（把二进制当数据喂给动态加载器，绕过 exec 检查）。见 [[鸿蒙PC-app域执行二进制与JIT限制]]。
+- **静态 .a 是 PIC 时可合成共享库**：`clang -shared -Wl,--whole-archive lib.a -Wl,--no-whole-archive ...`（glib 的 .a 是 PIC，能合成；libpng 的不是）。
+- glib 的 `g_libintl_*` 符号若缺，是 gettext 的薄封装，7 个函数 shim 一下转发到 `bindtextdomain/gettext/...` 即可。
+
+## 结论 / 下一步
+要在鸿蒙 PC 上跑 GTK（broadway 或自写 gdk-ohos 后端），**必须从源码 meson 交叉编译 glib + GTK**（glib 作为正常共享依赖），不能用 cmd-pkgs 预编译。两条 GUI 路线都以"从源码编 GTK 栈"为前提；既然都要自编，**编 GTK 时直接开 broadway 后端**（meson `-Dbroadway-backend=true`，GTK 原生支持）比再写 gdk-ohos 后端省得多。XComponent CPU-blit 那道缝已验证可行（见 [[鸿蒙PC-XComponent-CPU像素渲染与输入缝]]），留作 gdk-ohos 后端的退路。
+
+## ✅ 从源码 meson 交叉编译可行（glib 2.80.5 已成功，是可复用配方）
+- **meson cross-file 要点**：`[binaries] c = aarch64-unknown-linux-ohos-clang`（cpp/ar/strip/ranlib 同理，`pkg-config = /opt/homebrew/bin/pkg-config`）；`[host_machine] system='linux' cpu_family='aarch64' cpu='aarch64' endian='little'`（meson 不认 'ohos'，用 'linux'，OHOS clang 自带 `__linux__`）；`[properties] pkg_config_libdir = <prefix>/lib/pkgconfig`、`sys_root=<ndk>/sysroot`；`c_args/c_link_args` 带 `-I<prefix>/include` `-L<prefix>/lib`。
+- **glib 配方**：`meson setup _build --cross-file ohos-cross.ini --prefix=<prefix> --buildtype=release -Dtests=false -Dintrospection=disabled -Dman-pages=disabled -Dselinux=disabled -Dlibmount=disabled` → `meson compile` → `meson install`。696 目标全过、零源码改动。
+  - 坑：①别给 prefix 放半残的外部 libintl（cmd-pkgs 的 libintl 缺 `ngettext` → glib `assert libintl.type_name()=='internal'` 失败）——删掉让 glib 用内置 libintl proxy。②libffi 被 glib 当 subproject 自动编（无需外部）；若 prefix 预放了 `libffi.so` 非符号链接，install 阶段会 `already exists and is not a symlink` 报错（不影响 glib 本体已装，忽略或先删）。③introspection 交叉编译难（要跑目标二进制 dump 类型），先 disabled；**但 Zenmap/PyGObject 必须 typelib**，Phase 5 再专门解（gobject-introspection 交叉是已知硬骨头）。
+- **复用 vs 自编划分**：不链 glib 的 dep（freetype/fontconfig/pixman/libffi/pcre2/fribidi/libepoxy/libjpeg + 自编 libpng + 设备 libz）可复用预编译，把 `.pc` 的 `prefix=` sed 成新 prefix 即可；**链 glib 的（cairo-gobject/pango/gdk-pixbuf/atk/gtk）必须自编**，否则又把 glib 烤进去重蹈覆辙。
+
+## ⚠️ 但"复用预编译 dep"基本行不通——它们大多 64KB 页对齐会崩
+实际推进时发现：cmd-pkgs 的 pixman/fontconfig/fribidi/libepoxy/libffi(bare) 全是 **64KB 页对齐**，在 4KB 页设备上 dlopen 直接 SIGSEGV（见 [[鸿蒙PC-64KB页对齐so崩溃]]）。加上 pcre2 是坏的、expat 无 SONAME……**最后几乎整栈都从源码重编了**（带 `-Wl,-z,max-page-size=0x1000`）。结论强化：**鸿蒙 PC 跑 GTK，老老实实从源码编整栈**，cmd-pkgs 预编译只能拿来抄抄版本号。
+
+## ✅ 整套 GTK3 栈已从源码交叉编译成功并真机加载运行（2026-06-26）
+编译顺序与版本：
+`glib-2.84.4`（≥GTK3.24.52 需要 2.84 API `g_variant_builder_init_static`）→ `freetype-2.13.3` → `libpng-1.6.43`(直接 clang 编,带 arm/*neon*) → `pcre2-10.44`(直接 clang 编) → `harfbuzz-8.5.0` → `pixman-0.42.2`(`-Da64-neon=disabled -Darm-simd=disabled`,ARM 汇编 OHOS clang 编不过) → `cairo-1.18.2` → `pango-1.50.14` → `gdk-pixbuf-2.42.12`(`-Djpeg=disabled`,只 png) → `atk-2.38.0` → `fribidi-1.0.13` → `libepoxy-1.5.10` → `fontconfig-2.14.2` → `expat-2.6.2`(直接 clang 编) → **`gtk-3.24.52`**（`-Dx11_backend=false -Dwayland_backend=false -Dbroadway_backend=true -Dintrospection=false`）。
+- **结构正确**：`libgtk-3` 正常 `NEEDED libglib-2.0.so.0`、导出 0 个 g_object_new（不再静态烤）。含自带 `broadwayd`。
+- **真机**：整栈 dlopen 成功；`broadwayd :2` 起来监听 unix socket + TCP 8082(HTTP/WS)；GTK app(GDK_BACKEND=broadway) 连上 broadwayd 跑起来（需 `FONTCONFIG_FILE` 指向含 `<dir>/system/fonts</dir>` 的 fonts.conf，否则字体加载失败；需先 `rm /dev/shm/bdw-*` 清残留 shm）。
+- **剩**：broadway 要浏览器(ArkWeb WebView 连 localhost:8082) 提供 monitor 几何才出画面（无浏览器时 "infinite surface size" 警告，app 仍存活）——HAP 里用 Web 组件加载 `http://127.0.0.1:8082` 即整合完成。Mac 端经 hdc fport 的浏览器 WS 连不通（测试侧限制，非设备问题）。

package/node_modules/@ohos-agent/pc-adapter/skills/pc-knowledge-base/adaptation//351/270/277/350/222/231PC-cpp-lib/345/217/214/350/275/275/344/275/223/351/252/214/350/257/201OHPTCASE/345/215/217/350/256/256/351/205/215/346/226/271.md

@@ -0,0 +1,99 @@
+---
+name: 鸿蒙PC-cpp-lib双载体验证OHPTCASE协议配方
+description: 纯 C/C++ 库（cpp-lib 交付形态）的鸿蒙 PC 真机验证双载体配方：hap 载体（cpp-lib-demo NAPI 壳 dlopen 库符号，冒烟核心链路）与 cli 载体（私有 HNP + 测试 ELF 编译期自签 + fork+execv 逐条直跑，OHPTCASE 协议上报，hilog 整条取证）。取证前必须 hilog -b D + aa force-stop 冷启动。触发词：cpp-lib 双载体、cpp-lib-demo、cli-hnp-runner、OHPTCASE、fork+execv、链接期自签、--code-sign、4KB 页对齐、ELF 自签、私有 HNP、测试 ELF、CMocka、ctest、执行器 HAP、测试 ELF 部署、逐条直跑、上游测试套件、elf-verify、compile_napi_stub.cmd、handmade so 漏 libc++_shared。
+metadata:
+  type: adaptation
+  source: libcbor 0.14.0（纯 C99 编解码库，双载体全量验证实证）
+  relates_to: E150, E157
+  supersedes: []
+---
+
+# 鸿蒙 PC：cpp-lib 双载体验证——OHPTCASE 协议配方
+
+> 纯 C/C++ 库（`cpp-lib`）的设备验证需要两股载体互补：
+> - **hap 载体**（`cpp-lib-demo`）：证明库可以被动态加载、符号可解析、核心 API 调用无崩溃；
+> - **cli 载体**（`cli-hnp-runner`）：跑全量上游测试用例，供给逐条 pass/fail 的机器证据。
+>
+> 两载体缺一不可——单跑 hap 无法穷举 API 族边界，单跑 CLI 无法证明 dlopen 加载链路。
+
+## 一、载体分工
+
+| 载体 | scaffold kind | 测什么 | 证据形态 |
+|---|---|---|---|
+| **hap（NAPI dlopen）** | `cpp-lib-demo` | 库的加载链路（`dlopen` 返回值、符号地址非空、核心 API 可调用）、二进制兼容性 | `demo-verify.json`（GL 身份 + hilog 片段 + 截图） |
+| **cli（私有 HNP exec）** | `cli-hnp-runner` | 全量上游测试（CMocka/ctest 的测试 ELF），逐条 assert 判定点 | `OHPTCASE result=…` 协议行 → hilog → `device-raw.log` |
+
+## 二、hap 载体：cpp-lib-demo
+
+由 `ohpt-agent scaffold --kind cpp-lib-demo` 生成，自动纳入阶段 6 的 `cases.json` 用例接线骨架。
+
+- NAPI 壳：`napi_stub.cpp` 中 `kCases[]` 表注册每条用例 → native 侧 `runCase` 调用库符号 → `OHPT_CHECK` 判定点输出；
+- 编译：hvigor CMake 编入 HAP 的 `libs/arm64-v8a/`；
+- 验证：`ohpt-agent sign-demo --install` → `ohpt-agent verify-demo --cases <cases.json>` 一次拉起跑全部用例（`run_all.supported=true`）。
+
+**注意**：手编 .so（不走 hvigor CMake）会漏 `libc++_shared.so` → MUSL-LDSO 加载失败 → "export objects of native so is undefined" → 全部用例「调用失败: {}」+ 零 OHPTCASE 行（见 `pc-error-atlas` E157）。
+
+## 三、cli 载体：cli-hnp-runner
+
+由 `ohpt-agent scaffold --kind cli-hnp-runner` 生成，产出：
+- 交叉编译的测试 ELF（如 CMocka/ctest 的测试二进制），**编译期做 --code-sign 自签 + 4KB 页对齐**；
+- 私有 HNP（zip 包），内装测试 ELF 与运行时 .so（`libc++_shared.so`、被测库 .so）；
+- 执行器 HAP，在 app 域 `fork+execv` 逐条直跑测试 ELF。
+
+验证流：
+1. 测试 ELF 链接期注入 `--code-sign=1`（`elf-verify` 开关），否则 app 域 SELinux 拦 exec；
+2. 私有 HNP 打包（`hnpPackages`）：`strip` 后 zip 进 `libs/arm64-v8a/`，首段路径名=包名，安装器剥离首段路径（9568407 号定位）；
+3. 执行器 `execv(<HNP数据目录>/<test-elf>)`，子进程 `setenv("TMPDIR"/"TEMP"/"HOME")` 指向沙箱可写目录；
+4. 测试 ELF 内嵌 `OHPTCASE` 协议：每条用例输出 `OHPTCASE check id=… cp=… ok=… expect=… actual=…`，套件结束时输出 `OHPTCASE summary total=N pass=M fail=K pending=0`；
+5. 宿主轮询 hilog 至 summary 行出现即收证，逐行解析结果。
+
+**关键约束**：
+- 测试 ELF 须是**静态链接**或自带全运行时（app 域容器只提供基础 musl + libc++_shared）；  
+- 若测试框架用 `tmpfile()`/`P_tmpdir`：musl 硬编码 `/data/local/tmp`（EACCES），需设 `TEMP=<沙箱可写目录>`（详见 `platform/鸿蒙PC-应用沙箱临时目录语义…`）；  
+- 若测试框架 `fork()` 后等待子进程：需检查子进程是否能正常 exec（SELinux `avc: denied { execute }` → 需自签 ELF）。  
+
+## 四、取证协议：OHPTCASE
+
+两载体共用 OHPTCASE 协议做判定：
+
+```
+OHPTCASE: check id=F-01-01 cp=0 ok=0 expect=expectation actual=observed_value
+OHPTCASE: result=pass id=F-01-01 detail=<optional>
+OHPTCASE: summary total=27 pass=27 fail=0 pending=0
+```
+
+- `check` 行：单条检查点（OHPT_CHECK 宏），`ok=1` 通过，`ok=0` 失败，`expect`/`actual` 留存证据；
+- `result` 行：单条用例终态（pass/fail/blocked）；
+- `summary` 行：全部用例统计——**取证截止行**（verify-demo 轮询到此即收网）。
+
+## 五、取证前置
+
+`pc-device-verify` skill 规约，任意载体取证前必须：
+
+```bash
+hilog -b D                     # 提日志级别（否则 INFO 在写入时即被丢）
+aa force-stop <bundle-name>    # 冷启动（消灭上一次的 stale 日志）
+```
+
+`ohpt-agent verify-demo` 已内置此流程。若 hilog 空，先排查级别。
+
+## 验证矩确认
+
+| 步 | 检查项 | 工具/方法 |
+|---|---|---|
+| ① | ELF 是否自签 | `readelf -S <test-elf> \| grep -i code_sign` |
+| ② | HNP zip 布局是否符合契约 | `unzip -l <hnp.zip>` → 首段 = pkg 名 |
+| ③ | hilog 级别 | `hilog -b D` 补打 |
+| ④ | OHPTCASE 行出现 | `hdc shell "hilog \| grep OHPTCASE"` |
+| ⑤ | tmpdir 环境变量 | `execv` 前 `setenv("TEMP", cwd, 1)` |
+| ⑥ | host_runtime 明确 | manifest.json 中值为 `hap-dlopen`（cpp-lib 的固定值） |
+
+## 相关
+
+- [鸿蒙PC-C库设备验证测试设计.md](./鸿蒙PC-C库设备验证测试设计.md) — 上游测试套件优先原则 + 边界用例模板库
+- [鸿蒙PC-应用沙箱临时目录语义与libcheck-TEMP选址.md](../platform/鸿蒙PC-应用沙箱临时目录语义与libcheck-TEMP选址.md) — tmpfile 路径不可写排查
+- [鸿蒙PC-私有HNP打包与exec平台差异.md](../platform/鸿蒙PC-私有HNP打包与exec平台差异.md) — HNP 布局契约与 app 域 exec 限制
+- [鸿蒙PC-真机跑官方测试套件.md](../platform/鸿蒙PC-真机跑官方测试套件.md) — 测试套件移植总流程
+- `pc-device-verify/SKILL.md` — 设备验证完整操作节
+- `pc-test-design/references/demo-wiring-pc.md` — 用例接线与 OHPTCASE 协议完整规格
+- `pc-error-atlas` E157 — 手编 .so 漏 libc++_shared 导致零 OHPTCASE 行