warpo 文档

简体中文

English

简体中文

English

Appearance

WARPO 配置文件（asconfig.json） ​

2.3.0stable

WARPO 编译器使用名为 asconfig.json 的配置文件来控制构建流程、指定入口文件，以及自定义输出选项。该文件必须是符合下述 schema 的合法 JSON 对象。

顶层结构 ​

json
{
	"$schema": "./node_modules/warpo/asconfig.schema.json",
	"entries": [ ... ],
	"options": { ... },
	"targets": { ... }
}
  • schema：asconfig.json 的预定义 schema。它位于 warpo 项目根目录。

    INFO

    指定用于描述配置文件结构与校验规则的 JSON Schema URI。这能帮助工具与编辑器基于 schema 做校验、自动补全与错误检查。

  • entries：要编译的入口 AssemblyScript 源文件数组。每一项是文件路径（string）。
  • options：全局编译选项（见下文）。
  • targets：将 target 名称映射到各自编译选项的对象（见下文）。

Options ​

Options 用于控制构建过程与输出。它们可以全局设置（options 字段下），也可以按 target 设置（targets 字段下）。 每个字段的详细描述请参考 schema。

use ​

use 对应 AssemblyScript 的 --use <name>=<value> 选项。

它支持两种写法：

json
{
  "use": { "NAME": "VALUE" }
}
json
{
  "use": ["NAME=VALUE"]
}

WebAssembly 与优化特性 ​

WARPO 通过统一的 feature 集合管理 WebAssembly 能力和可选编译器优化。 默认集合显式启用 mutable-globals、sign-extension、nontrapping-f2i、bulk-memory 和 multi-value。 tail-call 和 return-to-br 默认关闭，需要使用时显式开启。

在 asconfig.json 中，可以通过 enable 和 disable 控制特性：

json
{
  "options": {
    "enable": ["tail-call"],
    "disable": ["multi-value"]
  }
}

支持的特性名称：

  • mutable-globals
  • sign-extension
  • nontrapping-f2i
  • bulk-memory
  • multi-value
  • tail-call
  • return-to-br

等价 CLI 写法：

bash
warpo assembly/index.ts -o build/app.wasm --enable-feature tail-call --disable-feature multi-value

同一特性同时出现在两个选项中时，以 disable 为准。

return-to-br ​

启用 return-to-br 可以让多个返回路径共享 shadow-stack 恢复操作，但也可能引入新的 block。 对于缺少变量活跃性分析的后端编译器 (eg: wasm-compiler)，这类控制流可能触发保守的执行上下文保存与恢复，增加局部变量的暂存开销，从而导致性能下降。换句话说，如果后端能够识别出 br 的target最终是函数返回，就能避免overhead。

因此，该优化的实际收益取决于后端的分析与代码生成能力，建议在目标后端上通过基准测试评估。

host ​

2.4.0stable

用于选择编译器在导入（imports）层面要面向的 host API。默认值为 none。

支持的取值：

  • none：不假设任何 host API。
  • wasi_snapshot_preview1：使用 WASI Snapshot Preview 1 的 host imports。

另见：WASI Snapshot Preview 1 Host

可以在配置文件中设置：

json
{
  "options": {
    "host": "wasi_snapshot_preview1"
  }
}

也可以通过 CLI 设置：

bash
warpo assembly/index.ts -o build/app.wasm --host wasi_snapshot_preview1

initialMemory 与 maximumMemory ​

用于配置 WARPO 生成 WebAssembly 模块时的内存限制。

  • initialMemory：初始内存大小，单位是 WebAssembly page（每页 64KiB）。
  • maximumMemory：最大内存限制，支持可选单位后缀。

maximumMemory 支持：

  • 整数：按字节（bytes）解释。
  • 带单位字符串，例如：65536、64KiB、1MiB、2MB、3pages。

maximumMemory 的生效规则：

  • 若值小于一页（65536 字节），WARPO 会将其作为 lowMemoryLimit。
  • 若值大于等于一页，则必须是整页倍数，并以 page 数形式应用到 maximumMemory。

asconfig.json 示例：

json
{
  "options": {
    "initialMemory": 2,
    "maximumMemory": "64MiB"
  }
}

等价 CLI 写法：

bash
warpo assembly/index.ts -o build/app.wasm --initialMemory 2 --maximumMemory 64MiB

Targets ​

Targets 允许你定义多个构建配置（例如 debug、release）。每个 target 都是一个带有独立 options 的对象，用于覆盖全局 options。

示例：

json
"targets": {
	"release": {
		"debug": false,
		"optimizeLevel": 3,
		"shrinkLevel": 2
	},
	"debug": {
		"debug": true,
		"sourceMap": true
	}
}

示例配置 ​

json
{
  "entries": ["src/main.ts", "src/module.ts"],
  "options": {
    "exportStart": "main",
    "debug": true,
    "optimizeLevel": 0
  },
  "targets": {
    "release": {
      "debug": false,
      "optimizeLevel": 3,
      "shrinkLevel": 2
    },
    "debug": {
      "debug": true,
      "sourceMap": true
    }
  }
}

工作方式 ​

编译器会读取由 --config 命令行选项指定的 asconfig.json。它会先应用 options 字段中的选项。如果通过 --target 指定了 target，则会用 targets 中对应 target 的选项覆盖全局选项。最后，会应用额外的命令行选项（优先级最高）。

Tips ​

  • 使用 options 定义公共的编译配置。
  • 使用 targets 在不同构建配置间快速切换。