토파즈문서
도구와 실행

인터프리터와 백엔드

토파즈 실행·배포 대상을 고르고 지원하지 않는 동작이 어디에서 명확히 실패하는지 이해합니다.

토파즈에는 검사되는 소스 언어 하나와 여러 실행·배포 경로가 있습니다. 완성 프로그램을 소유할 환경을 기준으로 경로를 선택합니다.

제품에 맞춰 선택하기

  • 개발 중 인터프리터에서 직접 실행하려면 topaz run을 사용합니다.
  • 플랫폼 전용 실행 파일이 필요하면 네이티브 build를 사용합니다.
  • .tpz 소스나 토파즈 CLI 없이 Python 3.11 이상에서 실행할 생성 번들이 필요하면 --target python을 사용합니다.
  • 기존 ES 모듈 호스트가 선택한 토파즈 내보내기를 호출한다면 --target web을 사용합니다.
  • 그 호스트에 생성된 Worker 통신 계층이 필요하면 --target web-worker를 사용합니다.
  • 브라우저 생명주기와 UI를 토파즈가 소유한다면 패키지 대상 web-app을 사용합니다.
  • 제한형 HTTP/1.1 핸들러 하나가 필요하면 패키지 대상 http-service를 사용합니다.

Raw Web과 Worker는 WASM 제품이며 관리형 Web 애플리케이션은 같은 검사형 Web 연결 계층을 완전한 정적 제품 안에 포함합니다.

BASH
topaz run main.tpz
topaz build main.tpz --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

web-app과 http-service는 topaz.toml의 [build].target으로 선택하는 패키지 전용 대상입니다.

대상과 낮추기는 서로 다른 선택

--target은 제품을 선택합니다. --backend native는 Rust 기반 제품 내부에서 선택할 수 있는 낮추기 전략입니다. 조건을 만족하는 스칼라 작업과 제한형 Bytes·ByteBuffer 연산을 먼저 시도하며, 지원하지 않는 모양은 일반 박싱 경로에 남깁니다. Python을 네이티브로 만들거나 Web 제품을 다른 대상으로 바꾸는 옵션이 아닙니다.

이 결정이 중요하면 검사형 native emit 또는 build에 --native-report-json <path>를 추가할 수 있습니다. 보고서는 제품 바이트를 바꾸지 않고 함수별 native, hybrid, boxed 선택을 기록합니다.

대상 경계에서 명확히 실패하기

대상들은 파싱, 모듈 해석과 정적 검사를 공유하지만 호스트에 의존하는 모든 연산을 조건 없이 지원한다고 약속하지 않습니다. 선택한 대상이 연산을 보존할 수 없으면 제품을 쓰기 전에 소스 위치가 있는 생성 오류를 냅니다.

예를 들어 결정적인 fixed-Huffman DEFLATE, 고정 zlib과 RS(255,223) 보호는 인터프리터, 생성 Rust, Raw Web, Worker와 플레이그라운드에서 사용할 수 있지만 생성 Python은 산출물 생성 전에 이를 거부합니다. Hash.crc32는 Python에서도 사용할 수 있습니다.

동시 작업의 실행 순서는 의도적으로 정하지 않습니다. 특정 백엔드가 고른 인터리빙에 의존하면 안 됩니다.

Rust, Python, LIT 경계

생성 Rust와 Python은 배포 산출물이지 추가 토파즈 문법이나 안정적인 수동 편집 API가 아닙니다. 각 전용 페이지에서 필수 조건, 런타임 파일과 명시적 예외를 대칭적으로 설명합니다.

LIT는 제한된 Lispex 통합·도그푸딩 경계입니다. 토파즈로 작성한 인터프리터 소스 하나를 여러 토파즈 경로에서 실행하지만 출하되는 백엔드가 아니며 전체 언어 동등성을 증명하지 않습니다.

관련 문서