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
동작:
- 소스 파싱 + import 확장
- LLVM IR 생성
- 네이티브 바이너리 링크 (
target/<file_stem>) - 실행
특징:
- 실행된 프로그램의 종료 코드를
wavec가 전달합니다. run명령에서는 legacy 옵션으로--img만 허용됩니다.
wavec run --img boot.wave
3.2 img <file>
부트 이미지 빌드 + QEMU 실행 경로입니다.
wavec img boot.wave
3.3 build <file>
실행 파일(exe)을 생성합니다.
wavec build app.wave
출력 바이너리:
target/<file_stem>
3.4 build -o <file> / build --obj <file>
오브젝트 파일만 생성합니다.
wavec build -o app.wave
wavec build --obj app.wave
출력:
target/<file_stem>.o- 경로를 stdout으로 출력
3.5 install std, update std
표준 라이브러리 설치/업데이트 명령입니다.
wavec install std
wavec update std
3.6 --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
허용 항목:
tokensastirmchexall
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형식- 같은 패키지명을 중복 지정하면 에러
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::module2세그먼트 필요
패키지 루트 결정 순서:
--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. 외부 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 -o app.wave
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