Skip to content

Latest commit

 

History

History
229 lines (180 loc) · 15.4 KB

DEVELOPMENT.md

File metadata and controls

229 lines (180 loc) · 15.4 KB

开发、测试与发布

本文于 2026-11-12 对照当前工作区脚本核对,主程序与驱动管理器项目版本为 1.8.5-pre5(源码基线 1eb833a)。 以下命令均从仓库根目录运行。模块关系见架构说明,文档入口见索引。

环境与依赖

工具 要求与用途
系统 Windows 10/11 x64;WPF 运行时测试需要交互桌面;虚拟摄像头运行需要 Windows 11
Visual Studio C++ Build Tools MSVC、Windows SDK、CMake;默认 CMake preset 指向 Visual Studio 18 2026,build.ps1 会查找已安装的工具链
CMake 项目最低 3.25;优先使用 Visual Studio 随附版本
.NET global.json 指定 10.0.301,允许 latestFeature 向前滚动,不启用预发布 SDK
Python 桥接配方和 CI 使用 Python 3.13 x64,构建时创建隔离虚拟环境
MSYS2 UCRT64 默认构建 UxPlay 可选组件和定制 FFmpeg;需要 CMake、Ninja、toolchain、pkgconf、GStreamer base/good/bad/libav、libplist、OpenSSL 及编解码依赖;完整包名见 Windows workflow
网络 首次还原 NuGet/Python 包以及准备 FFmpeg、VC Runtime、UxPlay、Inno Setup 等依赖时需要网络

Apple USB 支持和实机信任是运行有线功能的条件,不是离线协议单元测试的条件。 标准 ZIP 和 Setup 内置固定版本的 Personalized 与 Cryptex DDI;构建时下载并按 config/ddi-bundles.json 校验,打包缺失或损坏时失败。Apple 个性化签名的网络需求见桥接使用说明。

仓库结构

