編寫與 npm

如何將 WebAssembly 整合至這個設定？在本文中，我們將以 C/C++ 和 Emscripten 為例，說明如何解決這個問題。

Surma

WebAssembly (wasm) 通常會被視為效能原始碼，或是在網路上執行現有 C++ 程式碼集的方法。我們希望透過 squoosh.app 證明 WASM 至少還有第三種觀點：利用其他程式設計語言的龐大生態系統。Emscripten 可讓您使用 C/C++ 程式碼，Rust 內建了 WASM 支援，Go 團隊也正在進行相關工作。我相信之後還會有更多語言版本。

在這些情況下，WASM 並非應用程式的重點，而是拼圖的一部分：另一個模組。您的應用程式已含有 JavaScript、CSS、圖片素材資源、以網頁為中心的建構系統，甚至可能還有 React 等架構。如何將 WebAssembly 整合至這項設定？在本文中，我們將以 C/C++ 和 Emscripten 為例，說明如何執行這項操作。

Docker

我發現在使用 Emscripten 時，Docker 非常實用。C/C++ 程式庫通常會寫入與其建構的作業系統相容的程式碼。保持一致的環境非常有幫助。使用 Docker 可取得虛擬化的 Linux 系統，該系統已設定為與 Emscripten 搭配運作，並已安裝所有工具和依附元件。如果缺少某些內容，您可以直接安裝，不必擔心會影響自己的機器或其他專案。如果發生錯誤，請丟棄容器並重新開始。如果一次運作成功，您可以確定它會繼續運作並產生相同的結果。

Docker Registry 有我經常使用的 trzeci 提供的 Emscripten 映像檔。

與 npm 整合

在大多數情況下，網站專案的進入點是 npm 的 package.json。依照慣例，大多數專案都可以使用 npm install && npm run build 建構。

一般來說，Emscripten 產生的建構成果 (.js 和 .wasm 檔案) 應視為另一個 JavaScript 模組和另一個資產。JavaScript 檔案可由 webpack 或 rollup 等套件處理器處理，而 WASM 檔案應視為任何其他較大的二進位素材資源，例如圖片。

因此，您必須先建構 Emscripten 構建成果，才能啟動「一般」構建程序：

{
    "name": "my-worldchanging-project",
    "scripts": {
    "build:emscripten": "docker run --rm -v $(pwd):/src trzeci/emscripten
./build.sh",
    "build:app": "<the old build command>",
    "build": "npm run build:emscripten && npm run build:app",
    // ...
    },
    // ...
}

新的 build:emscripten 工作可直接叫用 Emscripten，但如先前所述，建議您使用 Docker 確保建構環境一致。

docker run ... trzeci/emscripten ./build.sh 會指示 Docker 使用 trzeci/emscripten 映像檔啟動新的容器，並執行 ./build.sh 指令。build.sh 是您接下來要編寫的 Shell 指令碼！--rm 會指示 Docker 在容器執行完畢後刪除容器。如此一來，您就不會隨著時間累積過多過時的機器映像檔。-v $(pwd):/src 表示您希望 Docker 將當前目錄 ($(pwd))「鏡像」到容器內的 /src。您對容器內 /src 目錄中的檔案所做的任何變更，都會反映在實際專案中。這些鏡像目錄稱為「繫結掛載點」。

讓我們來看看 build.sh：

#!/bin/bash

set -e

export OPTIMIZE="-Os"
export LDFLAGS="${OPTIMIZE}"
export CFLAGS="${OPTIMIZE}"
export CXXFLAGS="${OPTIMIZE}"

echo "============================================="
echo "Compiling wasm bindings"
echo "============================================="
(
    # Compile C/C++ code
    emcc \
    ${OPTIMIZE} \
    --bind \
    -s STRICT=1 \
    -s ALLOW_MEMORY_GROWTH=1 \
    -s MALLOC=emmalloc \
    -s MODULARIZE=1 \
    -s EXPORT_ES6=1 \
    -o ./my-module.js \
    src/my-module.cpp

    # Create output folder
    mkdir -p dist
    # Move artifacts
    mv my-module.{js,wasm} dist
)
echo "============================================="
echo "Compiling wasm bindings done"
echo "============================================="

這裡有很多內容要分析！

