在 VS Code 中试用 ！

在 VS Code 网页版中运行 WebAssembly

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

VS Code 网页版 (https://vscode.dev) 已经推出一段时间了，我们一直以来的目标是在浏览器中支持完整的编辑/编译/调试循环。对于 JavaScript 和 TypeScript 等语言来说，这相对容易，因为浏览器本身就带有 JavaScript 执行引擎。但对于其他语言来说，就比较困难了，因为我们必须能够执行（并因此调试）代码。例如，要在浏览器中运行 Python 源代码，就需要一个能够运行 Python 解释器的执行引擎。这些语言运行时通常是用 C/C++ 编写的。

WebAssembly 是一种用于虚拟机的二进制指令格式。WebAssembly 虚拟机现在随现代浏览器一起发布，并且有工具链可以将 C/C++ 编译成 WebAssembly 代码。为了了解 WebAssembly 目前能做什么，我们决定将一个用 C/C++ 编写的 Python 解释器编译成 WebAssembly，并在 VS Code 网页版中运行它。幸运的是，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 并与其完全交互。
  • 当然，它也运行在网页上。

此外，编译成 WebAssembly (WASM) 代码的 Python 解释器无需修改即可在 VS Code 网页版中运行。这些二进制文件与 CPython 团队创建的完全一致。

它是如何工作的？

WebAssembly 虚拟机不附带 SDK（例如，像 Java 或 .NET 那样）。因此，WebAssembly 代码开箱即用无法打印到控制台或读取文件内容。WebAssembly 规范定义了 WebAssembly 代码如何调用运行虚拟机的宿主中的函数。对于 VS Code 网页版而言，宿主是浏览器。因此，虚拟机可以调用在浏览器中执行的 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 System Interface（WebAssembly 系统接口）。它定义了许多类似操作系统的功能，包括文件和文件系统、套接字、时钟和随机数。使用 WASI SDK 编译 C/C++ 代码只会生成 WebAssembly 代码，但不会生成任何 JavaScript 函数。打印 C printf 语句内容所需的 JavaScript 函数必须由宿主提供。Wasmtime 就是一个例子，它提供了一个 WASI 宿主实现，将 WASI 连接到操作系统调用。

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

我们目前实现的 VS Code WASI 宿主基于 WASI snapshot preview1，本篇博客文章中描述的所有实现细节均指该版本。

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

在 Python 成功运行于 VS Code 网页版之后，我们很快意识到所采用的方法允许我们执行任何可以编译为 WASI 的代码。因此，本节演示了如何使用 WASI SDK 将一个小型的 C 程序编译为 WASI，并在 VS Code 的扩展宿主中执行它。本示例假设读者熟悉 VS Code 的扩展 API，并了解如何为 VS Code 网页版 编写扩展。

我们运行的 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。@vscode/wasm-wasi 节点模块提供了一个门面，用于在 VS Code 中加载和运行 WebAssembly 代码。

以下是加载和运行 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 网页版中运行的情况。

Run Hello World

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

VS Code 的 WASI 实现

WASI 和 VS Code API 共享文件系统或标准 I/O（例如终端）等概念。这使我们能够在 VS Code API 的基础上实现 WASI 规范。然而，不同的执行行为是一个挑战：WebAssembly 代码执行是同步的（例如，一旦 WebAssembly 执行开始，JavaScript worker 就会被阻塞直到执行完成），而 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 要求站点是跨域隔离的，由于 CORS 的传染性很强，这本身可能就是一项艰巨的任务。这就是为什么它目前只在 Insiders 版本 insiders.vscode.dev 上默认启用，并且必须在 vscode.dev 上使用查询参数 ?vscode-coi=on 启用。

下图详细展示了 WASM 工作程序和扩展宿主工作程序之间，对于我们编译到 WebAssembly 的上述 C 程序而言的交互。橙色框中的代码是 WebAssembly 代码，绿色框中的所有代码都在 JavaScript 中运行。黄色框代表 SharedArrayBuffer。

Interaction between the WASM worker and the extension host

一个网页 Shell

既然我们能够将 C/C++ 和 Rust 代码编译成 WebAssembly 并在 VS Code 中执行，我们便开始探索是否也能在 VS Code 网页版中运行一个 shell。

我们研究了将一个 Unix shell 编译成 WebAssembly。然而，一些 shell 依赖于操作系统功能（例如，派生进程等），这些功能目前在 WASI 中尚不可用。这促使我们采取了略微不同的方法：我们用 TypeScript 实现了一个基本 shell，并尝试仅将 Unix 核心工具（如 ls、cat、date 等）编译成 WebAssembly。由于 Rust 对 WASM 和 WASI 有很好的支持，我们尝试了 uutils/coreutils，这是一个用 Rust 对 GNU coreutils 进行的跨平台重新实现。于是，我们得到了第一个最小的网页 shell。

A web shell

如果不能执行自定义的 WebAssembly 或命令，shell 的功能将非常有限。为了扩展网页 shell，其他扩展可以为文件系统贡献额外的挂载点，以及当命令输入到网页 shell 中时被调用的命令。通过命令的间接性将具体的 WebAssembly 执行与在终端中输入的内容解耦。从一开始就在 Python 扩展中使用此支持，您可以直接在 shell 中通过在提示符下输入 python app.py 来执行 Python 代码，或者列出通常挂载在 /usr/local/lib/python3.11 下的默认 Python 3.11 库。

Python integration into web shell

接下来是什么？

WASM 执行引擎扩展和网页 Shell 扩展都处于实验预览阶段，不应将其用于实现生产就绪的 WebAssembly 扩展。它们已公开发布，旨在获取有关该技术的早期反馈。如果您有任何问题或反馈，请在相应的 vscode-wasm GitHub 存储库中提出问题。此存储库还包含 Python 示例以及 WASM 执行引擎和 网页 Shell 的源代码。

我们已知的是，我们将进一步探索以下主题：

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

谢谢，

Dirk 和 VS Code 团队

编程愉快！