在 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,我们也很高兴能借用他们的成果。这项探索的结果可以在下面的短视频中看到:
它看起来与在 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 网页版中运行的情况。
我们使用 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
。
一个网页 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。
如果不能执行自定义的 WebAssembly 或命令,shell 的功能将非常有限。为了扩展网页 shell,其他扩展可以为文件系统贡献额外的挂载点,以及当命令输入到网页 shell 中时被调用的命令。通过命令的间接性将具体的 WebAssembly 执行与在终端中输入的内容解耦。从一开始就在 Python 扩展中使用此支持,您可以直接在 shell 中通过在提示符下输入 python app.py
来执行 Python 代码,或者列出通常挂载在 /usr/local/lib/python3.11
下的默认 Python 3.11 库。
接下来是什么?
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 团队
编程愉快!