如何为WallpaperMachine贡献代码:源码入门与开发工作流完整指南
如何为WallpaperMachine贡献代码:源码入门与开发工作流完整指南
WallpaperMachine 是一款在 Mac 上播放 Wallpaper Engine 动态壁纸的免费开源应用,支持场景(scene)、视频和网页三类壁纸。本文是一份面向新手贡献者的 WallpaperMachine 源码入门与开发工作流指南:从搭好 Apple Silicon 开发环境、跑通首次构建与测试,到新代码该放哪里、提交与 Pull Request 怎么写,帮你在提交第一个 PR 之前就少走弯路。
项目速览:四层结构决定你的动手方向
WallpaperMachine 由 CONTRIBUTING.md 概括为「AppKit 外壳 + SwiftUI 控制面板的沙盒 macOS 应用、锁屏 ExtensionKit 扩展,以及一个 vendored 的 Rust/C++ 渲染器」。理解下面这张地图,是 WallpaperMachine 源码入门的第一步:
| 目录 | 技术栈 | 职责 |
|---|---|---|
App/ |
Swift | 主程序:Services/<Domain>/ 领域逻辑、ViewModels/、Views/ControlPanel/ SwiftUI 面板 |
Extension/ + Shared/ |
Swift | 沙盒锁屏扩展;Shared/ 只放两个目标都编译的代码 |
Renderer/ |
Rust + C++ | 渲染器:Rust 工作区(Shader/、Core/、Bridge/)与 C++ 场景引擎(Engine/) |
scripts/ |
Python | 开发者命令行:构建、测试、检查、打包,全部入口都在这里 |
Tests/ |
Swift | 单元测试 Tests/Unit/<Domain>/ 与显式开启的 Tests/UI/ |
上图是仓库自带的入门视频壁纸(位于 Resources/StarterWallpaper/),也是你本地跑通应用后最先看到的画面之一。更完整的目录地图见 docs/repository-layout.md,运行时各部件如何协作见 docs/architecture.md。
开发环境一键配置:Xcode、Homebrew 与 Rust 工具链
构建 WallpaperMachine 有硬性前提(详见 docs/build.md):
- Apple Silicon(
project.yml锁定arm64) - macOS 15.6+,且用
xcode-select选中完整 Xcode 26(仅 Command Line Tools 不够) - Homebrew 提供渲染器依赖,
python3需 3.11+,cargo需在PATH中
按 docs/build.md 的清单安装:
brew install quickjs-ng freetype lz4 nlohmann-json argparse
brew install rustup python cmake ninja pkg-config xcodegen
Rust 工具链由 Renderer/rust-toolchain.toml 固定为 nightly(Homebrew 的 rust 公式会忽略该文件,务必用 rustup):
export PATH="$(brew --prefix rustup)/bin:$PATH"
cd Renderer && rustup toolchain install
最后克隆仓库开始动手:
git clone https://gitcode.com/gh_mirrors/wa/WallpaperMachine
首次构建与运行测试:两条命令跑通项目
环境就绪后,WallpaperMachine 的开发工作流只有两条核心命令:
python3 scripts/build.py
python3 scripts/test.py
scripts/build.py 会按四阶段推进:cargo build 编译 Rust/C++ 渲染器 → uniffi-bindgen 生成 Swift 桥接(写入 App/Bridge/Generated/)→ xcodegen 从 project.yml 重新生成 WallpaperMachine.xcodeproj → xcodebuild 构建应用(内嵌锁屏扩展)。构建产物位于 build/Build/Products/Debug/WallpaperMachine.app,各阶段完整日志在 artifacts/build/,终端只显示错误与结论,排查失败时加 --verbose。
scripts/test.py 依次运行 Python 脚本测试、项目生成和全部原生单元测试(WallpaperMachineTests,上千个用例),结果落在 artifacts/tests/。测试不会触碰你的桌面壁纸,常规验证完全无侵入。
如果你还希望打包成可安装的磁盘镜像:
python3 scripts/package.py --configuration Release --install
日常开发循环:改代码、跑测试、提 PR
来自 CONTRIBUTING.md 的标准循环,照着做即可:
- 编辑源码。 只改 Swift/资源时用
python3 scripts/build.py --swift-only;改到Renderer/或桥接接口必须完整构建。 - 迭代测试。 开发中用
python3 scripts/test.py --only <TestClass>只跑你改动的域;提交 PR 前完整跑一次python3 scripts/test.py。 - 按需加测。 Rust crate 改动补跑
python3 scripts/check_rust.py;渲染器、桥接或场景改动补跑python3 scripts/check_renderer.py;python3 scripts/test.py --ui会接管桌面,只在明确需要时运行。 - 更新文档。 行为变了就更新对应文档;功能或跨域改动用
python3 scripts/log_verification.py --title "…" --line "…"记录验证。收尾前git status应只剩你的改动;清理产物用python3 scripts/clean.py --dry-run预览。
项目还有明确的「验证分级」,改动越大投入越多,详见 docs/testing/README.md。
新代码放哪里:目录归属速查
拿不准新文件放哪时,对照 docs/repository-layout.md 的表格:
| 你要加的东西 | 放这里 |
|---|---|
| App 服务或领域逻辑 | App/Services/<Domain>/(优先复用现有域) |
| 控制面板页面/功能 | App/Views/ControlPanel/<Area>/ |
| 单元测试 | Tests/Unit/<Domain>/(与被测代码同域同名) |
| 开发者脚本 | scripts/<name>.py(snake_case,argparse) |
| Rust crate / 场景引擎改动 | Renderer/Core/、Renderer/Bridge/、Renderer/Shader/、Renderer/Engine/ |
| 文档 | docs/ 或 docs/features/,并更新索引 |
贡献者的五条硬规则
这些是最容易翻车的红线(完整规则在 AGENTS.md 与 docs/conventions.md):
- 绝不手改生成文件。
WallpaperMachine.xcodeproj来自project.yml,App/Bridge/Generated/来自uniffi-bindgen;改源头、重新生成、两者一起提交。 - 不动
ThirdParty/不更新清单。 任何 vendored 改动都必须同步 ThirdParty/provenance.json。 - 不提交
artifacts/和build/。 两者均可丢弃;截图、trace、个人路径同样禁止入库。 - 用户可见文案必须本地化。 新字符串要进入全部三个
.xcstrings目录,且字面量必须与目录 key 完全一致;README.md 与 README.zh-CN.md 必须同时修改(见 docs/localization.md)。 - 修壁纸渲染问题要修通用机制。 禁止按 Workshop ID、标题或文件名给个别壁纸开特判;先复现成通用测试再修复(docs/testing/wallpaper-fixes.md)。
提交与 PR 规范:Conventional Commits 与 Sign-off
- 提交信息用 Conventional Commits,例如
fix(scene): …、feat(downloads): …。类型不是装饰:feat/fix/perf的标题和正文会被 scripts/release_notes.py 直接写进面向用户的发布说明,所以按「用户看得懂」的标准来写。 - PR 标题即提交标题。 PR 通常以 squash 方式合并,多提交 PR 合并后标题会成为最终 commit subject——给 PR 起标题就要像给 commit 起标题。
- 保持线性历史。 CI 会自行向
main提交(版本号、Supporter 列表),长期分支容易落后:请求评审前用git pull --rebase追平origin/main,不要制造 merge commit。 - 签名提交。 用
git commit -s签署 DCO(Developer Certificate of Origin),并在 PR 中勾选 sign-off——squash 合并会丢弃逐条 trailer,勾选框是唯一留存。 - 遵守许可。 项目为 GPL-3.0-only(LICENSING.md),贡献即视为以相同条款授权;仅受 GPL-2.0-only 保护的代码无法被接受。
延伸阅读
- 构建与打包细节:docs/build.md
- 代码、测试与文档规范:docs/conventions.md
- 测试策略与验证分级:docs/testing/README.md
- 渲染器与 GPU 调试:docs/testing/renderer.md
- 本地化与翻译贡献:docs/localization.md

