토파즈문서
도구와 실행

CLI와 진단

작업에 적합한 토파즈 명령을 선택하고 실행 성공·실패 및 복구 동작을 이해합니다.

CLI는 단일 파일과 패키지 모두에 동일한 파싱, 모듈 해석, 정적 검사 단계를 적용합니다. 모든 명령은 이 공통 관문을 먼저 거친 후 각자의 지정된 작업을 수행합니다.

검사 전에 서식 확인하기

코드 리뷰 및 자동화 환경에서는 fmt --check를 사용합니다. 정본 서식과 다른 모든 파일을 출력하고 0이 아닌 종료 코드를 반환합니다. 파일 내용을 변경하지는 않습니다.

BASH
topaz fmt --check --root my-app
topaz fmt --root my-app

두 번째 명령으로 서식을 적용한 후 첫 번째 명령을 다시 실행하세요. 패키지 모드에서는 벤더링된 의존성과 빌드 출력물을 대상에서 제외합니다.

실행 없이 검사하기

BASH
topaz check main.tpz
topaz check --root my-app --locked
topaz check --format json main.tpz

검사 결과 문제가 없으면 종료 코드는 0입니다. 진단에는 소스 코드 위치, 고정된 TPZ#### 코드, 요약 정보 및 필요한 상세 정보가 포함됩니다. JSON 모드는 도구가 읽을 수 있는 안정적인 진단 데이터를 출력합니다. 검사 단계에서는 사용자 코드를 실행하지 않으며 배포 아티팩트도 생성하지 않습니다.

BASH
topaz explain TPZ5021
topaz explain TPZ5021 --json

첫 번째 진단을 수정한 후 check를 다시 실행하세요. 후속 오류는 첫 번째 오류 때문에 발생했을 수 있습니다. explain 명령은 알려진 코드를 상세히 설명하지만 소스 코드를 직접 수정하지는 않습니다.

사용 프로필 하나로 검사 좁히기

check 명령에 --profile 옵션을 지정하면 정본 토파즈의 검사 범위를 특정 실행 프로필로 제약할 수 있습니다. 일반 check를 통과한 프로그램이라도 지정한 프로필 검사에서는 실패할 수 있습니다.

BASH
topaz check --profile agent-pack main.tpz
topaz check --profile test-profile tests/plan.tpz

agent-pack 프로필은 일반 애플리케이션 코드에 적합한 구문 형태만 허용합니다. assert, std.test 임포트, Test.* 멤버, >> 함수 합성 등은 프로덕션 출하용 코드가 아닌 테스트 전용이거나 명세 수준에 머무는 구문이므로 거부합니다. test-profile은 정본 자유 함수 assert(...)를 허용하며, 함수 합성 및 테스트 프레임워크 표면은 동일하게 거부합니다. 컴파일러 커널 소스를 위한 Bootstrap Profile은 툴체인 상태 문서에서 다룹니다.

사람이 읽는 진단 출력에는 고정된 TPZ5801 코드와 agent-pack/no-composition 같은 규칙 표기가 붙습니다. --format json 옵션을 사용하면 정본 에러에 진단 항목마다 topaz.profile-diagnostic/v1 객체가, 정본 출력에 topaz.profile-check/v1 요약 객체가 나옵니다. --profile 옵션은 check 명령에서만 제공됩니다. 현재 모드의 정본 토파즈가 필요하며 --exports-json 옵션과 함께 쓸 수 없습니다.

테스트와 실행

BASH
topaz test --root my-app --locked
topaz test tests/summary.tpz --root my-app --locked
topaz run --root my-app --locked
topaz run main.tpz -- arg1 arg2

test 명령은 검사를 마친 결정론적 테스트 호스트를 사용합니다. 단언이 실패하거나 정적 진단 오류, 런타임 결함이 발생하면 0이 아닌 종료 코드를 반환합니다. --root 옵션과 함께 테스트 파일을 지정하면 패키지 매니페스트, 잠금 파일, 모듈, 의존성을 그대로 유지하여 적용합니다.

run 명령은 검사를 마친 명령형 진입점을 인터프리터로 실행합니다. -- 뒤의 인수는 main 함수로 전달됩니다. Web 애플리케이션이나 HTTP 패키지에서 다루는 아티팩트는 단발성 명령이 아닌 브라우저 앱이나 서비스 형태입니다. 따라서 로컬 루프백 개발에는 topaz dev를 사용합니다.

배포 타깃 하나 빌드하기

BASH
topaz build main.tpz --out-dir native-product
topaz build --target python --root my-app --locked --out-dir python-product
topaz build --root my-app --locked --release --out-dir product

build 명령은 코드 검사를 완료한 후 요청한 관리형 제품을 생성합니다. 네이티브, Web, HTTP 빌드 시에는 해당 외부 Rust 타깃이 필요하며, Python은 제품을 실행할 때만 필요합니다. 정적 오류가 존재하는 경우 아티팩트를 생성하기 전에 중단됩니다. 외부 도구 오류는 토파즈 빌드 단계 이후 추가로 보고되며 역시 0이 아닌 종료 코드로 끝납니다.

출력 디렉터리에 다른 타깃의 파일이나 잘못된 아티팩트 매니페스트, 변경된 관리 바이트가 존재하더라도 토파즈는 디렉터리 소유권을 임의로 판단하지 않습니다. 추후 분석을 위해 해당 디렉터리는 그대로 두고 비어 있는 새 --out-dir을 고르세요.

패키지와 기계 판독 경계

진입 파일을 생략하고 --root 옵션을 전달하면 topaz.toml의 진입점을 사용합니다. --locked 옵션은 현재 매니페스트와 로컬 의존성 내용이 topaz.lock과 정확히 일치할 때만 통과합니다. 프로그램 인수는 항상 -- 뒤에 둡니다.

--unchecked 옵션은 컴파일러를 분석할 때 사용하는 우회 경로로, 일반 애플리케이션용 명령이 아닙니다. 이 옵션은 정적 검사 관문을 제거하므로, 실패한 검사형 빌드를 성공처럼 보이게 하려는 목적으로 사용해서는 안 됩니다.

관련 문서