Emscripten 和 npm

如何将 WebAssembly 集成到此设置中?在本文中,我们将以 C/C++ 和 Emscripten 为例来解决此问题。

WebAssembly (wasm) 通常被视为一种性能基元或一种在 Web 上运行现有 C++ 代码库的方法。通过 squoosh.app,我们希望展示 WASM 至少还有第三种视角:利用其他编程语言的庞大生态系统。借助 Emscripten,您可以使用 C/C++ 代码,Rust 内置了 wasm 支持Go 团队也在努力实现这一点。我相信很快就会推出更多语言版本。

在这些场景中,wasm 不是应用的核心,而是一块拼图:又一个模块。您的应用已经包含 JavaScript、CSS、图片资源、以 Web 为中心的构建系统,甚至可能还包含 React 等框架。如何将 WebAssembly 集成到此设置中?在本文中,我们将以 C/C++ 和 Emscripten 为例来解决此问题。

在使用 Emscripten 时,我发现 Docker 非常有用。C/C++ 库通常会编写为与其所构建的操作系统配合使用。保持一致的环境非常有帮助。借助 Docker,您可以获得一个已设置为与 Emscripten 搭配使用的虚拟化 Linux 系统,其中已安装所有工具和依赖项。如果缺少某些内容,您只需安装即可,而无需担心这会对您自己的机器或其他项目产生什么影响。如果出现问题,请丢弃容器并重新开始。如果它能正常运行一次,您可以肯定它会继续正常运行并产生相同的结果。

Docker 注册表中有一个由 trzeci 创建的 Emscripten 映像,我一直在大量使用它。

与 npm 集成

在大多数情况下,Web 项目的入口点是 npm 的 package.json。按照惯例,大多数项目都可以使用 npm install && npm run build 构建。

通常,Emscripten 生成的 build 工件(一个 .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 会将 shell 置于“快速失败”模式。如果脚本中的任何命令返回错误,整个脚本都会立即中止。这非常有用,因为脚本的最后输出始终是成功消息或导致构建失败的错误。

您可以使用 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 中找到所有可用选项,但该文件可能非常庞大。下面列出了我认为对 Web 开发者最重要的 Emscripten 标志:

  • --bind 启用embind
  • -s STRICT=1 不再支持所有已废弃的 build 选项。这样可以确保您的代码以向前兼容的方式进行构建。
  • -s ALLOW_MEMORY_GROWTH=1 允许在必要时自动增长内存。在撰写本文时,Emscripten 最初会分配 16MB 的内存。当代码分配内存块时,此选项决定这些操作是否会在内存耗尽时导致整个 wasm 模块失败,或者是否允许粘合代码扩展总内存以适应分配。
  • -s MALLOC=... 会选择要使用的 malloc() 实现。emmalloc 是专门针对 Emscripten 的一种小巧且快速的 malloc() 实现。替代方案是 dlmalloc,这是一个完整的 malloc() 实现。只有在您频繁分配大量小对象或想要使用线程时,才需要改用 dlmalloc
  • -s EXPORT_ES6=1 会将 JavaScript 代码转换为具有可与任何打包器搭配使用的默认导出的 ES6 模块。此外,还需要设置 -s MODULARIZE=1

以下标志并不总是必需的,或者仅对调试有用:

  • -s FILESYSTEM=0 是一个与 Emscripten 相关的标志,可在您的 C/C++ 代码使用文件系统操作时为您模拟文件系统。它会对自己编译的代码进行一些分析,以决定是否在粘合代码中添加文件系统模拟。不过,有时此分析可能会出错,您需要为可能不需要的文件系统模拟支付 70KB 的额外粘合代码开销。借助 -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>

(下面是一个包含所有文件的代码段。)

如需构建所有内容,请运行

$ npm install
$ npm run build
$ npm run serve

导航到 localhost:8080 后,您应该会在 DevTools 控制台中看到以下输出:

开发者工具,其中显示了通过 C++ 和 Emscripten 输出的消息。

将 C/C++ 代码添加为依赖项

如果您想为 Web 应用构建 C/C++ 库,则需要将其代码添加到项目中。您可以手动将代码添加到项目的代码库中,也可以使用 npm 来管理这类依赖项。假设我想在 Web 应用中使用 libvpx。libvpx 是一个 C++ 库,用于使用 VP8(.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 代码库克隆到名为 libvpxnode_modules 中。

现在,您可以扩展构建脚本来构建 libvpx。libvpx 使用 configuremake 进行构建。幸运的是,Emscripten 可以帮助确保 configuremake 使用 Emscripten 的编译器。为此,提供了封装容器命令 emconfigureemmake

# ... 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 版本的 DevTools。

您还会注意到,构建过程需要很长时间。构建时间过长的原因可能不尽相同。对于 libvpx,构建过程需要很长时间,因为每次运行 build 命令时,它都会为 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 ...

(以下是包含所有文件的代码段。)

借助 eval 命令,我们可以通过将参数传递给构建脚本来设置环境变量。如果 $SKIP_LIBVPX 已设置(设为任何值),test 命令将跳过 libvpx 的构建。

现在,您可以编译模块,但跳过重新构建 libvpx:

$ npm run build:emscripten -- SKIP_LIBVPX=1

自定义构建环境

有时,库需要依赖于其他工具才能构建。如果 Docker 映像提供的构建环境中缺少这些依赖项,您需要自行添加这些依赖项。例如,假设您还想使用 doxygen 构建 libvpx 的文档。Docker 容器中不提供 Doxygen,但您可以使用 apt 进行安装。

如果您要在 build.sh 中执行此操作,则每次要构建库时都需要重新下载并重新安装 doxygen。这不仅会造成浪费,还会导致您无法在离线状态下处理项目。

在这种情况下,构建自己的 Docker 映像非常有用。通过编写用于描述构建步骤的 Dockerfile 来构建 Docker 映像。Dockerfile 非常强大,包含许多命令,但在大多数情况下,您只需使用 FROMRUNADD 即可。在此示例中:

FROM trzeci/emscripten

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

借助 FROM,您可以声明要用作起点的 Docker 映像。我选择了 trzeci/emscripten 作为基础映像,这是您一直在使用的映像。借助 RUN,您可以指示 Docker 在容器内运行 shell 命令。这些命令对容器所做的任何更改现在都属于 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",
    // ...
    },
    // ...
}

(以下是包含所有文件的代码段。)

这将构建您的 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

(以下是包含所有文件的代码段。)

请注意,您需要手动安装 git 并克隆 libvpx,因为您在运行 docker build 时没有绑定挂载。作为副作用,您无需再使用 Napa。