开发者指南

本文档提供了一些与想要为 Emscripten 做贡献的人员相关的信息。我们欢迎任何对提供帮助感兴趣的人的贡献！

提示

如果您只是使用 Emscripten，那么这些信息可能不太相关，但可能仍然值得关注。

设置

要为 Emscripten 的核心代码做贡献，例如 emcc.py，您无需构建任何二进制文件，因为 emcc.py 是用 Python 编写的，而核心 JS 生成是用 JavaScript 编写的。您仍然需要 LLVM 和 Binaryen 的二进制文件，您可以使用 emsdk 获取它们

emsdk install tot
emsdk activate tot

这将安装运行 Emscripten 所需的最新“树顶”二进制文件。您可以将这些 emsdk 提供的二进制文件与 Emscripten 存储库的 git 检出一起使用。为此，您可以编辑本地 .emscripten 配置文件，或者在环境中设置 EM_CONFIG=/path/to/emsdk/.emscripten。

如果您确实想为 LLVM 或 Binaryen 做贡献，或者测试对它们的修改，您可以 从源代码构建它们.

感兴趣的仓库和分支

Emscripten 主存储库是 https://github.com/emscripten-core/emscripten.

除了 Emscripten 存储库外，其他感兴趣的代码库是 LLVM 和 Binaryen，Emscripten 会调用它们，以及 它们自己的存储库.

提交补丁

补丁应以通常的方式在 GitHub 上作为拉取请求提交。

提交补丁时，请

  • 如果您添加了任何新功能或修复了错误，请添加一个自动测试。在 test/*.py 中搜索相关的测试，因为通常最简单的方法是添加到现有测试中。如果您不确定如何测试您的代码，请随时寻求帮助。

  • 请注意我们在 .clang-format 中指定的编码风格。

  • 我们通常会压缩和合并 PR，这意味着 PR 会变成目标分支上的一个单独提交。正因为如此，在 PR 本身中进行合并提交是可以的，因为它们会被删除。请在 PR 描述中为最终提交提供一个好的描述，我们会在压缩时使用它。

代码审查

核心开发人员之一将在合并拉取请求之前对其进行审查。如果几天过去了，您的 PR 没有任何评论，请在 PR 中评论，这将提醒他们。（如果发生这种情况，对不起！有时事情会被遗漏。）

编译器概述

The Emscripten 编译器前端 (emcc) 是一个 python 脚本，它管理整个编译过程

  • emcc 调用 Clang 编译 C++ 和 wasm-ld 进行链接。它构建并与 Emscripten 系统库集成，包括已编译的库和用 JS 实现的库。

  • emcc 然后调用 emscripten.py，它执行最终的 Wasm 转换（包括调用 Binaryen 中的 wasm-emscripten-finalize）并调用 JS 编译器（参见 src/compiler.mjs 及其相关文件），它会输出 JS。

  • 如果优化 Wasm，emcc 然后会调用 wasm-opt，运行元 DCE 和其他有用的操作。它还会对与 Wasm 一起输出的 JS 运行 JS 优化。

Emscripten 测试套件

Emscripten 拥有一个 全面的测试套件，它涵盖了几乎所有 Emscripten 功能。这些测试会在您创建拉取请求时在 CI 上自动运行，它们都应该通过。如果您遇到无法解决的测试失败问题，请告知开发人员。

二分查找

如果您发现回归，二分查找通常是找出问题所在的最快方法。这不仅适用于在 Emscripten 本身中查找实际回归，还适用于当您升级时项目停止工作，您需要调查是 Emscripten 回归还是其他问题。本节的其余部分介绍了 Emscripten 本身的二分查找。希望这对 Emscripten 用户和 Emscripten 开发人员都有用。

如果您有一个很大的二分查找范围 - 例如，它涵盖了多个版本的 Emscripten - 那么您可能在多个存储库（Emscripten、LLVM 和 Binaryen）中进行了更改。在这种情况下，最简单、最快的方法是使用 emsdk builds 进行二分查找。二分查找的每一步都将下载由 emscripten 发布构建者生成的构建。使用这种方法，您无需自己编译任何内容，因此速度非常快！

为此，您需要了解 Emscripten 的 发布过程 关键思想是

emsdk install [HASH]

可以安装过去任何时间点的任意版本的 emscripten（假设构建成功）。每个构建都由一个哈希值（一个由数字和字符组成的长字符串）标识，它是 发布存储库 中提交的哈希值。Emscripten 发布号到此类哈希值的映射由 emsdk 存储库中的 emscripten-releases-tags.json 跟踪。

有了这些背景知识，二分查找过程如下所示

  1. 查找要二分查找的哈希值。如果您在 tot 构建中发现了问题，那么您可能已经知道它们了。如果您只知道 Emscripten 版本号，请使用 emscripten-releases-tags.json 查找哈希值。

  2. 使用这些哈希值，对 emscripten-releases 存储库进行正常的 git bisect。

  3. 在二分查找的每一步，使用 emsdk install HASH 下载当前提交哈希值（您正在其上进行二分查找的 emscripten-releases 存储库）的二进制构建。然后测试您的代码并根据情况执行 git bisect good 或 git bisect bad，并继续二分查找，直到找到第一个错误的提交。

第一个错误的提交是发布存储库中的单个更改。该提交通常会更新一个子存储库（Emscripten、LLVM 或 Binaryen）以添加一个或多个新更改。通常该列表会非常短，甚至只有一个提交，您可以看到是哪个实际提交导致了问题。在提交错误时，提及此类二分查找结果可以大大加快速度（即使该提交包含多个更改）。

如果该提交包含多个更改，那么您可以选择对特定存储库进行进一步的二分查找（因为所有更改通常都只在一个存储库中，而其他存储库保持不变）。执行此操作需要在本地重新构建，而本节中描述的主要二分查找不需要这样做。

使用 C 结构体和定义

如果您更改了 C 结构体的布局或修改了在 JavaScript 库文件中使用的 C 定义，则可能需要修改 tools/struct_info.json。每次修改该文件或更改结构体布局时，您都需要运行 ./tools/gen_struct_info.py 重新生成 JavaScript 使用的信息。请注意，您需要同时运行 ./tools/gen_struct_info.py 和 ./tools/gen_struct_info.py --wasm64。

如果您忘记执行此操作，test_gen_struct_info 测试将失败。

另请参阅