토파즈문서
빌드와 배포

패키지와 배포

패키지 루트, 매니페스트, 잠금 파일, 로컬 의존성 바이트, 관리형 제품의 올바른 사용 순서를 설명합니다.

패키지는 일반 토파즈 모듈에 루트, 진입점, 의존성 그래프, 빌드 타깃을 확장합니다. 새로운 문법을 추가하지 않으며, 모듈 가시성 규칙과 순환 규칙도 그대로 유지합니다.

1. 패키지 루트 만들기

BASH
topaz init --root my-app

루트에는 topaz.toml과 src/main.tpz가 생성됩니다. 매니페스트는 패키지 이름, 현재 언어, 진입점, 기본 빌드 타깃, 의존성을 선언합니다. 진입 파일 없이 --root my-app만 전달하면 명령은 이 매니페스트의 진입점을 사용합니다.

Web 애플리케이션과 HTTP 스캐폴드는 생성할 때 선택합니다.

BASH
topaz init --target web-app --root my-web-app
topaz init --target http-service --root my-service

2. 레지스트리 의존성이 없는 패키지 잠그기

BASH
topaz lock --root my-app
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.lock은 루트 매니페스트와 해석된 로컬 의존성 내역을 기록합니다. --locked 옵션은 매니페스트, 잠금 파일, 로컬 바이트 가운데 하나라도 일치하지 않으면 작업을 진행하지 않습니다. 매니페스트를 의도적으로 변경했다면 lock을 다시 실행하여 차이를 검토한 뒤 --locked 옵션을 복원하세요.

3. 로컬 또는 레지스트리 의존성 추가하기

경로 의존성은 상대 경로와 내용 식별자를 함께 추가합니다.

BASH
topaz add utility --path ../utility --root my-app
topaz lock --root my-app

레지스트리 의존성은 잠금 작업 전에 명시적인 로컬 레지스트리 입력 경로 안에 존재해야 합니다.

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

vendor 명령은 선택한 패키지를 검증한 후 vendor/utility/1.2.0 위치로 복사하고 잠금 파일을 작성합니다. 레지스트리 패키지의 해시나 벤더링된 내용이 없는 상태에서 lock을 먼저 실행하면 그대로 실패합니다. 이때 네트워크 레지스트리에 접속하지는 않습니다. fetch 명령 역시 동일하게 명시적인 로컬 --from 경계를 사용합니다. 두 명령 모두 주변 네트워크에서 의존성을 탐색하지 않습니다.

4. 로컬 입력만으로 빌드하기

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

이제 패키지 해석 과정에서는 루트, 경로 의존성, 잠긴 벤더 바이트, 툴체인의 번들 입력만 사용합니다. 네이티브 및 Web 컴파일도 내부에서 잠긴 Cargo 오프라인 모드로 동작합니다. 따라서 추가로 지정할 토파즈 옵션은 없습니다.

완성된 관리형 제품이 배포 단위입니다. 제품을 실행할 때 topaz.toml, topaz.lock, vendor, 패키지 소스, 토파즈 CLI는 필요하지 않습니다. 제품 디렉터리 전체를 복사하고, 선언한 파일 시스템 권한이 요구하는 애플리케이션 데이터도 함께 복사하세요.

잠금을 약화하지 않고 복구하기

  • --locked가 매니페스트 차이를 알리면 그 변경이 의도한 것인지 판단합니다. 그다음 잠금 파일을 다시 생성하여 검토합니다.
  • 레지스트리 패키지가 없으면 명시적인 로컬 레지스트리 입력을 확보한 뒤 vendor 또는 fetch를 실행합니다. --locked를 제거하지 마세요.
  • 벤더 바이트가 달라졌다면 기록된 내용을 되돌립니다. 그렇지 않다면 의도적으로 다시 벤더링하고 새 의존성을 검토합니다.
  • 빌드 출력이 달라졌다면 출처를 알 수 없는 파일을 삭제하지 말고 비어 있는 새 출력 디렉터리를 사용합니다.

관련 문서