跳到主要内容
Wave
GitHub

wavec CLI参考

本文详述了基于当前Wave编译器(wavec)实现标准的CLI操作。

核心原则：

  • wavec是编译器。
  • 包的安装/解决（lockfile、registry、下载）不属于wavec的责任。
  • 外部依赖通过执行wavec时的显式CLI参数传递。

1. 基本格式​

wavec [global-options] <command> [command-options]

例如：

wavec -O2 run main.wave
wavec build app.wave --link ssl -L ./native/lib
wavec run app.wave --dep-root .vex/dep

2. 命令解析规则（重要）​

wavec首先扫描所有参数中的全局选项，然后解释剩余参数为<command>。

即全局选项的位置是灵活的。

wavec -O3 run main.wave
wavec run main.wave -O3
wavec run -O3 main.wave

以上三个都是有效的。

使用--后，将停止全局选项扫描并转到命令区域。

wavec -- run main.wave

3. 命令​

3.1 run <file>​

编译并运行Wave文件。

wavec run hello.wave

操作：

  1. 源解析 + 导入扩展
  2. 生成LLVM IR
  3. 本机二进制链接（target/<file_stem>）
  4. 执行

特点:

  • 执行的程序的退出代码由wavec传递。

3.2 build <file>​

生成可执行文件(exe)。

wavec build app.wave

输出二进制文件:

  • target/<file_stem>

3.3 build选项(-o, -c)​

build命令可以用选项控制输出文件名和格式。

wavec build app.wave -o ./bin/app
wavec build app.wave -c
wavec build app.wave -c -o ./build/app.o
  • -o <file>: 指定输出文件名。
    • 默认（无-c）：指定可执行文件输出路径
    • 与-c一起：指定目标文件输出路径
  • -c：省略链接，仅生成目标文件。
  • 使用-c时，将目标路径输出到标准输出。

默认操作:

  • wavec build app.wave -> target/app
  • wavec build app.wave -c -> target/app.o（路径输出）

独立内核对象示例：

wavec --llvm \
  --target=x86_64-unknown-none-elf \
  build kernel.wave --emit=obj --freestanding -o kernel.o

aarch64-unknown-none-elf, riscv64-unknown-none-elf也可以以同样的方式使用。

3.4 install std, update std​

标准库安装/更新命令。

wavec install std
wavec update std

3.5 --help, --version​

wavec --help
wavec --version

4. 全局选项​

4.1 优化​

允许值:

  • -O0
  • -O1
  • -O2
  • -O3
  • -Os
  • -Oz
  • -Ofast

例如：

wavec -O3 run main.wave

4.2 调试输出​

wavec --debug-wave=tokens,ast,ir run main.wave

允许项目:

  • tokens
  • ast
  • ir
  • mc
  • hex
  • all

4.3 链接选项​

wavec build app.wave --link ssl --link crypto -L ./native/lib
  • --link=<lib> 或 --link <lib>
  • -L<path> 或 -L <path>

wavec在链接时内部传递为-l<lib>、-L<path>形式。

4.4 外部依赖选项（重要）​

用于外部import(pkg::...)解析的选项。

--dep-root <dir>​

添加包根目录候选项。

wavec run app.wave --dep-root .vex/dep

寻找包math时：

  • 检查.vex/dep/math

可以多次指定：

wavec run app.wave --dep-root .vex/dep --dep-root ./vendor/dep

--dep <name>=<path>​

将包名固定到特定路径。

wavec run app.wave --dep math=.vex/dep/math

规则：

  • name格式：[A-Za-z_][A-Za-z0-9_]*
  • --dep必须是name=path格式
  • 重复指定相同包名会导致错误

4.5 后端选项（--llvm，--whale）​

后端控制选项仅在--llvm之后解析。

wavec --llvm --target=x86_64-unknown-linux-gnu build app.wave -c

支持项目（摘要）：

  • --target, --cpu, --features, --abi
  • --sysroot
  • -C linker=<path>
  • -C link-arg=<arg>（可重复）
  • -C link-sysroot=<path>
  • -C no-default-libs

当前 wavec print target-list 的主要目标：

  • x86_64-unknown-linux-gnu
  • aarch64-unknown-linux-gnu
  • x86_64-apple-darwin
  • aarch64-apple-darwin
  • x86_64-unknown-none-elf
  • aarch64-unknown-none-elf
  • riscv64-unknown-none-elf

--whale目前是预留的虚设标志，实际的后端流水线尚未实现（TODO）。

5. Import解析规则​

Wave import分为以下三种：

  1. 本地import
  2. std import
  3. 外部包import

5.1 本地​

import("foo");
import("path/to/mod.wave");

从基准文件目录中查找<path>.wave。

5.2 std​

import("std::io::format");

使用路径~/.wave/lib/wave/std/...。

5.3 外部包​

import("math::add");
import("json::parser::core");

格式：

  • 至少需要package::module两段

包根决定顺序：

  1. --dep name=path明确映射
  2. 从每个--dep-root搜索<root>/<package>

如果在多个dep-root中同时发现相同的包：

  • 不自动选择，产生歧义错误
  • 必须用--dep name=path固定

模块文件探索顺序：

  1. <package_root>/<module_path>.wave
  2. <package_root>/src/<module_path>.wave

例如：

import("math::core::vec");

探索：

  • <package_root>/core/vec.wave
  • <package_root>/src/core/vec.wave

6. 外部import实际示例​

6.1 单一dep-root​

目录：

.vex/dep/
  math/
    src/
      add.wave
main.wave

代码：

import("math::add");

执行:

wavec run main.wave --dep-root .vex/dep

6.2 消除歧义​

wavec run main.wave \
  --dep-root .vex/dep \
  --dep-root ./vendor/dep

两者都有math时会出错。 如下面那样固定。

wavec run main.wave \
  --dep-root .vex/dep \
  --dep-root ./vendor/dep \
  --dep math=./vendor/dep/math

7. 与Vex的角色分离​

推荐结构：

  • wavec: 编译/链接/执行 + 指定的依赖解析
  • vex: 安装/管理依赖后 wavec ... --dep-root ... --dep ... 调用

例如：

# 在内部，vex 确实
wavec run main.wave --dep-root .vex/dep --dep math=.vex/dep/math

此模式保持编译器简单和确定，由包管理器负责自动化。

8. 快速参考​

wavec run main.wave
wavec build app.wave
wavec build app.wave -o ./bin/app
wavec build app.wave -c
wavec build app.wave -c -o ./build/app.o
wavec run main.wave --debug-wave=tokens,ast
wavec build app.wave --link ssl -L ./native/lib
wavec run main.wave --dep-root .vex/dep
wavec run main.wave --dep math=.vex/dep/math
wavec --llvm --target=x86_64-unknown-linux-gnu build app.wave -c
wavec --whale build app.wave -c # TODO: reserved, not implemented