토파즈는 여러 제품에서 WebAssembly를 씁니다. 제품마다 소유자와 신뢰 경계가 다릅니다. 명령을 고르기 전에 어떤 제품을 만들지부터 정하세요.
1. 플레이그라운드(Playground): 첫 브라우저 실험
CLI를 설치하지 않고 작은 토파즈 프로그램을 고치고 검사하고 실행하고 싶다면 사이트 플레이그라운드를 쓰세요. 브라우저는 Worker 안으로 컴파일러와 인터프리터 WebAssembly를 불러옵니다. 이 방식은 소스를 대화형으로 실험해 보는 데까지만 쓸모가 있습니다. 애플리케이션이 배포된다거나 브라우저에 제한 없이 접근한다는 증거는 아닙니다.
설치한 CLI로 같은 실험을 하려면 첫 프로그램에서 시작하세요.
2. Raw Web: 기존 호스트가 토파즈 호출
기존 JavaScript ES 모듈 호스트가 UI를 소유하고 선택한 토파즈 내보내기 함수를 호출하는 구조라면 Raw Web을 고르세요.
topaz build --target web main.tpz --release --out-dir web-product
제품에는 topaz-web.js, topaz-web.d.ts, topaz-web.wasm과 공통 산출물
파일이 들어갑니다. 생성 모듈에서 instantiateTopaz를 가져오세요. 디렉터리는
HTTP로 제공합니다. 호스트는 생성된 타입 ABI를 그대로 따라야 합니다.
3. Worker: 같은 ABI를 메인 스레드 밖에서 사용
기존 호스트에 요청과 응답을 주고받는 통신 계층까지 필요하다면 Worker를 고르세요. 이 계층은 Raw Web 제품을 감싸는 모양으로 함께 생성됩니다.
topaz build main.tpz --target web-worker --release --out-dir worker-product
제품에 topaz-web-worker.js와 topaz-web-worker-client.js가 더해집니다.
Worker는 UI를 만들지 않고 권한도 늘리지 않습니다. UI와 권한은 계속 JavaScript
호스트가 소유합니다.
4. 관리형 Web 애플리케이션: 토파즈가 UI 소유
모델, 메시지, 상태 갱신, 화면, 선언한 브라우저 권한까지 토파즈가 소유하는
구조라면 web-app을 고르세요.
topaz init --target web-app --root hello-web
topaz lock --root hello-web
topaz check --root hello-web --locked
topaz test hello-web/tests/app.tpz --root hello-web --locked
topaz dev --root hello-web --port 8000
topaz build --root hello-web --locked --release --out-dir web-app-product
이 대상은 패키지에서만 쓸 수 있습니다. 완전한 정적 제품 하나를 만듭니다. 그
안에는 index.html, 검사된 topaz-app.js 호스트, Raw Web 파일, 권한
메타데이터, 선언한 스타일과 자산이 들어갑니다. topaz dev는 루프백에서만
돕니다. 프로덕션 서버가 아닙니다.
필수 조건과 복구
Raw Web, Worker, 관리형 Web 빌드에는 Rust가 필요합니다. 그 Rust에는
wasm32-unknown-unknown 대상이 설치되어 있어야 합니다. 완성된 브라우저
제품에는 토파즈 CLI나 Rust가 필요하지 않습니다. HTTP로 제공하세요.
file://에서 ES 모듈과 WASM을 직접 불러오는 방식은 지원하는 경로가 아닙니다.
브라우저가 호스트와 런타임 식별자가 맞지 않는다고 알리면 예전 JavaScript와 새 WASM을 섞지 마세요. 한 번의 빌드에서 나온 디렉터리 전체를 배포합니다. 관리형 출력 디렉터리가 달라졌다면 그대로 두고 비어 있는 새 디렉터리에 빌드하세요.