set -e 會將殼層置於「快速失敗」模式。如果指令碼中的任何指令傳回錯誤，整個指令碼就會立即中止。這點非常實用，因為指令碼的最後輸出內容一律會是成功訊息，或是導致建構失敗的錯誤。

您可以使用 export 陳述式定義幾個環境變數的值。這些參數可讓您將額外的命令列參數傳遞至 C 編譯器 (CFLAGS)、C++ 編譯器 (CXXFLAGS) 和連結器 (LDFLAGS)。這些參數都會透過 OPTIMIZE 接收最佳化工具設定，確保所有項目都以相同方式進行最佳化。OPTIMIZE 變數有幾個可能的值：

  • -O0：不進行任何最佳化。不會移除任何無效程式碼，Emscripten 也不會壓縮所產生的 JavaScript 程式碼。適合用於偵錯。
  • -O3：積極提升效能。
  • -Os：以效能為優先，並將大小做為次要標準進行最佳化。
  • -Oz：積極縮減大小，視需要犧牲效能。

對於網頁，我大多建議使用 -Os。

emcc 指令本身有許多選項。請注意，emcc 應為「GCC 或 clang 等編譯器的即時替代品」。因此，您可能知道的 GCC 所有標記，很可能也會由 emcc 實作。-s 標記很特別，因為它可讓我們特別設定 Emscripten。您可以在 Emscripten 的 settings.js 中找到所有可用選項，但該檔案可能會讓您感到不知所措。以下是我們認為對網頁程式開發人員最重要的 Emscripten 標記清單：

  • --bind 會啟用 embind。
  • -s STRICT=1 已停止支援所有已淘汰的建構選項。這樣可確保程式碼以向前相容的方式建構。
  • -s ALLOW_MEMORY_GROWTH=1 可在必要時自動增加記憶體。在撰寫本文時，Emscripten 會一開始分配 16 MB 的記憶體。當程式碼分配記憶體區塊時，這個選項會決定這些作業是否會在記憶體用盡時導致整個 WASM 模組失敗，或是允許黏合程式碼擴充總記憶體以因應分配作業。
  • -s MALLOC=... 會選擇要使用的 malloc() 實作項目。emmalloc 是專為 Emscripten 實作的 malloc() 小型快速實作項目。替代方案是 dlmalloc，這是完整的 malloc() 實作。只有在經常分配大量小型物件，或想要使用執行緒時，才需要切換至 dlmalloc。
  • -s EXPORT_ES6=1 會將 JavaScript 程式碼轉換為 ES6 模組，並提供可與任何 bundler 搭配使用的預設匯出功能。也需要設定 -s MODULARIZE=1。

下列旗標不一定必要，或僅供偵錯使用：

  • -s FILESYSTEM=0 是與 Emscripten 相關的標記，當您的 C/C++ 程式碼使用檔案系統作業時，它可以為您模擬檔案系統。它會對所編譯的程式碼進行一些分析，決定是否要在黏合程式碼中加入檔案系統模擬功能。不過，有時這項分析可能會出錯，您可能會為不需要的檔案系統模擬作業付出相當龐大的 70 KB 額外黏合程式碼。您可以使用 -s FILESYSTEM=0 強制 Emscripten 不納入這個程式碼。
  • -g4 會讓 Emscripten 在 .wasm 中加入偵錯資訊，並為 wasm 模組產生來源對應檔案。如要進一步瞭解如何使用 Emscripten 進行偵錯，請參閱「偵錯」一節。

就是這樣！為了測試這個設定，我們來快速建立一個小小的 my-module.cpp：

    #include <emscripten/bind.h>

    using namespace emscripten;

    int say_hello() {
      printf("Hello from your wasm module\n");
      return 0;
    }

    EMSCRIPTEN_BINDINGS(my_module) {
      function("sayHello", &say_hello);
    }

以及 index.html：

    <!doctype html>
    <title>Emscripten + npm example</title>
    Open the console to see the output from the wasm module.
    <script type="module">
    import wasmModule from "./my-module.js";

    const instance = wasmModule({
      onRuntimeInitialized() {
        instance.sayHello();
      }
    });
    </script>

(以下是包含所有檔案的gist)。

如要建構所有項目，請執行

$ npm install
$ npm run build
$ npm run serve

