在 VS Code for the Web 中运行 WebAssembly

2023 年 6 月 5 日，作者：Dirk Bäumer

VS Code for the Web (https://vscode.dev) 已经发布一段时间了，我们的目标始终是支持在浏览器中完成完整的“编辑/编译/调试”周期。对于 JavaScript 和 TypeScript 等语言，这相对容易，因为浏览器自带 JavaScript 执行引擎。但对于其他语言来说，这就比较困难，因为我们必须能够执行（从而调试）这些代码。例如，要在浏览器中运行 Python 源代码，就需要一个能够运行 Python 解释器的执行引擎。这些语言运行时通常是用 C/C++ 编写的。

WebAssembly 是一种用于虚拟机的二进制指令格式。现代浏览器现已内置 WebAssembly 虚拟机，并且有多种工具链可以将 C/C++ 编译为 WebAssembly 代码。为了探索 WebAssembly 的潜力，我们决定采用一个用 C/C++ 编写的 Python 解释器，将其编译为 WebAssembly，并在 VS Code for the Web 中运行。幸运的是，Python 团队已经开始了将 CPython 编译为 WASM 的工作，我们很乐意在此基础上进行构建。探索成果可见下方的短视频。

Execute a Python file in VS Code for the Web

这看起来与在桌面版 VS Code 中执行 Python 代码没什么不同。那么，这有什么酷的地方呢？

Python 源代码（app.py 和 hello.py）托管在 GitHub 仓库中，并直接从 GitHub 读取。Python 解释器可以完全访问工作区中的文件，但不能访问其他任何文件。
示例代码包含多个文件。app.py 依赖于 hello.py。
输出结果会很好地显示在 VS Code 的终端中。
你可以运行 Python REPL 并与其进行完全交互。
当然，它是在 Web 上运行的。

此外，编译为 WebAssembly (WASM) 代码的 Python 解释器无需任何修改即可在 VS Code for the Web 中运行。其二进制文件与 CPython 团队创建的完全一致。

它是如何工作的？

WebAssembly 虚拟机并不像 Java 或 .NET 那样自带 SDK。因此，开箱即用的 WebAssembly 代码无法打印到控制台或读取文件内容。WebAssembly 规范定义的是 WebAssembly 代码如何调用运行虚拟机的宿主中的函数。对于 VS Code for the Web 而言，宿主就是浏览器。因此，虚拟机可以调用在浏览器中执行的 JavaScript 函数。

Python 团队提供了两种版本的解释器 WebAssembly 二进制文件：一种使用 emscripten 编译，另一种使用 WASI SDK 编译。尽管它们都生成 WebAssembly 代码，但作为宿主实现所提供的 JavaScript 函数特性有所不同。

emscripten - 特别关注 Web 平台和 Node.js。除了生成 WASM 代码外，它还会生成 JavaScript 代码，作为宿主在浏览器或 Node.js 环境中执行 WASM 代码。例如，该 JavaScript 代码提供了一个函数，用于将 C 语言 printf 语句的内容打印到浏览器的控制台。
WASI SDK - 将 C/C++ 代码编译为 WASM，并假定存在符合 WASI 规范的宿主实现。WASI 代表 WebAssembly 系统接口 (WebAssembly System Interface)。它定义了一些类似操作系统的功能，包括文件和文件系统、套接字、时钟和随机数。使用 WASI SDK 编译 C/C++ 代码只会生成 WebAssembly 代码，而不会生成任何 JavaScript 函数。打印 C 语言 printf 语句内容所需的 JavaScript 函数必须由宿主提供。例如，Wasmtime 就是一个提供 WASI 宿主实现并将 WASI 连接到操作系统调用的运行时。

对于 VS Code，我们决定支持 WASI。尽管我们的主要重点是在浏览器中执行 WASM 代码，但我们实际上并非在纯浏览器环境中运行它。我们必须在 VS Code 的扩展宿主 (Extension Host) 工作线程中运行 WebAssembly，因为这是扩展 VS Code 的标准方式。除了浏览器的 Worker API 外，扩展宿主工作线程还提供了完整的 VS Code 扩展 API。因此，我们不是将 C/C++ 程序中的 printf 调用连接到浏览器的控制台，而是将其连接到 VS Code 的终端 (Terminal) API。在 WASI 中实现这一点比在 emscripten 中更容易。

我们目前对 VS Code WASI 宿主的实现基于 WASI 快照预览版 1，本博文描述的所有实现细节均指该版本。

我该如何运行自己的 WebAssembly 代码？

在 Python 于 VS Code for the Web 中成功运行后，我们很快意识到这种方法允许我们执行任何可以编译为 WASI 的代码。因此，本节将演示如何使用 WASI SDK 将一个小型的 C 程序编译为 WASI，并在 VS Code 的扩展宿主内部执行它。该示例假设读者熟悉 VS Code 扩展 API 并知道如何为 VS Code for the Web 编写扩展。

我们运行的 C 程序是一个简单的“Hello World”程序，代码如下：

#include <stdio.h>

int main(void)
{
    printf("Hello, World\n");
    return 0;
}

假设你已安装最新的 WASI SDK 并将其添加到 PATH 中，可以使用以下命令编译该 C 程序：

clang hello.c -o ./hello.wasm

这会在 hello.c 文件旁边生成一个 hello.wasm 文件。

VS Code 通过扩展添加新功能，在将 WebAssembly 集成到 VS Code 时，我们也遵循同样的模型。我们需要定义一个扩展来加载并运行 WASM 代码。扩展 package.json 清单中的关键部分如下：

{
    "name": "...",
    ...,
    "extensionDependencies": [
        "ms-vscode.wasm-wasi-core"
    ],
    "contributes": {
        "commands": [
            {
                "command": "wasm-c-example.run",
                "category": "WASM Example",
                "title": "Run C Hello World"
            }
        ]
    },
    "devDependencies": {
        "@types/vscode": "1.77.0",
    },
    "dependencies": {
        "@vscode/wasm-wasi": "0.11.0-next.0"
    }
}

ms-vscode.wasm-wasi-core 扩展提供了 WebAssembly 执行引擎，将 WASI API 连接到 VS Code API。Node 模块 @vscode/wasm-wasi 提供了一个用于在 VS Code 中加载和运行 WebAssembly 代码的门面 (facade)。

以下是加载和运行 WebAssembly 代码的实际 TypeScript 代码：

import { Wasm } from '@vscode/wasm-wasi';
import { commands, ExtensionContext, Uri, window, workspace } from 'vscode';

export async function activate(context: ExtensionContext) {
  // Load the WASM API
  const wasm: Wasm = await Wasm.load();

  // Register a command that runs the C example
  commands.registerCommand('wasm-wasi-c-example.run', async () => {
    // Create a pseudoterminal to provide stdio to the WASM process.
    const pty = wasm.createPseudoterminal();
    const terminal = window.createTerminal({
      name: 'Run C Example',
      pty,
      isTransient: true
    });
    terminal.show(true);

    try {
      // Load the WASM module. It is stored alongside the extension's JS code.
      // So we can use VS Code's file system API to load it. Makes it
      // independent of whether the code runs in the desktop or the web.
      const bits = await workspace.fs.readFile(
        Uri.joinPath(context.extensionUri, 'hello.wasm')
      );
      const module = await WebAssembly.compile(bits);
      // Create a WASM process.
      const process = await wasm.createProcess('hello', module, { stdio: pty.stdio });
      // Run the process and wait for its result.
      const result = await process.run();
      if (result !== 0) {
        await window.showErrorMessage(`Process hello ended with error: ${result}`);
      }
    } catch (error) {
      // Show an error message if something goes wrong.
      await window.showErrorMessage(error.message);
    }
  });
}

下方视频展示了该扩展在 VS Code for the Web 中的运行情况。

Run Hello World

我们将 C/C++ 代码作为 WebAssembly 的源，且由于 WASI 是一项标准，还有其他工具链也支持 WASI。例如：Rust、.NET 或 Swift。

VS Code 的 WASI 实现

WASI 和 VS Code API 共享文件系统或标准输入输出（如终端）等概念。这使我们能够在 VS Code API 之上实现 WASI 规范。然而，不同的执行行为是一个挑战：WebAssembly 代码的执行是同步的（例如，一旦 WebAssembly 开始执行，JavaScript 工作线程就会阻塞，直到执行完成），而 VS Code 和浏览器的大部分 API 是异步的。例如，在 WASI 中读取文件是同步的，而对应的 VS Code API 是异步的。这种特性给在 VS Code 扩展宿主工作线程中执行 WebAssembly 代码带来了两个问题：

我们需要防止扩展宿主在执行 WebAssembly 代码时被阻塞，因为这会阻止其他扩展的执行。
需要一种机制，在异步的 VS Code 和浏览器 API 之上实现同步的 WASI API。

第一个问题很容易解决：我们在单独的工作线程中运行 WebAssembly 代码。第二个问题更难解决，因为将同步代码映射到异步代码需要挂起同步执行的线程，并在异步计算出的结果可用时将其恢复。WebAssembly 的 JavaScript-Promise 集成提案解决了 WASM 层面的这个问题，且 V8 中有一个该提案的实验性实现。然而，当我们开始这项工作时，V8 实现尚未发布。因此，我们选择了另一种实现方式，即使用 SharedArrayBuffer 和 Atomics 将同步的 WASI API 映射到 VS Code 的异步 API 上。

该方法的实现步骤如下：

WASM 工作线程创建一个 SharedArrayBuffer，其中包含有关应在 VS Code 端调用的代码的必要信息。
它将共享内存发布到 VS Code 的扩展宿主工作线程，然后使用 Atomics.wait 等待扩展宿主工作线程完成其工作。
扩展宿主工作线程接收消息，调用相应的 VS Code API，将结果写回 SharedArrayBuffer，然后使用 Atomics.store 和 Atomics.notify 通知 WASM 工作线程唤醒。
随后，WASM 工作线程从 SharedArrayBuffer 中读取任何结果数据，并将其返回给 WASI 回调。

这种方法唯一的难点在于 SharedArrayBuffer 和 Atomics 要求站点是跨域隔离 (cross-origin isolated) 的，而由于 CORS 的广泛性，这本身可能就是一项艰巨的工作。这就是为什么目前它仅在 Insiders 版本 insiders.vscode.dev 上默认启用，而在 vscode.dev 上必须使用查询参数 ?vscode-coi=on 才能启用的原因。

下方的图表详细展示了上述编译为 WebAssembly 的 C 程序中，WASM 工作线程与扩展宿主工作线程之间的交互。橙色框中的代码是 WebAssembly 代码，所有绿色框中的代码都在 JavaScript 中运行。黄色框表示 SharedArrayBuffer。

Interaction between the WASM worker and the extension host

Web Shell

既然我们已经能够将 C/C++ 和 Rust 代码编译为 WebAssembly 并将其在 VS Code 中执行，我们便探索了是否也能在 VS Code for the Web 中运行 Shell。

我们研究了将其中一个 Unix Shell 编译为 WebAssembly 的可能性。然而，一些 Shell 依赖于操作系统功能（如派生进程等），而这些功能目前在 WASI 中尚不可用。这使我们采取了略有不同的方法：我们用 TypeScript 实现了一个基础 Shell，并尝试只将 ls、cat、date 等 Unix 核心工具编译为 WebAssembly。由于 Rust 对 WASM 和 WASI 有非常好的支持，我们尝试了 uutils/coreutils，它是 GNU coreutils 在 Rust 中的跨平台重新实现。Et voilà，我们拥有了第一个最小化的 Web Shell。

A web shell

如果无法执行自定义的 WebAssembly 或命令，Shell 的功能将非常有限。为了扩展 Web Shell，其他扩展可以贡献额外的文件系统挂载点，以及在 Web Shell 中输入时调用的命令。通过命令进行的间接寻址，将具体的 WebAssembly 执行与在终端中输入的内容分离开来。从一开始就在 Python 扩展中使用此支持，让你只需在提示符下输入 python app.py，或者列出默认安装在 /usr/local/lib/python3.11 下的 Python 3.11 库，即可直接在 Shell 中执行 Python 代码。

Python integration into web shell

接下来是什么？

WASM 执行引擎扩展和 Web Shell 扩展目前均处于实验性预览阶段，不应直接用于实现生产级的 WebAssembly 扩展。我们公开发布它们是为了获得关于该技术的早期反馈。如果你有任何问题或反馈，请在相应的 vscode-wasm GitHub 仓库中提出 Issue。该仓库还包含 Python 示例，以及 WASM 执行引擎和 Web Shell 的源代码。

我们确定将会进一步探索以下主题：

WASI 团队正在制定规范的 preview2 和 preview3 版本，我们也计划提供支持。新版本将改变 WASI 宿主的实现方式。不过，我们有信心能保持我们在 WASM 执行引擎扩展中暴露的 API 基本稳定。
还有 WASIX 项目，它通过进程或 futex 等附加的类似操作系统功能扩展了 WASI。我们将继续关注这项工作。
许多 VS Code 的语言服务器是用 JavaScript 或 TypeScript 以外的语言实现的。我们计划探索将这些语言服务器编译为 wasm32-wasi 并在 VS Code for the Web 中运行的可能性。
改进 Web 上 Python 的调试功能。我们已经着手进行这项工作，请保持关注。
增加支持，以便扩展 B 可以运行由扩展 A 提供的 WebAssembly 代码。例如，这将允许任意扩展通过重用贡献了 Python WebAssembly 的扩展来执行 Python 代码。
确保为 wasm32-wasi 编译的其他语言运行时能够在 VS Code 的 WebAssembly 执行引擎之上运行。VMware Labs 提供了 Ruby 和 PHP 的 wasm32-wasi 二进制文件，两者都可以在 VS Code 中运行。

谢谢，

Dirk 和 VS Code 团队

编码愉快！