在 Web 版 VS Code 中运行 WebAssemblies
2023 年 6 月 5 日，作者：Dirk Bäumer
Web 版 VS Code (https://vscode.dev) 已经推出一段时间了，我们一直以在浏览器中支持完整的编辑 / 编译 / 调试周期为目标。对于 JavaScript 和 TypeScript 等语言来说，这相对容易，因为浏览器内置了 JavaScript 执行引擎。对于其他语言则较难，因为我们必须能够执行（并因此进行调试）代码。例如，要在浏览器中运行 Python 源代码，就需要一个能够运行 Python 解释器的执行引擎。这些语言运行时通常是用 C/C++ 编写的。
WebAssembly 是一种用于虚拟机的二进制指令格式。如今，WebAssembly 虚拟机已内置于现代浏览器中，并且存在可将 C/C++ 编译为 WebAssembly 代码的工具链。为了了解 WebAssembly 当前的可能性，我们决定采用用 C/C++ 编写的 Python 解释器，将其编译为 WebAssembly，并在 Web 版 VS Code 中运行。幸运的是，Python 团队已经开始着手将 CPython 编译为 WASM，我们也很乐意借力于他们的努力。探索的成果可以在下面的短视频中看到
这看起来与在 VS Code 桌面版中执行 Python 代码没什么不同。那么，这为什么很酷呢？
- Python 源代码（
app.py和hello.py）托管在 GitHub 仓库中，并直接从 GitHub 读取。Python 解释器可以完全访问工作区中的文件，但不能访问任何其他文件。 - 示例代码是多文件代码。
app.py依赖于hello.py。 - 输出在 VS Code 的终端中清晰显示。
- 你可以运行 Python REPL 并与其完全交互。
- 当然，它**运行**在 Web 上。
此外，编译为 WebAssembly (WASM) 代码的 Python 解释器无需修改即可在 Web 版 VS Code 中运行。这些二进制文件与 CPython 团队创建的完全相同。
它是如何工作的？
WebAssembly 虚拟机不附带 SDK（例如 Java 或 .NET）。因此，WebAssembly 代码开箱即用无法打印到控制台或读取文件内容。WebAssembly 规范定义的是 WebAssembly 代码如何调用运行虚拟机的宿主中的函数。在 Web 版 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 系统接口。它定义了许多类似操作系统的特性，包括文件和文件系统、套接字、时钟和随机数。使用 WASI SDK 编译 C/C++ 代码只会生成 WebAssembly 代码，而不会生成任何 JavaScript 函数。将 C
printf语句的内容打印到控制台所需的 JavaScript 函数必须由宿主提供。Wasmtime 例如，就是一个提供 WASI 宿主实现的运行时，它将 WASI 连接到操作系统调用。
对于 VS Code，我们决定支持 WASI。尽管我们的主要重点是在浏览器中执行 WASM 代码，但我们实际上并非在纯粹的浏览器环境中运行它。我们必须在 VS Code 的扩展宿主工作线程中运行 WebAssemblies，因为这是扩展 VS Code 的标准方式。扩展宿主工作线程除了提供浏览器的 worker API 外，还提供完整的 VS Code 扩展 API。因此，我们并非将 C/C++ 程序中的 printf 调用连接到浏览器控制台，而是希望将其连接到 VS Code 的 终端 API。在 WASI 中实现这一点比在 emscripten 中更容易。
我们目前对 VS Code 的 WASI 宿主实现是基于 WASI 快照 preview1 的，本博客文章中描述的所有实现细节都指的是该版本。
如何运行我自己的 WebAssembly 代码？
在 Python 能够在 Web 版 VS Code 中运行后，我们很快意识到我们采取的方法允许我们执行任何可以编译到 WASI 的代码。因此，本节演示了如何使用 WASI SDK 将一个小的 C 程序编译到 WASI 并在 VS Code 的扩展宿主中执行。示例假定读者熟悉 VS Code 的扩展 API 并知道如何为 Web 版 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 中，我们在将 WebAssemblies 集成到 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 扩展提供了将 WASI API 连接到 VS Code API 的 WebAssembly 执行引擎。Node 模块 @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);
}
});
}
下面的视频展示了该扩展在 Web 版 VS Code 中运行。
我们使用 C/C++ 代码作为 WebAssembly 的源，并且由于 WASI 是一个标准，因此还有其他支持 WASI 的工具链。例如：Rust、.NET 或 Swift。
VS Code 的 WASI 实现
WASI 和 VS Code API 共享文件系统或 stdio（例如终端）等概念。这使我们能够在 VS Code API 之上实现 WASI 规范。然而，不同的执行行为是一个挑战：WebAssembly 代码执行是同步的（例如，一旦 WebAssembly 执行开始，JavaScript worker 将被阻塞直到执行完成），而 VS Code 和浏览器的大部分 API 是异步的。例如，在 WASI 中从文件中读取是同步的，而相应的 VS Code API 是异步的。这个特性给 WebAssembly 代码在 VS Code 扩展宿主工作线程中的执行带来了两个问题
- 我们需要防止扩展宿主在执行 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。
一个 Web Shell
既然我们能够将 C/C++ 和 Rust 代码编译为 WebAssembly 并在 VS Code 中执行，我们还探索了是否也能在 Web 版 VS Code 中运行 Shell。
我们研究了将其中一个 Unix Shell 编译为 WebAssembly 的可能性。然而，一些 Shell 依赖于操作系统特性（如生成进程等），这些特性目前在 WASI 中不可用。这导致我们采取了稍有不同的方法：我们用 TypeScript 实现了一个基本的 Shell，并尝试仅将诸如 ls、cat、date 等 Unix 核心工具编译为 WebAssembly。由于 Rust 对 WASM 和 WASI 有很好的支持，我们尝试了 uutils/coreutils，这是一个用 Rust 重新实现的跨平台 GNU coreutils。Et voilà，我们有了一个最初的最小 Web Shell。
如果无法执行自定义 WebAssemblies 或命令，Shell 的功能将非常有限。为了扩展 Web Shell，其他扩展可以为文件系统贡献额外的挂载点以及在 Web Shell 中输入时调用的命令。通过命令进行的间接调用将具体的 WebAssembly 执行与终端中输入的内容解耦。从一开始就在 Python 扩展中使用此支持，你可以通过在提示符中输入 python app.py 或列出通常挂载在 /usr/local/lib/python3.11 下的默认 python 3.11 库，直接在 Shell 中执行 Python 代码。
接下来是什么？
WASM 执行引擎扩展和 Web Shell 扩展都处于实验性预览阶段，不应将其用于实现生产环境就绪的 WebAssemblies 扩展。它们已公开发布以获取有关该技术的早期反馈。如果您有任何问题或反馈，请在相应的 vscode-wasm GitHub 仓库中提出 issue。该仓库还包含 Python 示例、WASM 执行引擎 和 Web Shell 的源代码。
我们知道我们将进一步探索以下主题
- WASI 团队正在开发规范的 preview2 和 preview3 版本，我们也计划支持它们。新版本将改变 WASI 宿主的实现方式。然而，我们相信我们可以使 WASM 执行引擎扩展中暴露的 API 大部分保持稳定。
- 此外，还有 WASIX 的工作，它用进程或 futex 等额外的 类似操作系统的特性 扩展了 WASI。我们将继续关注这项工作。
- 许多用于 VS Code 的语言服务器是用 JavaScript 或 TypeScript 以外的语言实现的。我们计划探索将这些语言服务器编译到
wasm32-wasi并在 Web 版 VS Code 中运行的可能性。 - 改进 Web 上的 Python 调试。我们已经开始着手这项工作，敬请期待。
- 添加支持，使扩展 B 可以运行扩展 A 贡献的 WebAssembly 代码。例如，这将允许任意扩展通过重用贡献了 Python WebAssembly 的扩展来执行 Python 代码。
- 确保为
wasm32-wasi编译的其他语言运行时能够在 VS Code 的 WebAssembly 执行引擎之上运行。VMware Labs 提供了 Ruby 和 PHP 的wasm32-wasi二进制文件，它们都能在 VS Code 中运行。
谢谢，
Dirk 和 VS Code 团队
编码愉快！