토파즈문서
빌드와 배포

산출물과 배포

토파즈 제품에 어떤 파일이 들어가는지 확인하고, 패키지 소스 없이 실행하고, 출력 디렉터리가 바뀌었을 때 안전하게 복구합니다.

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을 쓰세요. 이전 제품으로 되돌려야 한다면 정상으로 확인된 제품 전체를 복원하세요. 해시를 고치거나 관리 파일을 하나씩 지우면 안 됩니다.

관련 문서