Skip to main content

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는 먼저 전체 인자에서 global option을 스캔한 뒤, 남은 인자로 <command>를 해석합니다.

즉 global option은 위치가 유연합니다.

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

위 3개는 모두 유효합니다.

--를 사용하면 그 뒤는 global option 스캔을 멈추고 command 영역으로 넘깁니다.

wavec -- run main.wave

3. Commands​

3.1 run <file>​

Wave 파일을 컴파일하고 실행합니다.

wavec run hello.wave

동작:

  1. 소스 파싱 + import 확장
  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를 사용할 때는 오브젝트 경로를 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. Global Options​

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가지로 분기됩니다.

  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 2세그먼트 필요

패키지 루트 결정 순서:

  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