前往 localhost:8080 後，DevTools 控制台中應會顯示以下輸出內容：

開發人員工具顯示透過 C++ 和 Emscripten 列印的訊息。

將 C/C++ 程式碼新增為依附元件

如果您想為網頁應用程式建構 C/C++ 程式庫，則需要將其程式碼納入專案。您可以手動將程式碼新增至專案的存放區，也可以使用 npm 來管理這類依附元件。假設我想在我的網路應用程式中使用 libvpx。libvpx 是用於以 VP8 編碼圖片的 C++ 程式庫，.webm 檔案中使用的轉碼器。不過，libvpx 不在 npm 上，也沒有 package.json，因此我無法直接使用 npm 安裝它。

為瞭解決這個難題，我們推出了 napa。napa 可讓您將任何 git 存放區網址當做依附元件，安裝至 node_modules 資料夾。

安裝 napa 做為依附元件：

$ npm install --save napa

並確保以安裝指令碼的形式執行 napa：

{
// ...
"scripts": {
    "install": "napa",
    // ...
},
"napa": {
    "libvpx": "git+https://github.com/webmproject/libvpx"
}
// ...
}

執行 npm install 時，napa 會將 libvpx GitHub 存放區複製到 node_modules，並以 libvpx 為名稱。

您現在可以擴充建構指令碼來建構 libvpx。libvpx 會使用 configure 和 make 進行建構。幸好，Emscripten 可確保 configure 和 make 使用 Emscripten 的編譯器。為此，我們提供包裝函式指令 emconfigure 和 emmake：

# ... above is unchanged ...
echo "============================================="
echo "Compiling libvpx"
echo "============================================="
(
    rm -rf build-vpx || true
    mkdir build-vpx
    cd build-vpx
    emconfigure ../node_modules/libvpx/configure \
    --target=generic-gnu
    emmake make
)
echo "============================================="
echo "Compiling libvpx done"
echo "============================================="

echo "============================================="
echo "Compiling wasm bindings"
echo "============================================="
# ... below is unchanged ...

C/C++ 程式庫會分成兩個部分：定義程式庫公開的資料結構、類別、常數等的標頭 (傳統上為 .h 或 .hpp 檔案)，以及實際的程式庫 (傳統上為 .so 或 .a 檔案)。如要在程式碼中使用程式庫的 VPX_CODEC_ABI_VERSION 常數，您必須使用 #include 陳述式加入程式庫的標頭檔案：

#include "vpxenc.h"
#include <emscripten/bind.h>

int say_hello() {
    printf("Hello from your wasm module with libvpx %d\n", VPX_CODEC_ABI_VERSION);
    return 0;
}

問題是編譯器不知道要在哪裡尋找 vpxenc.h。這就是 -I 旗標的用途。它會告訴編譯器要檢查哪些目錄的標頭檔案。此外，您還需要將實際的程式庫檔案提供給編譯器：

