패키지와 배포

패키지를 만들고 로컬 폴더의 의존성을 추가한 뒤 topaz.lock으로 내용을 고정하세요. 잠금을 검사하는 명령이 실패하면 복구 표에서 고칠 파일을 찾을 수 있습니다.

첫 프로그램을 따라 topaz를 설치하세요. my-app, utility, registry-app이 아직 없는 작업 폴더에서 아래 명령을 실행합니다.

패키지 만들고 실행하기

BASH

topaz init --root my-app
topaz lock --root my-app
topaz fmt --check --root my-app
topaz check --root my-app --locked
topaz run --root my-app --locked

init은 my-app/topaz.toml과 my-app/src/main.tpz를 만듭니다. lock은 my-app/topaz.lock을 만듭니다. 검사가 통과하면 종료 코드는 0이며, run은 Hello from Topaz를 출력합니다.

topaz.toml은 패키지 설정 파일인 매니페스트입니다. 이름, 패키지·언어 버전, 진입 파일, 기본 빌드 대상, 의존성을 기록합니다. 명령에서 파일 인수를 생략하면 이 파일에 적힌 진입 파일을 사용합니다.

topaz.lock은 매니페스트와 의존성 내용을 기록합니다. --locked는 입력이 기록과 다르면 명령을 멈춥니다. 서식이 다르면 topaz fmt --root my-app으로 맞춘 뒤 서식 검사를 반복하세요. 테스트가 있는 패키지는 첫 애플리케이션처럼 테스트 파일 경로를 지정하세요.

로컬 의존성 추가하기

my-app 옆에 패키지를 하나 더 만들고 의존성으로 추가하세요.

BASH

topaz init --root utility
topaz add utility --path ../utility --root my-app
topaz lock --root my-app
topaz check --root my-app --locked

add는 my-app/topaz.toml에 경로와 내용 해시를 담은 utility 항목을 씁니다. 해시는 의존성 파일의 내용을 식별하는 값입니다. ../utility는 my-app 기준의 상대 경로이므로 옆 폴더를 가리킵니다. lock은 topaz.lock을 갱신하고 마지막 검사는 종료 코드 0으로 끝납니다.

로컬 레지스트리에서 의존성 복사하기

이 예제에는 별도 패키지인 registry-app을 사용합니다. 먼저 앞 절의 utility 폴더를 작업 폴더 아래 registry/utility/1.2.0으로 복사하세요. 복사본의 topaz.toml에서 [package].name = "utility"를 유지하고 [package].version = "1.2.0"으로 바꾸세요. 소스 파일과 나머지 생성 설정은 유지합니다.

BASH

topaz init --root registry-app
topaz add utility@1.2.0 --root registry-app
topaz vendor --root registry-app --from ./registry
topaz check --root registry-app --locked

vendor는 패키지를 검사하고 registry-app/vendor/utility/1.2.0으로 복사한 뒤 registry-app/topaz.lock을 씁니다. 마지막 검사는 종료 코드 0으로 끝납니다. 이렇게 의존성을 프로젝트 안에 복사하는 작업을 벤더링이라고 합니다.

--from은 작업 폴더 기준의 경로입니다. fetch도 같은 로컬 입력을 받아 의존성 복사본과 잠금 파일을 씁니다. 두 명령은 네트워크 레지스트리에서 다운로드하지 않습니다. 레지스트리 의존성의 해시나 복사한 내용이 없는 상태에서 lock을 실행하면 실패합니다.

잠금 불일치 고치기

문제	수정 위치와 행동
매니페스트가 바뀜	`my-app/topaz.toml`을 검토하세요. 실수라면 원래대로 고칩니다. 의도한 변경이라면 `topaz lock --root my-app`을 실행하고 `topaz.lock`의 차이를 검토하세요.
로컬 의존성 내용이 바뀜	`utility`의 파일을 기록된 내용으로 복구하세요. 의도한 갱신을 반영하려면 `my-app/topaz.toml`에서 해당 의존성 항목을 지우고 `add`를 다시 실행해 새 해시를 기록하세요. 이어서 `lock`을 실행하고 두 파일의 차이를 검토합니다.
레지스트리 패키지가 없음	`registry/utility/1.2.0/topaz.toml`의 이름·버전과 소스 파일을 확인하고 `vendor --from ./registry`를 다시 실행하세요.
벤더링한 내용이 바뀜	기록된 파일을 복구하거나 검토한 의존성을 다시 벤더링하세요. 매니페스트가 해시를 지정했다면 검토한 내용의 해시로 갱신하세요.

고친 뒤 --locked를 붙여 check를 다시 실행하세요. 패키지에서도 모듈 가시성과 순환 규칙은 그대로 적용됩니다.

배포용으로 빌드하기

BASH

topaz build --root my-app --locked --release --out-dir product

명령은 product/에 실행 파일과 topaz-artifact.json을 만듭니다. 패키지를 찾을 때는 루트, 경로 의존성, 잠근 의존성 복사본, 툴체인에 포함된 입력을 사용합니다. 네이티브와 Web 빌드에는 대상용 Rust 툴체인이 필요하며, 내부에서 Cargo를 잠금·오프라인 모드로 실행합니다.

제품 폴더 전체와 파일 시스템 권한에 따라 프로그램이 사용할 데이터를 함께 배포하세요. 실행할 때 패키지 소스, topaz.toml, topaz.lock, vendor, 토파즈 CLI는 필요하지 않습니다. 실행 조건은 아티팩트와 배포를 보세요. 생성한 출력이 달라졌다면 보존하고 비어 있는 새 출력 폴더를 고르세요.