토파즈 5.15.0이 현재 제품입니다. 현재 언어 모드는
topaz-5.15입니다.
다음 명령으로 설치 상태를 확인합니다.
topaz version --verbose
이 명령은 컴파일러, 언어 모드, 런타임, Rust 백엔드 식별자를 보여 줍니다. 설치 문제를 알릴 때는 출력 전체를 그대로 첨부하세요.
컴파일러 선택하기
Rust Stage 0는 기본 컴파일러입니다. 문제가 생겼을 때 돌아갈 복구 컴파일러이기도 합니다. 설치된 Stage 2 컴파일러도 직접 골라 쓸 수 있습니다. 현재 언어 모드의 파싱, 검사, 실행, 테스트, 벤치마크, 패키지 검사, 컴파일러 관찰에서 고를 수 있습니다.
topaz check app/main.tpz
topaz check app/main.tpz --compiler self
topaz test --root app --locked --compiler self
topaz emit app/main.tpz --compiler self
topaz emit app/main.tpz --target python --compiler self --out-dir python-source
topaz build app/main.tpz --compiler self --out-dir app-product
topaz build app/main.tpz --target web --compiler self --out-dir web-product
topaz dev --root web-app --locked --compiler self
topaz fmt app/main.tpz --compiler self
topaz lsp --compiler self
topaz doc --root app --locked --compiler self --out-dir api-docs
topaz compiler observe app/main.tpz --compiler self --out-dir observation
topaz check app/main.tpz --compiler rust
topaz compiler status --json
--compiler를 생략하면 rust를 고른 것과 똑같습니다. self 경로는 설치된 C2
이미지를 씁니다. 이 경로가 실패해도 Rust로 다시 시도하지 않습니다. 다음 경로가
이 선택을 따릅니다. parse, dump-ast, check, 모든 현재 프로필, export
보고서, run, test, bench, 잠긴 패키지, compiler observe, 검사된 boxed
Rust 생성, 네이티브 빌드, Python 소스와 배포 제품, raw Web, worker, Web
애플리케이션, HTTP 서비스, 허용된 Web/서비스 dev, 서식 정리, LSP, 패키지
문서 생성입니다. self 서식 정리와 문서 생성은 선택한 C2 구문·의미 제품을 받아
씁니다. 그다음은 Rust 경로와 같은 결정적 출력기, 같은 표현 스키마를 씁니다.
self LSP는 열어 둔 문서에서 선택한 C2 제품을 만들어 캐시합니다. 선언된 모든
메서드에 대해 Rust 컴파일러 단계를 부르지 않고 응답합니다. LSP 프로세스 하나는
컴파일러 선택 하나를 끝까지 유지합니다. 그러니 설정을 바꾼 뒤에는 편집기
세션을 다시 시작하세요. self 대상 어댑터는 C2가 검증한 정보만 받아 씁니다.
산출물에는 topaz-stage2 출처를 기록하고 Rust 대상 프런트엔드는 부르지
않습니다. 이전 언어 모드, 검사 생략, 네이티브 특화에는 아직
--compiler rust가 필요합니다. 지원하지 않는 self 선택은 소스를 읽거나 출력을
만들기 전에 멈춥니다. Rust 복구 명령을 대신 실행하지 않고 안내만 합니다.
compiler status --json은 기계가 읽을 수 있는 기준 정보를 보여 줍니다. 설치된
생성자, 프로그램 이미지, 소스 집합 식별자, 지원 경로와 거부 경로, 기본값,
복구 선택, 무폴백 정책이 여기에 들어갑니다.
설치 제품의 복구 경계
정확한 npm 설치 제품은 두 컴파일러 선택을 실행 파일 하나에 담습니다. 저장소를
checkout할 필요가 없습니다. 어느 쪽으로 빌드했든 토파즈 소스를 지운 뒤에도
제품을 실행할 수 있습니다. 설치된 C2 이미지가 없거나 깨졌다면 self 요청은
그대로 실패합니다. Rust 결과를 가져다 쓰거나 자동으로 다시 시도하는 일은
없습니다. 복구를 직접 선택할 때만 원래 명령을 --compiler rust로 다시
실행하세요. Rust는 언제든 따로 쓸 수 있습니다. 공개된 Stage 0 복구 키트는 자동
폴백이 아니라 따로 실행하는 오프라인 재구성 경로입니다.
설치된 self 컴파일러는 이제 현재 모드의 완전한 컴파일 제품을 가집니다. 이 제품에는 버전이 붙습니다. 안에는 순서가 고정된 모듈, 토큰과 AST, 이름 해석과 export, 타입 진단과 프로필 진단, 하강 결과와 런타임 요구 사항, 생성 Rust, 정확한 호출 출처와 결과 출처가 들어갑니다. 호스트 어댑터는 C2가 준 사실을 검증하고 해독하기만 합니다. 빠진 컴파일러 결정을 스스로 다시 만들지 않습니다. 허용된 명령 경로에서는 공유 패키지 호스트와 런타임이 검증된 같은 제품을 받아 씁니다.
self Rust 생성은 C2의 고정점 IR 테이블을 그대로 보존합니다. 여기에 일반
애플리케이션 호스트 facade만 덧붙입니다. 이 테이블은 대상 전용 공유 런타임이
실행합니다. 이 런타임에는 C1과 C2 컴파일러 이미지가 들어 있지 않습니다. Rust
파서, 리졸버, 검사기, 하강기, 생성기를 실행할 수도 없습니다. 네이티브 산출물
manifest는 선택한 컴파일러와 생성자, 컴파일러 소스 집합과 대상 소스 집합,
컴파일 제품, 생성 소스 해시, targetCompilerFallback: false를 기록합니다.
사용할 수 있는 제품 경로
- CLI는 파일이나 패키지의 서식을 맞추고, 검사하고, 테스트하고, 실행하고, 생성 소스를 내보내고, 제품을 빌드합니다.
- 네이티브 빌드는 그 플랫폼에서만 도는 실행 파일을 만듭니다.
- Python 빌드는
program.py와topaz_py_rt.py를 만듭니다. 실행하려면 Python 3.11 이상이 필요합니다. - Raw Web과 Web Worker는 기존 JavaScript 호스트가 쓸 WASM 패키지를 만듭니다.
- Web 애플리케이션은 완전한 관리형 정적 브라우저 제품을 만듭니다.
- 제한형 HTTP 서비스는 관리형 네이티브 HTTP/1.1 프로세스를 만듭니다. 리스너, 요청, 대기열, 마감 시간, 로그, 종료 설정이 모두 유한합니다.
- 패키지 명령은 매니페스트, 잠금 파일, 경로 의존성, 검증된 로컬 벤더 의존성을 씁니다.
- 브라우저 플레이그라운드는 네이티브 CLI를 설치하지 않고도 제한된 검사와 인터프리터 실행을 해 볼 수 있게 합니다.
컴파일러 관찰 자료 살펴보기
설치된 CLI는 현재 검사 컴파일러 파이프라인을 기록할 수 있습니다. 생성 Rust 소스 단계까지를 정규 관리형 번들 하나에 담습니다.
topaz compiler observe --root my-app --locked --out-dir compiler-observation
topaz compiler validate compiler-observation
출력은 my-app 바깥에 두세요. 패키지 안에 두면 다음 관찰에서 관리형 출력
디렉터리 자체가 패키지 디렉터리 사실로 보일 수 있습니다. 번들에는 정확한 소스
바이트와 소스 집합, 원시 토큰과 레이아웃 토큰, AST, 이름 해석, 구조화된 타입,
호출, 클로저 캡처, 소스에 의존하지 않는 하강, 런타임 연산, 생성 Rust, 진단,
요청, 응답, 출처 정보가 들어갑니다. 이 번들은 소스 패키지와 같은 수준으로
보호하세요.
validate는 읽기 전용입니다. 다시 컴파일하지 않고 원래 소스 트리도 읽지
않습니다. 정규 인코딩, 스키마, 순서, 상호 참조, 완전성, 크기, 해시만
검사합니다. 출처 정보는 생성자를 Rust Stage 0으로 명시합니다. 이는 이 관찰
경로를 설명할 뿐, 다른 컴파일러 단계가 어떤 언어로 작성됐는지는 말하지
않습니다.
명시적인 프리뷰 경로는 토파즈로 작성한 현재의 렉서, 레이아웃 구현, 파서, 논리적 import 폐쇄, 이름 해석기, 정적 검사기를 실행합니다. 이들을 띄우는 쪽은 Rust Stage 0입니다.
topaz compiler preview --root my-app --locked --out-dir typed-preview
topaz compiler validate typed-preview
이 번들은 타입 검사 단계에서 끝납니다. 기록에는 engine: topaz-front-end-preview,
생성·결과 단계 0/0, 기본 엔진 Rust Stage 0가 남습니다. 토파즈 프런트엔드는
현재 문법과 정본 AST를 다룹니다. 패키지 의존성과 마운트 의존성, 표준 모듈의
논리적 폐쇄도 다룹니다. 정확한 스코프, 선언, 참조, export와 정적 타입, 호출,
캡처, 구조화 진단까지 맡습니다. 소스 사실, AST 노드와 Typed 노드, 노드 깊이,
셸 교환 크기에는 상한이 있습니다. 대상 코드를 하강하거나 생성하거나 빌드하거나
실행하지 않습니다. Stage 1이나 자기 호스팅 컴파일러라는 주장도 아닙니다.
프리뷰가 실패하면 그 자리에서 멈추고 대상 프런트엔드 작업을 Rust로 다시
시도하지 않습니다. 일반 컴파일러 명령은 계속 Rust Stage 0를 씁니다.
설치 제품은 생성된 C1을 명시적인 Stage 1 Compiler Preview로도 제공합니다.
topaz compiler preview main.tpz --producer stage1 --terminal rust-source --out-dir stage1-observation
topaz compiler validate stage1-observation
C1은 토파즈로 작성한 하강기와 Rust 생성기가 만든 결과를 받아 씁니다. 그 결과는
버전이 붙은 교환 형식과 소스가 없는 비공개 IR입니다. C1은 이것으로 일반
패키지를 컴파일합니다. 이때 대상 Rust 파서, 리졸버, 검사기, 하강기, 생성기,
인터프리터를 링크하지 않습니다. 실패했을 때 이들을 다시 부르는 일도 없습니다.
관리형 번들은 생성·결과 단계 1/1, 컴파일러 소스 집합, 생성 소스, 런타임
템플릿 식별자, targetCompilerFallback: false를 기록합니다. Stage 2 고정점을
주장하지는 않습니다.
비교 경계는 의미 관찰, 진단, 생성 소스, 생성 제품 동작, 출처를 각각 따로 판정합니다. 선언된 다중 모듈 사례와 검사 거부 사례에서 Stage 0와 C1의 결과가 일치합니다. C1은 같은 것을 여러 번 생성해도 바이트가 그대로입니다. Stage 0와 Stage 1이 만든 Rust 소스는 서로 다릅니다. 다만 각 생성자 안에서는 결정적이므로 둘을 별도 결과로 기록하고 바이트가 같다는 거짓 주장을 만들지 않습니다. 잘못된 생성자 식별자나 손상된 관리형 C1 제품은 곧바로 거부합니다. 대상을 Stage 0로 다시 시도하지 않습니다.
설치 제품만 있으면 저장소를 복제하지 않고도 정확히 비교할 수 있습니다.
topaz compiler observe main.tpz --terminal rust-source --out-dir rust-observation
topaz compiler preview main.tpz --producer stage1 --terminal rust-source --out-dir stage1-observation
topaz compiler validate rust-observation
topaz compiler validate stage1-observation
topaz compiler compare --layer semantic rust-observation stage1-observation
관리형 관측 번들 두 개를 만들고 나면 검증과 비교는 원래 대상 소스를 다시 읽지
않습니다. Stage 1이 요청을 거부하거나 고장 나면 그대로 실패합니다. 다른 관측
번들로 대신하지 않습니다. 이때는 별도의 compiler observe 복구 명령을 안내만
하고 자동으로 실행하지 않습니다. Rust Stage 0가 필요하면 일반 observe,
check, 빌드 명령을 직접 쓰세요.
컴파일러가 만든 Rust는 생성자와 빌드 출처를 정본 소스 바이트 바깥에 기록합니다. 이렇게 떼어 놓으면 이후 컴파일러 단계에서 생성 소스를 바이트 단위로 비교할 수 있습니다. 누가 만들었는지도 지워지지 않습니다. 설치형 Stage 1 명령과 Rust Stage 0 기본값은 그대로입니다.
이제 C1을 새로 실행하면 R1이 나옵니다. 고정된 빌드는 그 바이트를 그대로 별도 C2 프로그램 이미지에 묶습니다. 정본 컴파일러 소스가 같아도 C1과 C2는 서로 독립된 manifest와 내장 이미지를 가집니다. 이 빌드 경계만으로 C2를 실행했다거나 고정점에 도달했다고 주장하지는 않습니다.
독립적으로 내장된 C2 이미지는 다음처럼 명시적으로 실행합니다.
topaz compiler preview app/main.tpz \
--producer stage2 \
--terminal rust-source \
--out-dir stage2-observation
entry 경로 없이 --self-source를 쓰면 설치 제품에 들어 있는 컴파일러 소스
세트를 컴파일합니다. 이 명령은 Stage 2 제품 manifest를 씁니다. C1이나 Rust
대상 front end로 다시 시도하지 않습니다.
고정점 court는 두 주장을 나눠서 다룹니다. 먼저 C1과 C2가 해석한 컴파일러 프로그램 의미를 비교합니다. 정상 입력 하나와 진단 입력 하나에 대한 정본 관찰도 함께 비교합니다. 그다음 새 R1과 R2를 아무 정규화 없이 원시 바이트로 비교합니다. 두 계층 모두 결과가 같습니다. C1과 C2의 이미지, 호출 출처는 서로 달라도 정상입니다. 네이티브 실행 파일 바이트는 이 주장에 넣지 않습니다. 이 결과는 명시적 Preview 컴파일러가 그 경계에서 안정됐다는 뜻입니다. 이 결과가 Stage 2를 기본값으로 만들지는 않습니다. 가능한 모든 컴파일러 동작이 옳다는 증명도 아닙니다.
제한된 실패 canary는 의미 투영, 생성 소스 식별자, C2 출처, 생성자, seed, runtime 경계를 한 번에 하나씩 바꿔 봅니다. 소스 fact가 없을 때나 현재 Preview 경계 밖의 언어 모드를 골랐을 때도 완성된 출력 디렉터리를 확정하기 전에 멈춥니다. 어떤 실패에서도 C1이나 Rust 대상 front end로 다시 시도하지 않습니다.
정확한 로컬 npm 패키지는 대상 소스와 저장소 경로가 없어도 일반 Stage 2 형식과
self-source 형식을 실행합니다. self-source 번들에는
stage2-fixed-point.json이 들어 있습니다. 여기서 의미와 생성 소스 상태는
pass이고 네이티브 바이너리 재현성은 not-run입니다. 오프라인 Stage 0 복구
소스에는 C1/C2 매니페스트, 고정점 기록, 스키마, 런타임, 고정된 도구 모음
정보가 들어갑니다. 다시 만든 Stage 0는 자동 폴백이 아닙니다. 쓸 때마다 따로
지정해야 하는 엔진으로 남습니다.
답을 얻고 싶은 질문에 맞는 경계를 고르세요. 그러면 완전한 관찰 번들 두 개를 비교할 수 있습니다.
topaz compiler compare --layer semantic observation-a observation-b
topaz compiler compare --layer generated-source observation-a observation-b
topaz compiler compare --layer provenance observation-a observation-b
topaz compiler compare --layer native-binary program-a program-b
명령은 크기가 제한된 정규 JSON 레코드 하나를 출력합니다. 선택한 계층이 서로 다르면 실패 상태로 끝납니다. 의미 비교는 처음 달라진 컴파일러 단계에서 멈춥니다. 생성 소스와 출처 정보는 서로 독립적입니다. 그래서 생성자 식별자가 달라졌다고 해서 언어 의미가 어긋난 것은 아닙니다.
Rust Stage 0 기준점 복구
자기 호스팅 자격을 갖춘 릴리스에는 일반 플랫폼 바이너리 다섯 개가 들어갑니다. 여기에 복구 매니페스트와 결정적 소스 아카이브가 따로 들어갑니다. 아카이브는 Rust 컴파일러 소스, 잠금 파일, 벤더 의존성과 라이선스, 런타임 템플릿, 프로토콜 스키마, 컴파일러 작업 부하, 재구성 도구를 고정합니다. 임베드된 토파즈 작성 컴파일러 파일도 하나의 소스 집합으로 기록합니다. 이 집합은 따로 검증할 수 있습니다. 같은 입력으로 두 번 만들면 아카이브 바이트가 똑같습니다.
복구 세트에는 Rust 도구 모음 자체가 들어 있지 않습니다. 고정된 Rust 도구 모음을 먼저 설치해야 합니다. 그다음부터는 아카이브 안의 벤더 디렉터리만으로 오프라인에서 빌드합니다. 이 경로는 복구와 출처 확인을 따로 하려고 둔 것입니다. 일반 설치 경로가 아니며 Rust 복구 체인이 자기 호스팅된다는 뜻도 아닙니다.
부트스트랩에 적합한 컴파일러 소스 검사
Bootstrap Profile은 컴파일러 커널 소스가 쓸 수 있는 현재 언어의 범위를 기계가 읽을 수 있게 제한합니다. 새 문법이나 방언을 더하지는 않습니다. 잠긴 결정적 패키지는 주변 호스트 권한, extern 모듈, 부동소수점, 동시성, 리소스, 테스트 API, 그 밖의 호스트 의존 연산을 쓰지 않을 때만 통과합니다.
topaz check --profile bootstrap --locked --root compiler-kernel
사람이 읽는 진단에는 안정적인 bootstrap/* 규칙 이름이 나옵니다.
--format json을 쓰면 stderr로는 기계가 읽을 수 있는 프로필 진단이, stdout으로는
요약 하나가 나옵니다. 로컬 값은 철자가 아니라 해석된 식별자로 판정합니다.
그래서 직접 만든 함수의 이름이 print여도 호스트 연산이 되지 않습니다. 거꾸로
금지된 호스트 연산은 이름을 바꾸거나 별칭을 붙여도 숨길 수 없습니다.
선택에 필요한 제한
모든 대상이 파싱, 모듈 해석, 정적 검사를 똑같이 공유합니다. 하지만 호스트에 의존하는 연산까지 어디서나 쓸 수 있는 것은 아닙니다. 어떤 연산을 그대로 보존할 수 없는 대상은 제품을 쓰기 전에 그 연산을 거부해야 합니다. 특히 생성 Python은 지금 fixed-Huffman DEFLATE, 고정 zlib, RS(255,223) 도우미를 지원하지 않습니다. 이때는 생성 단계에서 분명하게 실패합니다. 바이너리 미디어를 다룰 때는 대상을 고르기 전에 백엔드 페이지를 확인하세요.
HTTP 제품은 일부러 기능을 좁혀 놓았습니다. TLS, HTTP/2, WebSocket, 아웃바운드 네트워크 접근, 주변 환경 권한, 공유 가변 토파즈 상태, 범용 Web 프레임워크를 더하지 않습니다.
Web 애플리케이션 호스트는 선언한 브라우저 권한만 열어 줍니다. Raw Web과 Worker 제품에는 기존 JavaScript 호스트가 있어야 합니다. 플레이그라운드 실행은 소스를 시험해 보는 것입니다. 배포된다는 증거는 아닙니다.
동시에 도는 작업의 실행 순서는 정해 두지 않습니다. 특정 인터리빙에 기대면 안 됩니다.
LIT는 Lispex 도그푸딩과 통합을 위한 제한된 경계로만 둡니다. 제품으로 출시하는 토파즈 백엔드가 아닙니다. 전체 언어 동등성을 확립하지도 않습니다.
권장 작업 순서
fmt --check, check, test로 시작하세요. 명령형 애플리케이션은 run으로
확인합니다. Web 애플리케이션이나 HTTP 서비스는 dev로 확인합니다. 실제로
배포할 대상만 빌드하세요. 배포할 때는 관리되는 디렉터리 전체를 복사합니다.