툴체인 상태

설치된 토파즈 컴파일러를 확인하고 프로그램을 실행할 환경을 고르세요. 컴파일러 문제를 조사할 때는 아래 상세 절에서 컴파일 기록을 저장하고 읽는 방법을 찾을 수 있습니다.

설치 상태 확인하기

토파즈 CLI를 설치한 뒤 터미널에서 실행하세요.

topaz version --verbose

컴파일러 버전, 언어 모드, 런타임 버전, Rust 백엔드가 나옵니다. 그중 다음 두 줄은 언어 모드와 백엔드를 나타냅니다.

Language mode: topaz-5.20
Rust backend: rust (CDR-006)

Rust backend는 네이티브 빌드가 Rust 코드를 생성한다는 뜻입니다. 기본 컴파일러는 토파즈로 작성했습니다. 설치 문제를 제보할 때는 출력 전체를 첨부하세요. 터미널이 topaz를 찾지 못하면 터미널을 다시 열고 설치 폴더가 PATH에 있는지 확인하세요.

현재 공개 제품은 토파즈 5.20.4입니다. 현재 언어 모드는 topaz-5.20입니다. 공식 릴리스는 topaz.ooo와 npm에서 제공합니다. 소스는 topaz.ooo/dl에서 확인하세요.

npm 패키지는 컴파일러를 실행 파일 하나에 담으므로 저장소를 복제할 필요가 없습니다. 실행 파일은 리스펙스 애플리케이션 소스와 컴파일러 프로그램 이미지를 압축해 담고, 명령이 처음 필요로 할 때 압축을 풉니다. 빌드한 제품은 토파즈 소스를 지운 뒤에도 실행됩니다. 내장 컴파일러의 식별자가 맞지 않으면 컴파일을 멈추고 불일치를 보고합니다. 토파즈를 다시 설치해 설치본을 복원하세요.

실행 환경 고르기

WASM 빌드에는 Rust의 wasm32-unknown-unknown 대상도 필요합니다. 인터프리터와 백엔드에서 대상을 고르고 전체 예제를 찾으세요. 배포할 때는 빌드 출력 폴더 전체를 복사합니다.

모든 대상은 문법·모듈·타입 검사를 공유합니다. 호스트 연산의 지원 여부는 대상에 따라 다릅니다. 지원하지 않는 연산이 있으면 제품을 쓰기 전에 소스 위치가 담긴 오류를 냅니다. 해당 연산을 고치거나 지원하는 환경을 고르세요. 동시 작업의 실행 순서는 정해져 있지 않습니다. 순서대로 출력하려면 작업을 합류한 뒤 출력하세요.

리스펙스 규칙 실행하기

설치된 평가기는 topaz lispex embed run으로 요청 하나를 실행합니다. 리스펙스 평가기와 LIT에 입력 파일 세 개, 명령, 보고서 필드가 있습니다. 평가가 완료되면 result.lpxvalue와 report.json을 씁니다. 규칙 실행 실패나 리소스 한도 초과 때는 report.json을 씁니다. 요청 거부나 엔진 오류 때는 출력 폴더를 만들지 않습니다.

설치본은 평가기, 프로필, 리소스 규칙, 입력 검사 조건을 고정합니다. 다른 평가기를 내려받거나 콜백·import·폴백을 사용하지 않습니다. CLI 보고서는 토파즈 실행을 기록합니다. 애플리케이션 아티팩트 API는 다른 환경으로 옮길 수 있는 리스펙스 형식의 기록을 만듭니다.

토파즈 애플리케이션에서는 잠긴 std.lispex API로 규칙을 호출하세요. 인터프리터와 다섯 네이티브 릴리스 대상에서 실행됩니다. 리스펙스 규칙 실행하기에서 매니페스트, 잠금, 빌드, 결과 저장과 재실행을 다룹니다. raw-web, worker-web, no-capability, mcp-empty-component-set은 출력이나 실행 전에 이 호출을 거부합니다. --target lispex도 출력 전에 거부합니다. LIT는 리스펙스 통합 테스트 프로그램이며 설치 평가기와 빌드 대상과 구분됩니다.

설치된 컴파일러 상태 읽기

topaz compiler status --json

종료 코드 0과 함께 JSON을 출력합니다. 다음은 기본 컴파일러와 참조 컴파일러를 나타내는 필드를 추린 것입니다.

{
  "schema": "topaz.compiler-support/v5",
  "languageMode": "topaz-5.20",
  "defaultCompiler": "self",
  "referenceCompiler": "rust",
  "silentFallback": false
}

self는 토파즈로 작성한 컴파일러를 선택합니다. parse, check, test, run, bench, emit, build, fmt, lsp, doc, compiler observe가 기본으로 사용합니다. 컴파일러가 실패하면 Rust로 전환하지 않고 명령을 멈춥니다.

compilers에서 selector가 self인 객체를 찾으세요. 그 객체의 필드와 별도 배열인 routes를 다음처럼 읽습니다.