路径 职责
src/App WPF 主程序、设备会话、输入路由、媒体输出及更新器
src/Core C++20 C ABI、USB/QuickTime、解码、D3D11、WASAPI 与无线 IPC
src/WirelessHost / src/UxPlayHost 原始 AirPlay/DLNA 宿主、UxPlay 备用适配进程
src/VirtualCamera Windows 11 Media Foundation 媒体源、帧交换及注册助手
src/DriverInstaller 独立驱动管理器与提权操作入口
src/Shared / src/SharedUI 共享下载/提权安全逻辑、主题、控件、窗口行为
tools/usb_touch_bridge.py / tools/iostouch 当前 Python 反控桥及 QuickTime 配置下的 USBMux 共存支持
src/App/Automation / docs/api 本地 HTTP Automation API、接入说明及 Python/curl 示例
scripts / installer / .github/workflows 构建依赖、验证、打包、安装器与 CI
src/*.Tests / tests 托管、Python 及专项恢复测试;原生测试在各模块的 tests 下
docs / updates 文档与版本说明、应用备用更新清单
build / dist / outputs / work 构建目录、桥接载荷、发布产物和临时依赖;不是唯一源码来源

本地主线与交付约定

本机持续开发使用 C:/Users/Ray/Documents/iphoneMirror 的 main,开始前检查状态、近期提交并获取远端更新,保留未提交修改;未经明确要求不另建分支或 worktree。 work/main-consolidation 仅为历史恢复备份,不是开发或交付来源。

当前主线交付目录为 outputs/iPhoneMirror-main。下方 build.ps1 的默认输出仍是 outputs/iPhoneMirror,脚本没有自动改用主线交付目录;构建后将验证过的完整载荷整理到主线交付目录。 更新交付前检查程序是否运行,不覆盖运行中的程序;停止或更新运行实例需有相应任务授权。 -TestBuild 会清理整个 outputs,也可能影响主线交付和历史验证产物,不应作为保留现有交付的日常构建方式。

常用构建

# 默认 Release:构建、测试,并发布自包含应用
./build.ps1 -Configuration Release

# 调试构建和测试,不生成自包含发布目录
./build.ps1 -Configuration Debug -NoPublish

-NoPublish 仍会构建桥接器并准备原生依赖,不是只编译 C# 的快捷入口。 常规 Release 产物为 outputs/iPhoneMirror;安装器载荷为 outputs/iPhoneMirror.Installer,主程序使用外置 .NET 运行时,驱动管理器独立自包含, 安装器通过统一压缩减少重复数据。 二者都包含独立桥接器的完整 onedir 载荷。

参数 行为与限制
-SkipTests 跳过 build.ps1 的测试段;不能据此报告测试通过
-OmitUxPlayRuntime 缺少 MSYS2 时可生成省略 UxPlay 的测试包;原始无线接收端仍保留
-IncludeUxPlayRuntime 将默认独立下载的 UxPlay 组件也内置,适合离线包
-OmitMediaOutputRuntime 省略内置 FFmpeg;应用仍校验候选 FFmpeg 的固定 SHA-256,任意系统 FFmpeg 不能替代
-Version 显式覆盖此次构建的产品版本;常规构建默认取项目版本
-TestBuild 根据源码、版本记录及已有输出递增 -testN,重新整理 outputs 并将测试版发布到其根目录;使用前保存需要保留的产物;不能与 -NoPublish 或 -Version 同用

桥接器构建来源

默认使用仓库内 scripts/usb-bridge-recipe,将当前 tools/usb_touch_bridge.py 和 tools/iostouch 暂存后打包。不会自动克隆上游最新分支。配方来源及固定提交见 SOURCE.md,直接依赖版本见 requirements.txt。

IPHONE_MIRROR_USB_BRIDGE_ROOT 覆盖的是构建配方目录;它必须兼容当前 Python 源码。 上游新 Rust 后端采用不同运行时 schema,不能直接替换。应用当前要求运行时清单 schema 1,而 ready 的应用协议号为 2,二者含义不同。

必须一起保留 iUsbBridge.exe、iUsbBridge.runtime.json 和 _internal;只复制 EXE 会 破坏运行时。构建环境位于 work/usb-touch-bridge-python,打包产物位于 dist。

测试入口与覆盖范围

默认构建依次运行 CTest、Python unittest、桥接源码暂存与三个提权启动脚本、三个托管测试程序、 Automation 生命周期专项、VC Runtime 版本解析和 Apple 支持包验证。CI=true 时,脚本明确跳过 App.Runtime.Tests;它并非自动检测所有无桌面环境。本地运行 WPF 测试会创建窗口。 本地化校验由 Windows workflow 单独执行,不包含在 build.ps1 的测试段中。

本地构建还分别在新进程中运行主程序和驱动管理器的 --grid-layout-entry 探针, 验证各自的应用入口在首次 Grid 布局前启用兼容算法。两者不能在同一进程中合并验证, 因为 WPF 会缓存兼容开关。默认运行时套件同时覆盖 2,784 组 Grid 边界及混合布局; 也可单独执行 App.Runtime.Tests --grid-layout-compatibility。故障证据见 启动布局闪退分析。

build.ps1 先编译托管测试,再直接执行测试程序集,并仅为测试子进程清除 SDK/CI 注入的 CLR/.NET 环境覆盖。dotnet run 会注入 DOTNET_ROOT_X64, 触发更新器和驱动的提权环境保护;单独运行涉及提权的测试时,应使用干净环境下的 dotnet <测试程序集.dll>。应用的安全检查和拒绝注入的回归测试保持启用。

若 ctest 不在 PATH 中,使用 Visual Studio 随附 ctest.exe 的绝对路径运行相同参数; build.ps1 会自动定位它,单独输入 ctest 的终端则需要正确的工具路径。

./scripts/verify_localization.ps1

# 先完成一次同配置构建,确保原生 DLL 与测试程序匹配
ctest --test-dir build/native -C Release --output-on-failure
# 在未设置 CLR/.NET 注入变量的终端中执行;完整构建会自动净化测试子进程环境
dotnet ./src/App.Logic.Tests/bin/Release/net10.0-windows10.0.19041.0/IPhoneMirror.App.Logic.Tests.dll
dotnet ./src/App.Runtime.Tests/bin/Release/net10.0-windows10.0.19041.0/win-x64/IPhoneMirror.App.Runtime.Tests.dll
dotnet ./src/DriverInstaller.Tests/bin/Release/net10.0-windows10.0.19041.0/iPhoneMirror.DriverInstaller.Tests.dll

# 使用构建创建的 Python 环境,避免缺少桥接依赖
$env:PATH = (Join-Path $PWD 'third_party/libusb/bin/x64') + ';' + $env:PATH
& ./work/usb-touch-bridge-python/Scripts/python.exe -m pip install -r tests/requirements.txt
& ./work/usb-touch-bridge-python/Scripts/python.exe -m unittest discover -s tests -p '*test.py'

完整构建会在运行 Python 测试前安装 测试依赖,包含手机边框验证使用的 Pillow、NumPy 和 SciPy;这些依赖不属于 HID 桥接运行时。

静态预览回归使用合成 NV12 帧,不连接手机或启动无线接收器:

# 需要可访问的交互桌面;验证静态画面、重绘、缩放、隐藏恢复和故障重试
./build/native/src/Core/Release/iPhoneMirror.Core.Tests.exe --preview-static-frame-only

# DXGI 可呈现但桌面像素不可读取时,仅验证 Present 和重试;不验证显示
./build/native/src/Core/Release/iPhoneMirror.Core.Tests.exe --preview-static-frame-retry-only

# 验证同一 HWND 的公开预览接管、并发停止/销毁、构造失败回滚及核心重启
./build/native/src/Core/Release/iPhoneMirror.Core.Tests.exe --preview-ownership-only

# 验证旧预览释放后立即创建新翻转模型交换链
./build/native/src/Core/Release/iPhoneMirror.Core.Tests.exe --preview-handoff-only

测试为每个预览单独注入呈现繁忙、窗口遮挡和上传失败,始终保持同一帧时间戳。 故障注入仅编入原生测试程序,不进入发布用 Core DLL。 若运行环境使窗口始终处于 DXGI_STATUS_OCCLUDED,两种模式都需要改在可呈现的 交互桌面运行;重试模式不会把被遮挡状态当作成功。

测试 主要覆盖
CTest QuickTime/CoreMedia 解析、USB 恢复策略、输出状态、无线/UxPlay IPC 与虚拟摄像头组件
App.Logic.Tests 设备身份、选择、更新解析、输出参数、媒体及输入路由等逻辑
App.Runtime.Tests 实际 WPF 加载、窗口交互、本地化、焦点、布局及运行时回归
DriverInstaller.Tests 驱动识别、错误分类、父驱动确认及恢复策略;模拟测试不等于完成真实驱动变更验证
Python unittest 触控/键盘消息、桥接安全边界、USBMux 与恢复逻辑
PowerShell 验证 暂存源、依赖载荷、签名/哈希和安装器规则等专项检查

App.Runtime.Tests --automation-lifecycle 包含后台准备/打开窗口的取消、管理锁释放、 已有会话保护及新建会话清理回归。--automation-lifecycle-long-startup 另外运行一次 46 秒的模拟反控启动,验证 API 不再用短于 DDI 准备期限的 45 秒超时中断启动;不连接手机。

当前另有未接入默认构建的专项入口,例如:

./scripts/test_driver_cleanup_safety.ps1
./scripts/test_cleanup_localization.ps1
dotnet run --project tests/UsbRecovery.Tests/UsbRecovery.Tests.csproj -c Release

前两个脚本只载入被测定义并使用模拟调用,不执行实际清理入口。 UI smoke、Test-WiredRecoveryDevice.ps1、Test-WiredControlUia.ps1 和 tools/srs-lab/Start-SrsLab.ps1 属于交互/实机场景,先阅读参数及前置条件,再按改动范围选择。 reset_driver_test_environment.ps1、驱动删除脚本和原生 USB 探针可能改变系统或设备状态, 不能当成普通测试批量执行。原生实机探针默认由 IPHONEMIRROR_BUILD_DANGEROUS_USB_TOOLS=OFF 排除。

打包与版本

# 默认从主程序项目读取版本,并要求驱动管理器版本一致
./scripts/package_release.ps1 -GenerateSbom

脚本生成 outputs/releases 下的 Setup、ZIP、SHA256SUMS.txt 和 SPDX SBOM。 标准包另附 UxPlay 可选组件 ZIP;应用首次选用时通过镜像下载并显示进度弹窗。 安装包默认以 100,000,000 字节为优化目标,超出时只提醒,组件完整可用优先。 需要强制限制的构建可显式传入 -EnforceInstallerSizeLimit。 不指定旧的 -Version 1.8.3,可避免与当前源码版本冲突。-SkipBuild 仅适用于已有匹配 载荷;它仍执行版本和完整性检查。构建与打包应使用一致的运行时省略选项。

ZIP 与安装包验收

每次交付必须分别测试同一版本的最终 ZIP 和 Setup 安装包,两者都通过后才能报告 “发布包正常”。源码测试、构建成功、打包成功或发布目录中的运行结果,均不能代替 实际交付产物的运行验证。验收至少覆盖以下项目:

产物 必测项目
ZIP 便携版 将最终 ZIP 完整解压到独立目录,核对版本、必需文件与哈希;从解压目录启动主程序和驱动管理器,验证首次启动、设置保存、关闭及再次启动。
Setup 安装包 使用最终安装 EXE 在隔离测试环境中全新安装,从安装目录启动主程序和驱动管理器;验证快捷方式、版本与文件完整性、覆盖升级及设置保留、卸载与重新安装。
两者分别执行 验证本次修改涉及的功能;有实机条件时分别验证有线/无线连接、投屏、键鼠控制、断开重连,以及退出后无需人工拔插即可再次连接和控制。需要按需下载的组件,应分别验证下载后可用。

scripts/test_installer.ps1 可补充安装、升级、卸载回归,但它会重新生成隔离测试安装器, 不能替代对最终交付安装 EXE 的验证,也不能替代 ZIP 验收。 测试记录应分别列出 ZIP 与 Setup 的版本、SHA-256、测试环境、场景、结果及日志位置。 任何一项失败或因环境限制未执行,都必须明确记录为失败或待验证;修复后重新打包, 并重新验证受影响的两种最终产物,不能沿用旧包的通过结果。

待上传资产确定后,可加 -UpdateReleaseManifest 同步 updates/releases.json 中 对应版本的大小与哈希。打包脚本不会代替维护者上传 GitHub Release。 -AllowVersionOverride 是显式覆盖,不应拿来掩盖主程序与驱动管理器的版本分歧。

Apple 支持包只在拥有再分发权时显式提供;参数及校验要求见 驱动依赖说明。通常公开包不包含 Apple USB 支持 MSI; DDI 是另一项载荷,当前标准包按 config/ddi-bundles.json 内置并校验 Personalized 与 Cryptex 镜像。 其分发状态见组件来源说明。 发布说明放在 docs/releases,根目录变更记录汇总版本;不要把工作区验证结果写成已发布事实。

配置、诊断与维护

  • 文档检查:python scripts/verify_docs.py 离线检查本地链接、图片、锚点、围栏及索引覆盖; 外部链接可用性、命令实际行为和真机结论需另行验证。
  • 用户设置由 UpdateSettingsStore 保存到 %LOCALAPPDATA%/iPhoneMirror/settings.json; 设备绑定位于同目录的 device-binding-profiles.json。
  • 主程序诊断位于 %LOCALAPPDATA%/iPhoneMirror/Logs;驱动 UI 日志位于 %LOCALAPPDATA%/iPhoneMirror.Driver/Logs/driver-ui.log。
  • 父驱动快照与提权日志位于 %ProgramData%/iPhoneMirror.Driver;快照不等于完整驱动备份。
  • 修改 C ABI 或 IPC 时同步两端结构、版本校验和对应测试;原生 API、无线 IPC、桥接运行时 清单、输入 JSON schema 是不同契约,参见架构说明。
  • 变更记录注明实际执行的命令、结果及未覆盖的实机环境;脱敏 UDID、配对记录和个人屏幕内容。