在 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.pyhello.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.NETSwift

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 的实现尚未可用。因此,我们选择了另一种实现方式,它使用 SharedArrayBufferAtomics 将同步 WASI API 映射到 VS Code 的异步 API。

该方法的工作原理如下:

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

这种方法唯一的困难是 SharedArrayBufferAtomics 要求站点是跨域隔离的,由于 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 核心工具(如 lscatdate 等)编译成 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 团队

编程愉快!