토파즈문서
도구와 실행

인터프리터와 백엔드

토파즈의 실행 타깃과 배포 타깃을 선택하고 지원하지 않는 동작이 명확히 실패하는 지점을 이해합니다.

토파즈는 하나의 검사 대상 소스 언어를 제공하며, 실행 경로와 배포 경로는 다채롭습니다. 완성된 프로그램을 제어할 주체 환경에 맞춰 적절한 경로를 선택합니다.

제품에 맞춰 선택하기

  • 개발 중 인터프리터에서 직접 실행하려면 topaz run을 사용합니다.
  • 플랫폼 전용 실행 파일이 필요하다면 네이티브 build를 사용합니다.
  • Python 3.11 이상 환경에서 .tpz 소스 및 토파즈 CLI 없이 실행되는 생성 번들이 필요한 경우 --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도 아닙니다. 각 대상별 전용 문서에서 요구 조건, 런타임 파일, 명시적 예외 항목을 동일한 구조로 설명합니다.

Lispex-in-Topaz의 약어인 LIT는 리스펙스 시험·통합을 위한 제한적 경계입니다. 토파즈로 작성된 단일 인터프리터 소스를 다양한 토파즈 경로에서 실행하도록 지원합니다. 이는 정식 출하되는 백엔드가 아니며, 전체 언어 차원의 동등성을 증명하지도 않습니다.

관련 문서