토파즈문서
빌드와 배포

아티팩트와 배포

토파즈 제품에 포함되는 파일을 확인하고 패키지 소스 없이 실행하며, 출력 디렉터리가 변경되었을 때 제품을 복구하는 방법을 설명합니다.

emit은 생성된 소스를 보여 줍니다. 이 소스는 점검하거나 다른 도구와 연동할 때 활용하며, 언제든 다시 생성하여 교체할 수 있습니다. build는 관리 대상 배포 제품을 만듭니다. 배포할 때는 build 디렉터리를 사용하십시오. 컴파일러가 임시로 사용하는 저장 공간이나 맥락 없이 추출한 생성 파일을 배포하지 마십시오.

제품 빌드

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

마지막 명령은 topaz.toml에 지정한 [build].target을 사용합니다. web-app과 http-service는 패키지에서만 사용할 수 있습니다. topaz.lock은 작성과 검증에 사용합니다. 빌드를 완료한 관리형 제품은 자체 식별자를 topaz-artifact.json에 기록합니다.

모든 제품의 공통 파일

빌드에 성공하면 다음 파일이 항상 함께 포함됩니다.

출력
LICENSE
NOTICE
GENERATED-OUTPUT-NOTICE.txt
topaz-artifact.json

아티팩트 매니페스트는 타깃, 툴체인 및 언어 식별자, 런타임 요구 사항, 실행 방법을 기록합니다. 관리 타깃 파일마다 경로, 크기, 해시, 실행 권한 요구 사항도 함께 남깁니다. 이 파일은 가장 마지막에 기록합니다.

타깃별 파일 구조

네이티브 타깃은 해당 플랫폼에서만 사용하는 파일 하나를 추가로 만듭니다.

출력
target/debug/program[.exe]
target/release/program[.exe]

두 경로 중 빌드한 프로필 하나만 생성됩니다. Windows에서는 파일 이름 끝에 .exe가 붙습니다.

Python은 다음 파일을 추가로 만듭니다.

출력
program.py
topaz_py_rt.py

Raw Web은 다음 파일을 추가로 만듭니다.

출력
topaz-web.js
topaz-web.d.ts
topaz-web.wasm

Web Worker는 Raw Web 파일을 그대로 두고 다음 파일을 추가합니다.

출력
topaz-web-worker.js
topaz-web-worker-client.js

관리형 Web 애플리케이션도 Raw Web 파일을 그대로 두고 다음 파일을 추가합니다.

출력
index.html
topaz-app.js
topaz-web-capabilities.json
styles/app.css

선언한 스타일과 자산은 정규화한 상대 경로를 그대로 유지합니다. 따라서 마지막 줄은 패키지마다 달라집니다.

HTTP 서비스는 다음 파일을 추가로 만듭니다.

출력
target/release/program[.exe]
topaz-service-config.json
THIRD-PARTY-NOTICES.txt

이 예시는 릴리스 빌드 기준입니다. 디버그 빌드는 target/debug를 사용합니다. Windows에서는 [.exe]가 붙습니다.

토파즈 패키지 소스 없이 실행

제품 디렉터리 전체를 새 위치로 복사한 뒤 그 루트에서 실행하십시오.

BASH
./target/release/program
python3 program.py

두 명령 중 자신이 빌드한 제품에 맞는 것만 사용하십시오. Python 제품은 Python 3.11 이상이 필요합니다. 네이티브와 HTTP 실행 파일은 빌드한 플랫폼에서만 동작합니다.

관리형 Web 애플리케이션 디렉터리는 HTTP로 제공한 다음 index.html을 열어야 합니다. Raw Web과 Worker 제품에는 ES 모듈 호스트가 있어야 합니다. 이 호스트가 생성된 JavaScript API를 가져다 씁니다. 어떤 Web 제품도 file:// 방식의 모듈 로딩에 의존하면 안 됩니다.

네이티브와 Python 패키지 애플리케이션은 선언한 파일 시스템 권한 루트를 프로세스의 작업 디렉터리에서부터 탐색합니다. 매니페스트가 요구하면 관리형 제품 옆에 애플리케이션 data/와 쓰기 가능한 출력 디렉터리를 복사하거나 생성하십시오. 패키지 데이터는 자동으로 동반되지 않습니다. Web 스타일과 자산은 다릅니다. 선언한 [web] 입력은 관리형 Web 제품에 함께 복사합니다.

출력 디렉터리 안전과 복구

같은 타깃을 다시 빌드하면 기존 관리 파일의 바이트부터 검사합니다. 타깃이 달라졌거나, 매니페스트가 잘못되었거나, 관리 파일이 변경되었거나, 심볼릭 링크나 사용자 소유 경로와 충돌하면 빌드를 거부합니다. 아티팩트 매니페스트에 없는 파일은 그대로 둡니다.

빌드를 강제로 통과시키려고 소유권이 불분명한 디렉터리를 지우지 마십시오. 원인을 검토할 수 있도록 그대로 두고 비어 있는 새 --out-dir을 사용하십시오. 이전 제품으로 되돌려야 한다면 정상으로 확인된 제품 전체를 복원하십시오. 해시를 수정하거나 관리 파일을 하나씩 삭제하면 안 됩니다.

관련 문서