툴체인 개요

토파즈 툴체인은 소스 파일과 패키지를 실행 가능한 최종 아티팩트로 연결하는 단일 검증 경로로 처리합니다. 파서나 백엔드 내부 구조를 몰라도 효율적으로 사용할 수 있습니다.

일반적인 작업 순서

명령은 다음 순서로 사용합니다.

fmt --check로 커밋할 소스가 정본 서식을 따르는지 확인합니다.
check로 구문, 식별자, 타입 진단을 확인합니다. 이 단계는 모듈을 해석할 뿐 프로그램을 실행하지는 않습니다.
test로 검사를 마친 테스트 진입점을 결정론적 테스트 호스트에서 실행합니다.
run으로 명령형 애플리케이션을 인터프리터에서 직접 실행합니다.
build로 실제 배포할 제품 타깃 하나를 생성합니다.

잠긴 패키지의 전체 명령 형태는 다음과 같습니다.

BASH

topaz fmt --check --root my-app
topaz check --root my-app --locked
topaz test --root my-app --locked
topaz run --root my-app --locked
topaz build --root my-app --locked --out-dir product

Web 애플리케이션과 HTTP 패키지는 topaz run 대신 topaz dev로 루프백 개발 동작을 확인합니다. 그다음은 동일하게 패키지 모드 build를 사용합니다.

편집기 지원

공식 토파즈 확장은 Visual Studio Marketplace와 Open VSX Registry에서 모두 제공됩니다. VS Code에서는 Marketplace 등록본을, VSCodium이나 다른 호환 편집기에서는 Open VSX 등록본을 사용하세요.

두 스토어에는 동일한 공식 확장이 등록되어 있습니다. 확장은 .tpz 파일을 인식하여 토파즈 파일 아이콘과 구문 강조를 적용하며, 주석·괄호 설정과 기본 스니펫을 제공합니다. 또한 설치된 topaz lsp를 실행하여 편집기 내부에서 진단 결과를 보여 줍니다. topaz.compiler의 기본값은 설치된 토파즈 제품의 컴파일러 선택을 그대로 따릅니다. 비교나 복구를 위해 Rust 컴파일러를 명시할 때만 rust를 선택하고, 설치된 자체 호스트 컴파일러를 직접 지정하려면 self를 선택하세요.

확장 자체에는 컴파일러가 포함되어 있지 않습니다. 설정된 토파즈 실행 파일을 찾지 못해도 구문 강조를 비롯한 정적 편집 기능은 그대로 사용할 수 있으며, 편집기에 실행 파일을 찾지 못했다는 오류가 표시됩니다. 토파즈가 PATH에 없다면 topaz.executablePath를 설정하세요.

성공했을 때 달라지는 것

fmt --check, check, test, run은 배포 제품을 만들지 않습니다. build는 관리 타깃 디렉터리를 사용하며 파일 목록을 topaz-artifact.json에 기록합니다. 패키지 명령은 topaz.toml을 읽습니다. --locked를 사용하면 topaz.lock이 매니페스트 및 로컬 의존성 바이트와 일치해야 합니다.

0이 아닌 종료 코드는 요청한 단계가 완료되지 않았음을 나타냅니다. 첫 번째 토파즈 진단을 수정한 뒤 해당 단계부터 다시 실행하세요. 외부 컴파일러가 없다면 준비가 끝난 타깃을 선택하거나 필요한 툴체인을 설치하세요. 관리형 출력 디렉터리가 변경되었다면 기존 내용은 그대로 두고 비어 있는 새 디렉터리를 사용하세요.

작업에 맞는 다음 문서

명령 옵션, 진단, 종료 동작과 복구는 CLI와 진단을 보세요.
패키지 루트, 잠금 파일, 로컬 의존성과 벤더링은 패키지와 배포를 보세요.
네이티브, Python, Web, HTTP 제품 내용과 토파즈 패키지 소스 없는 실행은 아티팩트와 배포를 보세요.
인터프리터와 빌드 대상 중 무엇을 고를지는 인터프리터와 백엔드를 보세요.