[Sunrisepeak]

中文

HuxerUI 增加第二个构建系统：mcpp 用一个 mcpp.toml 构建框架和应用，覆盖 Linux / Windows / macOS / iOS / Android / Web。CMake 构建不变，两者并存。本 PR 是 A；Lib-Live2D 的 B（Sunrisepeak/Lib-Live2D#2）和 live2d 模板 C（#8）依赖它。

1. 两个构建系统必须一致的内容：规范与验证

• 规范： docs/design/build-systems-spec.md 规定默认程序模型（链接、资源包与命名空间、资源位置、平台下限、应用 id 与图标、Android manifest 与 native 库、Info.plist、签名、产物与发布位置）、开发者扩展点、允许的差异，以及 SDK / CLI 的规则。
• 验证： build-systems-conformance.yml 用同一个 CLI 分别创建 CMake 与 mcpp 应用，huxerui package <平台> 打包，读出产物的程序模型事实并比对。差异不在规范白名单里就失败。PR 上跑 Linux / Web / Android，每周和手动触发跑六个平台。

白名单里的差异，每条都附理由：

• Linux AppImage 自带 mcpp 链接的 GTK，CMake 用发行版的；
• macOS / iOS 的 C++ 标准库来源；
• iOS 启动屏形式与图标容器（Xcode 的 ibtool / actool 不可再分发）；
• 版本号来自 [package] version；
• Windows：CMake 动态链接 MSVC 运行时并随程序安装，mcpp 静态链接；
• 另有几项文件名与元数据，见规范 §4。

2. mcpp 构建：默认与 CMake 相同

方面	mcpp 构建
框架链接与加载	桌面、iOS、Web 静态链接；Android 为独立的 libhuxerui.so，Java 侧加载方式不变
资源包	一个应用一个包：框架内置 → 直接依赖的 HuxerUI 库（命名空间 package_product）→ 应用（app）
平台元数据	Android manifest、Info.plist、图标、Web 页面取 CLI 模板的内容；BuildConfig 与 MainActivity 与 Gradle 模板相同
签名	Android release 包不签名、debug 包用 debug key；macOS ad-hoc；可显式配置 keystore / identity
产物	AppImage、带安装界面的 Setup.exe、DMG、双 ABI APK（native 库剥离、不压缩存放）、.app、Web 目录，发布到 dist/<平台>
扩展点	应用的 android/java、android/kotlin、android/res、android/libs、Maven 锁文件，ios/Info.plist、macos/Info.plist，iOS 真机；库的资源与 Android 源码
C++ 标准	全部 c++20

依赖的外部版本： mcpp 2026.9.15.2、mcpp:plugins 0.11.1（mcpp-community/mcpp-plugins#27：dist-apk 剥离 native 库并按 manifest 不压缩存放，dist-appimage 支持 SVG 图标）。

3. SDK / CLI 改动与理由

SDK（与 CMake 共用；框架运行时和平台代码没有改动）

• NodeExtensionHandle::operator== 改为手写，语义与 = default 相同。原因：clang 搭配 MSVC 标准库时默认版本让 std::find 编译失败（<xutility>: std::find no longer compiles with structs with defaulted equality comparison with Clang-CL microsoft/STL#6294）。
• hrc 新增两个可选参数 --depfile、--module-name，CMake 不传，行为不变。
• Windows 安装界面模板 corner_radius 改为 corner_radii：upstream 缺陷，CMake 生成的安装界面同样编译不过。
• hcg、hrc 的 mcpp.toml 许可证改为 MIT，只是包元数据。

CLI（CMake 项目的行为不变）

• 一套命令，按项目类型分发：mcpp 项目的 build、run、package、platform add 调用 mcpp。package 把 mcpp 报告的产物发布到 dist/<平台>，与 CMake 项目相同；Windows 打包传 --features windows-installer，安装界面只在打包时构建，与 CMake 相同。
• --profile 显式传给 mcpp（dev / release）。原因：mcpp pack 没有 --release，且默认是 release。
• run ios --device 映射到 aarch64-ios，设备经 DEVICECTL_RUN_DEVICE 交给 devicectl-run（未在真机上实测）。
• doctor 保持只读；删除重复的 huxerui mcpp build；create --build mcpp 支持 --platform、--id。
• platforms 键逐行匹配，不用 std::regex::multiline：MSVC 标准库没有它，CLI 在 Windows 上编译不过。
• CMake 侧只改了 CLI 的源文件列表：新增 mcpp_backend.cpp，删除 mcpp/mcpp.cpp。

4. mcpp 构建相对 CMake 的额外能力

可选，直接用 mcpp 命令或清单，不经过 CLI：全模块（import huxerui;、资源模块）、自动准备的环境、一个清单六个平台、MSI / AAB / macOS .app、在模拟器和设备上直接运行、mcpp test、按次切换工具链、锁文件、桌面共享框架。见 docs/guide/cpp-modules-and-mcpp.md。

5. 验证与未覆盖的部分

• CI：mcpp Build（六个平台的构建与产物检查、模板、parity）、Tool Tests、Build Systems Conformance（六个平台）。
• 未实测：iOS 真机；共享 macOS 框架中异常跨镜像按类型捕获（mcpp#646 F2）。
• 已登记的缺口（规范 §3，Build programs: query the resolved dependency graph and package metadata; compile Swift sources; Android on a macOS host; feature and tool contract mismatches mcpp-community/mcpp#647）：库的 Swift（E2）、传递依赖的库资源与 Android 源码（E1）、在 macOS / Windows 主机上构建 Android（E3）。

