開發人員指南

本文提供與想要為 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 儲存庫之外，其他感興趣的程式碼庫是 Emscripten 呼叫的 LLVM 和 Binaryen，以及它們自己的儲存庫。

提交修補程式

修補程式應以正常方式在 GitHub 上以提取請求提交。

提交修補程式時，請

  • 如果您新增任何新功能或修正錯誤，請新增自動測試。在 test/*.py 中搜尋相關測試，因為通常最簡單的方法是新增至現有的測試。如果您不確定如何測試您的程式碼，請隨時尋求協助。

  • 請注意我們在 .clang-format 中指定的程式碼樣式。

  • 我們通常會壓縮和合併 PR，這表示 PR 會變成目標分支上的單一提交。因此，PR 本身有合併提交是可以的，因為它們會被移除。請在 PR 描述中放入最終提交的良好描述，我們會在壓縮時使用它。

程式碼審查

其中一位核心開發人員會在合併提取請求之前進行審查。如果過了幾天您的 PR 都沒有任何評論，請在 PR 中評論，這會 ping 他們。（如果發生這種情況，抱歉！有時會遺漏某些事情。）

編譯器概述

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、執行 meta-dce 和其他有用的操作。它也會對與 Wasm 一起發出的 JS 執行 JS 最佳化。

Emscripten 測試套件

Emscripten 有一個全面的測試套件，涵蓋幾乎所有 Emscripten 功能。這些測試會在您建立提取請求時在 CI 上自動執行，而且它們都應該通過。如果您遇到無法修正的測試失敗問題，請告知開發人員。

二分搜尋

如果您發現回歸，二分搜尋通常是找出問題所在的最快方法。這不僅適用於尋找 Emscripten 中的實際回歸，也適用於當您升級時專案停止運作，而且您需要調查是 Emscripten 回歸還是其他問題時。本節的其餘部分涵蓋對 Emscripten 本身進行二分搜尋。希望對使用 Emscripten 的人和 Emscripten 開發人員都有幫助。

如果您有很大的二分搜尋範圍（例如，涵蓋多個版本的 Emscripten），那麼您可能會在多個儲存庫（Emscripten、LLVM 和 Binaryen）之間進行變更。在這種情況下，最簡單和最快的方法是使用 emsdk 建置進行二分搜尋。二分搜尋的每個步驟都會下載 Emscripten 發行版本建置器產生的建置版本。使用此方法，您不需要自己編譯任何內容，因此速度可以非常快！

若要執行此操作，您需要基本了解 Emscripten 的發行流程。關鍵概念是

emsdk install [HASH]

可以從過去的任何時間點安裝 Emscripten 的任意建置版本（假設建置成功）。每個建置版本都由雜湊值（一長串數字和字元）識別，它是 releases 儲存庫中提交的雜湊值。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，並繼續進行二分搜尋，直到找到第一個錯誤提交。

第一個錯誤提交是 releases 儲存庫中的單一變更。該提交通常會更新單一子儲存庫 (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 測試將會失敗。

另請參閱