컴파일러 관측 저장하기

컴파일러 관측은 입력 하나를 처리한 과정부터 생성 Rust까지 기록합니다. 컴파일러 결과의 차이를 조사할 때 사용하세요. 소스도 들어 있으므로 소스 프로젝트와 같은 수준으로 폴더를 보호하세요.

빈 작업 폴더를 만들고 다음 내용을 main.tpz로 저장하세요.

print("ready")

그 폴더에서 아래 명령을 실행하세요. ../ 경로는 소스 폴더 옆에 출력을 둡니다. 아직 쓰지 않은 출력 폴더를 고르세요. 소스 루트 안의 출력은 다음 관측에서 자기 파일을 수집할 수 있으므로 거부합니다.

topaz compiler observe main.tpz --out-dir ../topaz-observation
topaz compiler validate ../topaz-observation

두 명령은 종료 코드 0으로 끝나고 다음 줄을 차례로 출력합니다.

../topaz-observation: compiler-observation-ok
../topaz-observation: compiler-observation-valid

관측 폴더에는 sources/, topaz-observation.json, provenance.json과 각 컴파일 단계의 기록이 들어 있습니다. validate는 파일을 바꾸거나 다시 컴파일하거나 원본 소스 트리를 열지 않고 관측 폴더를 읽습니다. 인코딩, 스키마, 순서, 참조, 필수 기록, 크기, 해시를 확인합니다. 검증이 실패하면 오류를 보존하고 원본 소스에서 관측을 새로 만드세요.

컴파일 기록 읽기

설치 실행 파일에는 토파즈 소스에서 생성한 네이티브 컴파일러가 들어 있습니다. 어댑터는 컴파일 전에 내장 소스와 런타임 식별자를 검사합니다. 식별자가 맞지 않으면 명령을 멈춥니다. 대상 소스, 진단, 생성 소스, 출력 파일은 요청마다 새로 계산합니다.

버전이 붙은 컴파일 결과에는 순서대로 나열한 모듈, 토큰, 구문 트리, 해석한 이름과 내보내기, 타입, 프로필 진단이 들어 있습니다. 프로필은 지원 기능과 실행 규칙을 정합니다. 내부 코드 변환(lowering), 필요한 런타임 연산, 생성 Rust, 요청과 결과의 식별자도 기록합니다. 어댑터는 이 기록을 검증하고 디코딩합니다. 컴파일러의 판단이 빠져 있으면 거부합니다.

네이티브 빌드 매니페스트는 컴파일러와 생성자, 컴파일러와 대상의 소스 집합, 컴파일 결과, 생성 소스 해시를 기록합니다. 소스 집합은 한 번의 컴파일에 포함된 파일 모음입니다.

고정점과 생성자 정보 읽기

../topaz-observation/provenance.json을 열면 결과를 만든 컴파일러와 입력을 확인할 수 있습니다. 다음 필드는 서로 다른 검사 결과를 나타냅니다.

{
  "engine": "topaz-native-k",
  "generatedSourceFixedPoint": "established",
  "nativeBinaryReproducibility": "not-run",
  "semanticFixedPoint": "not-established"
}

generatedSourceFixedPoint는 자기 소스를 연속으로 컴파일한 단계에서 생성 Rust 바이트가 같았는지 기록합니다. 이를 생성 소스 고정점이라고 합니다. nativeBinaryReproducibility는 실행 파일 바이트 비교를, semanticFixedPoint는 컴파일러 중간 기록 비교를 나타냅니다. 각 값을 따로 읽으세요. 이 필드들은 관측의 출처 정보 파일에 있습니다. 설치 컴파일러의 링크·소스 식별자와 지원 명령은 위의 상태 JSON에서 확인하세요.

참조 컴파일러와 비교하기

설치 실행 파일에는 검증용 Rust 참조 컴파일러도 들어 있습니다. 같은 소스 폴더에서 수정하지 않은 main.tpz를 참조 컴파일러로 관측하세요.

topaz compiler observe main.tpz --compiler rust --out-dir ../reference-observation
topaz compiler compare --layer semantic ../topaz-observation ../reference-observation

첫 명령은 ../reference-observation을 만들고 ../reference-observation: compiler-observation-ok를 출력합니다. 둘째 명령은 JSON을 출력합니다. equal은 비교 결과, firstFailingPhase는 처음 다른 단계, mismatches는 다른 기록을 나타냅니다. 같으면 종료 코드 0, 다르면 종료 코드 1로 끝납니다.

같은 입력의 컴파일러 기록이 다르면 두 폴더와 JSON 보고서를 보존해 컴파일러 결함을 조사하세요. --compiler rust는 검증할 때 선택합니다. self 컴파일에 실패한 명령이 참조 컴파일러로 다시 실행되지는 않습니다. 정합성과 검증에서 비교 계층과 입력 변경이 JSON에 나타나는 예제를 확인하세요.

관련 문서

• 툴체인 개요
• 인터프리터와 백엔드
• 정합성과 검증
• 히스토리