开发指南¶

许可证头¶

所有提交都必须带有适当的许可证头署名。

你可以通过运行以下命令轻松添加所有必要的许可证头：

git fetch origin master:master
.ci/license-header.sh -u -c
git push

或者，你也可以省略 -c 并执行一个 amend 提交：

git fetch origin master:master
.ci/license-header.sh
git commit --amend -a --no-edit

如果相关工作是从其他人或项目获得许可/引入的，你可以省略许可证头。此外，如果你希望对某段代码保留作者身份，你可以将其归属于自己；但该代码可能会在任何时候被修改，并最终归属于 Eden 的署名。

有关许可证头脚本的更多信息，请运行 .ci/license-header.sh -h。

拉取请求¶

拉取请求只有在经过充分测试且讨论在 Discord 或其他沟通渠道上得出结论后，才能由核心开发者合并。标签是推荐而非必需的。但是，所有 PR 都必须带有命名空间，并可选择带有类型前缀：

[cmake] refactor: CPM over submodules
[desktop] feat: implement firmware install from ZIP
[hle] stub fw20 functions
[core] test: raise maximum CPU cores to 6
[cmake, core] Unbreak FreeBSD Building Process

• 命名空间的层级通常由提交者自行决定。
• 不过，我们绝不建议超过两级，但 hle 除外，在该命名空间下，你可以根据更改的特定程度使用最多四级。
• 偶尔，可以额外提供最多两个命名空间，以提升清晰度。
• 影响整个项目（不含 CMake 更改）的更改应使用 meta 命名空间。
• 维护者可以随意更改命名空间。
• PR 内的提交不要求必须带命名空间，但强烈建议这样做。

添加新设置¶

添加新设置时，如果该设置是字段类型，请使用 tr("Setting:")；如果该设置是“是/否”或勾选类型，则使用 tr("Setting")。参见这份简短风格指南。

• 大多数软件在该设置的默认选项下必须能够正常工作，除非该设置会显著降低性能。
• 调试设置绝不能默认开启。
• 提供合理的边界（例如，控制 VRAM 数量的设置不应为 0）。
• 设置的描述必须简短精炼；如果某个设置“做了很多事情”，请考虑尽可能将其拆分为多个设置。
• 尽量避免多余/冗余的解释；“recommended for most users and games（推荐给大多数用户和游戏）”可以简写为“(recommended)（推荐）”。
• 尽量不要编写“slow/fast”选项，除非它确实会降低/提升特定场景下的性能；因为大多数选项可能会改变行为，导致不同系统上的表现指标各不相同。例如，如果选项是“accuracy（精度）”选项，写“High（高）”就足以暗示“Slow（慢）”，无需写成“High (Slow)”。

一些示例：

• “[…] negatively affecting image quality（对图像质量产生负面影响）”“[…] degrading image quality（降低图像质量）”：措辞相同，但后者废话更少。
• “[…] this may cause some glitches or crashes in some games（这可能会导致某些游戏出现故障或崩溃）”“[…] this may cause soft-crashes（这可能会导致软崩溃）”：崩溃本身就暗示可能存在故障（因为崩溃在技术上也是致命故障的一种形式）。整个句子结构“may cause [...] on some games（可能会导致某些游戏……）”是冗余的，因为“may cause [...] in games（可能会导致游戏……）”具有相同的语义（“may”本身就表示在“某些”给定情况下发生的概率）。
• “FIFO Relaxed is similar to FIFO [...]（FIFO Relaxed 与 FIFO 类似）”“FIFO Relaxed [...]”：名称本身已经暗示了相似性。
• “[…] but may also reduce performance in some cases（但在某些情况下也可能会降低性能）”“[…] but may degrade performance（但可能会降低性能）”：同样，“some cases（某些情况）”和“may（可能）”本身就暗示了存在概率。
• “[…] it can [...] in some cases（在某些情况下它可以……）”“[…] it can [...]（它可以……）”：概率已隐含其中。

在添加新设置之前，请考虑：

• 该设置所涉及的代码，在开启/关闭时是否会产生显著差异？
• 它能否被自动检测？

IDE 设置¶

VSCode¶

将此内容复制到 .vscode/settings.json，安装 CMake 工具扩展后，应该就可以直接构建了：

{
    "editor.tabSize": 4,
    "files.watcherExclude": {
        "**/target": true
    },
    "files.associations": {
      "*.inc": "cpp"
    },
    "git.enableCommitSigning": true,
    "git.alwaysSignOff": true
}

如果构建 Qt，你可能还需要 Qt Extension Pack 扩展。

构建加速¶

如果你使用的是 HDD，请使用 ramdisk（在 RAM 中构建）。完整构建并包含调试符号大约需要 4GB 空间：

mkdir /tmp/ramdisk
chmod 777 /tmp/ramdisk
# about 8GB needed
mount -t tmpfs -o size=4G myramdisk /tmp/ramdisk
cmake -B /tmp/ramdisk
cmake --build /tmp/ramdisk -- -j32
umount /tmp/ramdisk

资源与大文件¶

上传文件前的一个大致经验法则：

• PNG 文件：使用 optipng。
• SVG 文件：使用 svgo。

可能不常用，但值得一提：

• OGG 文件：使用 OptiVorbis。
• 视频文件：使用 ffmpeg，最好重新编码为 AV1。