---

English

HuxerUI gains a second build system: mcpp builds the framework and applications from one mcpp.toml for Linux, Windows, macOS, iOS, Android and the Web. The CMake build is unchanged, and the two coexist. This PR is A; Lib-Live2D's B (Sunrisepeak/Lib-Live2D#2) and the live2d template C (#8) build on it.

1. What the two build systems must agree on: a specification and a check

• Specification: docs/design/build-systems-spec.md defines three things and the rules the SDK and the CLI follow:
  • the default program model: linking, the resource package and its namespaces, resource locations, platform floors, identity and icons, the Android manifest and native libraries, Info.plist, signing, artifacts and where they are published;
  • the developer extension points;
  • the allowed differences.
• Check: build-systems-conformance.yml creates the same application for CMake and for mcpp with one CLI and packages each with huxerui package <platform>. It then reads the program model facts from both artifacts and fails on any difference the specification does not list. Linux, the Web and Android run on pull requests; all six platforms run weekly and on request.

Each allowed difference carries its reason:

• The Linux AppImage carries the GTK mcpp linked, where CMake's uses the distribution's.
• The macOS and iOS C++ standard library comes from a different source.
• The iOS launch screen and icon take a different form, because Xcode's ibtool and actool are not redistributable.
• Versions come from [package] version.
• On Windows, CMake links the MSVC runtime as DLLs and installs them; mcpp links it statically.
• A few file names and metadata keys, listed in the specification's §4.

2. The mcpp build: CMake's program by default

	mcpp build
Framework linking and loading	Static on desktop, iOS and the Web; its own libhuxerui.so on Android, loaded by the Java host as before
Resource package	One per application: builtin → each direct HuxerUI library (namespace package_product) → the application (app)
Platform metadata	The CLI templates' Android manifest, Info.plist entries, icons and Web page; BuildConfig and MainActivity as the Gradle template has them
Signing	Android release unsigned, debug with the debug key; macOS ad hoc; a keystore or identity when stated
Artifacts	AppImage, a Setup.exe with the installer interface, DMG, a two-ABI APK (native libraries stripped and stored uncompressed), .app, Web directory, published to dist/<platform>
Extension points	The application's android/java, android/kotlin, android/res, android/libs and Maven lock, ios/Info.plist and macos/Info.plist, iOS devices; a library's resources and Android sources
C++ standard	c++20 throughout

External versions: mcpp 2026.9.15.2 and mcpp:plugins 0.11.1 (mcpp-community/mcpp-plugins#27):

• dist-apk strips native libraries and stores them uncompressed when the manifest asks;
• dist-appimage takes an SVG icon.

3. SDK / CLI changes and why

SDK (shared with CMake; no framework runtime or platform code changes)

• NodeExtensionHandle::operator== is written out, equivalent to = default: with clang and the MSVC standard library the defaulted version breaks std::find (<xutility>: std::find no longer compiles with structs with defaulted equality comparison with Clang-CL microsoft/STL#6294).
• hrc gains the optional --depfile and --module-name; CMake passes neither.
• The Windows installer template uses corner_radii instead of corner_radius. This is an upstream defect: the interface CMake generates did not compile either.
• hcg's and hrc's mcpp.toml licence is MIT; package metadata only.

CLI (CMake projects unchanged)

• One set of commands, dispatched by project type. In an mcpp project, build, run, package and platform add run mcpp.
  • package publishes the artifacts mcpp reports to dist/<platform>, as for a CMake project.
  • A Windows package passes --features windows-installer, so the installer interface is built for a package only, as under CMake.
• --profile is passed to mcpp explicitly (dev / release), because mcpp pack has no --release and defaults to release.
• run ios --device maps to aarch64-ios; the device reaches devicectl-run as DEVICECTL_RUN_DEVICE. This is not measured on a device.
• Other changes:
  • doctor stays read-only.
  • The duplicate huxerui mcpp build is removed.
  • create --build mcpp takes --platform and --id.
• The platforms key is matched line by line rather than with std::regex::multiline, which MSVC's standard library lacks; the CLI did not compile on Windows.
• On the CMake side only the CLI's source list changes: mcpp_backend.cpp is added and mcpp/mcpp.cpp removed.

4. What the mcpp build adds beyond CMake

These are optional, and used through mcpp or the manifest rather than the CLI:

• modules throughout (import huxerui;, a resource module);
• a provisioned environment;
• one manifest for six platforms;
• MSI, AAB and a macOS .app;
• running on simulators and devices;
• mcpp test, per-command toolchains and a lock file;
• a shared desktop framework.

See docs/guide/cpp-modules-and-mcpp.md.

5. Verification and what is not covered

• CI runs three workflows:
  • mcpp Build: builds and artifact checks on six platforms, the templates and parity;
  • Tool Tests;
  • Build Systems Conformance, on six platforms.
• Not measured: an iOS device; whether an exception thrown in a shared macOS framework is caught by type (mcpp#646 F2).
• Recorded gaps (specification §3, Build programs: query the resolved dependency graph and package metadata; compile Swift sources; Android on a macOS host; feature and tool contract mismatches mcpp-community/mcpp#647):
  • a library's Swift (E2);
  • transitive libraries' resources and Android sources (E1);
  • an Android build on a macOS or Windows host (E3).