# ... above is unchanged ...
echo "============================================="
echo "Compiling wasm bindings"
echo "============================================="
(
    # Compile C/C++ code
    emcc \
    ${OPTIMIZE} \
    --bind \
    -s STRICT=1 \
    -s ALLOW_MEMORY_GROWTH=1 \
    -s ASSERTIONS=0 \
    -s MALLOC=emmalloc \
    -s MODULARIZE=1 \
    -s EXPORT_ES6=1 \
    -o ./my-module.js \
    -I ./node_modules/libvpx \
    src/my-module.cpp \
    build-vpx/libvpx.a

# ... below is unchanged ...

如果現在執行 npm run build，您會發現該程序會建構新的 .js 和新的 .wasm 檔案，而示範頁面確實會輸出常數：

開發人員工具顯示透過 emscripten 列印的 libvpx ABI 版本。

您也會發現建構程序需要很長的時間。導致建構時間過長的原因可能不盡相同。以 libvpx 為例，每次執行建構指令時，即使原始檔案未變更，它也會為 VP8 和 VP9 編譯編碼器和解碼器，因此耗時很久。即使對 my-module.cpp 進行微幅變更，建構作業也需要很長的時間。在第一次建構 libvpx 後，保留其建構構件會非常有幫助。

其中一種做法就是使用環境變數。

# ... above is unchanged ...
eval $@

echo "============================================="
echo "Compiling libvpx"
echo "============================================="
test -n "$SKIP_LIBVPX" || (
    rm -rf build-vpx || true
    mkdir build-vpx
    cd build-vpx
    emconfigure ../node_modules/libvpx/configure \
    --target=generic-gnu
    emmake make
)
echo "============================================="
echo "Compiling libvpx done"
echo "============================================="
# ... below is unchanged ...

(以下是包含所有檔案的 Gist)。

eval 指令可讓我們將參數傳遞至建構指令碼，藉此設定環境變數。如果已設定 $SKIP_LIBVPX (為任何值)，test 指令會略過建構 libvpx。

您現在可以編譯模組，但略過重建 libvpx：

$ npm run build:emscripten -- SKIP_LIBVPX=1

自訂建構環境

有時程式庫需要使用其他工具才能建構。如果 Docker 映像檔提供的建構環境中缺少這些依附元件，您必須自行新增。舉例來說，假設您也想使用 doxygen 建構 libvpx 的說明文件。Doxygen 無法在 Docker 容器中使用，但您可以使用 apt 安裝。

如果您在 build.sh 中執行此操作，每次要建構程式庫時，都必須重新下載及安裝 Doxygen。這不僅會造成浪費，也會讓您無法在離線時處理專案。

因此，建議您自行建構 Docker 映像檔。建構 Docker 映像檔時，您必須編寫 Dockerfile 來說明建構步驟。Dockerfile 相當強大，且有許多指令，但大多數情況下，您只需使用 FROM、RUN 和 ADD 即可。在這種情況下：

FROM trzeci/emscripten

RUN apt-get update && \
    apt-get install -qqy doxygen

您可以使用 FROM 宣告要使用的 Docker 映像檔，做為起點。我選擇 trzeci/emscripten 做為基礎，也就是您一直以來使用的圖片。使用 RUN 時，您會指示 Docker 在容器內執行殼層指令。這些指令對容器所做的任何變更，現在都會成為 Docker 映像檔的一部分。為確保 Docker 映像檔已建構，並且在執行 build.sh 前可供使用，您必須稍微調整 package.json：

{
    // ...
    "scripts": {
    "build:dockerimage": "docker image inspect -f '.' mydockerimage || docker build -t mydockerimage .",
    "build:emscripten": "docker run --rm -v $(pwd):/src mydockerimage ./build.sh",
    "build": "npm run build:dockerimage && npm run build:emscripten && npm run build:app",
    // ...
    },
    // ...
}

(以下是包含所有檔案的 Gist)。

這會建構 Docker 映像檔，但前提是該映像檔尚未建構。接著，所有項目都會照常執行，但現在建構環境會提供 doxygen 指令，這會導致 libvpx 的說明文件也一併建構。

結論

C/C++ 程式碼和 npm 不相容，這一點並不令人意外，但您可以透過一些額外工具和 Docker 提供的隔離功能，讓兩者搭配運作。這項設定並非適用於所有專案，但可做為起點，您可以視需求進行調整。如果有改善方法，請與我們分享。

附錄：使用 Docker 映像檔層

另一個解決方法是使用 Docker 和 Docker 的智慧快取方法，封裝更多這類問題。Docker 會逐一執行 Dockerfile，並將每個步驟的結果指派給各自的映像檔。這些中間圖片通常稱為「圖層」。如果 Dockerfile 中的指令未變更，在重新建構 Dockerfile 時，Docker 實際上不會重新執行該步驟。而是重複使用上次建構圖片時的圖層。

先前，您必須採取一些措施，才能避免每次建構應用程式時都重新建構 libvpx。現在，您可以將 libvpx 的建構指令從 build.sh 移至 Dockerfile，以便使用 Docker 的快取機制：

FROM trzeci/emscripten

RUN apt-get update && \
    apt-get install -qqy doxygen git && \
    mkdir -p /opt/libvpx/build && \
    git clone https://github.com/webmproject/libvpx /opt/libvpx/src
RUN cd /opt/libvpx/build && \
    emconfigure ../src/configure --target=generic-gnu && \
    emmake make

(以下是包含所有檔案的 Gist)。

請注意，您需要手動安裝 git 並複製 libvpx，因為執行 docker build 時沒有綁定掛載點。因此，您不再需要使用 napa。