`wavec` CLI リファレンス

この文書は、現在のWaveコンパイラ（wavec）実装基準のCLI動作を詳細に説明します。

核心原則:

wavec はコンパイラです。
パッケージのインストール/解決（ロックファイル、レジストリ、ダウンロード）は wavec の責任ではありません。
外部依存性は wavec 実行時に 明示的CLI引数 で渡します。

1. 基本形式

wavec [グローバルオプション] <コマンド> [コマンドオプション]

例:

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

2. コマンド解析ルール（重要）

wavec は全体の引数から global option を最初にスキャンした後に、残りの引数で <command> を解釈します。

つまり、global option の位置は柔軟です。

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

上記の3つはすべて有効です。

-- を使用すると、その後は global option のスキャンを停止し、コマンド領域に渡します。

wavec -- run main.wave

3. コマンド

3.1 `run <file>`

Wave ファイルをコンパイルして実行します。

wavec run hello.wave

動作:

ソース解析 + インポート拡張
LLVM IR 生成
ネイティブバイナリリンク (target/<file_stem>)
実行

特徴:

実行されたプログラムの終了コードを 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 使用時はオブジェクトパスを stdout に出力します。

デフォルト動作:

wavec build app.wave -> target/app
wavec build app.wave -c -> target/app.o (パス出力)

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 no-default-libs

--whale은 현재 예약된 더미 플래그이며, 실제 백엔드 파이프라인은 아직 미구현(TODO)입니다.

5. Import解釈規則

Wave importは次の3つに分岐します。

ローカルimport
std import
外部パッケージ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 の2セグメントが必要

パッケージルートの決定順序：

--dep name=path の指定マッピング
各--dep-rootから<root>/<package>を検索

同じパッケージが複数のdep-rootで同時に発見された場合：

自動選択せずに曖昧さエラー
--dep name=pathで固定する必要があります

モジュールファイル探索順序：

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

例：

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

探索：

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

6. 外部インポート実践例

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

1. 基本形式​

2. コマンド解析ルール（重要）​

3. コマンド​

3.1 run <file>​

3.2 build <file>​

3.3 build オプション (-o, -c)​

3.4 install std, update std​

3.5 --help, --version​

4. グローバルオプション​

4.1 最適化​

4.2 デバッグ出力​

4.3 リンクオプション​

4.4 外部依存オプション（重要）​

--dep-root <dir>​

--dep <name>=<path>​

4.5 백엔드 옵션 (--llvm, --whale)​

5. Import解釈規則​

5.1 ローカル​

5.2 std​

5.3 外部パッケージ​

6. 外部インポート実践例​

6.1 単一dep-root​

6.2 曖昧さの解消​

7. Vexとの役割分担​

8. クイックリファレンス​