토파즈문서
인터롭

Rust 백엔드

검증을 마친 토파즈 패키지를 관리형 플랫폼 실행 파일로 빌드합니다. 토파즈 소스 트리가 없는 환경에서도 실행됩니다.

빌드 타깃 머신의 운영체제와 아키텍처에서 실행되는 플랫폼 실행 파일이 필요할 때 Rust 경로를 선택합니다. Rust는 빌드 타깃일 뿐이며, Rust 토큰이 토파즈 문법으로 변환되는 것은 아닙니다.

준비 사항

  • 첫 애플리케이션의 study-plan 패키지를 완성합니다.
  • topaz.toml, topaz.lock, src/plan.tpz, src/main.tpz 파일과 선택 테스트를 한곳에 배치합니다.
  • 빌드 머신에 호환되는 Rust 툴체인과 Cargo를 설치합니다.
  • 다음 명령은 study-plan 디렉터리에서 실행합니다.

빌드된 실행 파일은 토파즈 런타임, Cargo, .tpz 소스 파일 없이 작동합니다. 단, 빌드 대상 운영체제와 아키텍처에 맞추어 생성된 바이너리입니다.

공유하는 검사 대상 패키지

Python 문서 예제에서도 동일한 두 토파즈 모듈을 공유합니다. 먼저 src/plan.tpz입니다.

TOPAZ
export record 학습과제 {
    제목: string,
    분: int,
    완료: bool = false,
}

function 분해석(텍스트: string) -> Result<int, string> {
    match toInt(텍스트) {
        case Some(값) if 값 > 0 => Ok(값)
        case _ => Err("minutes must be a positive integer")
    }
}

export function 과제만들기(
    제목: string,
    분문자열: string,
    완료: bool = false,
) -> Result<학습과제, string> {
    let 분 = 분해석(분문자열)?
    Ok(학습과제 { 제목: 제목, 분: 분, 완료: 완료 })
}

export function 요약(과제들: Array<학습과제>) -> string {
    let mut 남음 = 0
    for 과제 in 과제들 {
        if !과제.완료 {
            남음 = 남음 + 과제.분
        }
    }
    "tasks={과제들.length}, remaining={남음} minutes"
}

패키지 진입점인 src/main.tpz입니다.

TOPAZ
import src.plan { 학습과제, 과제만들기, 요약 }

export function main(인자: Array<string>, 표준입력: string) -> Result<int, string> {
    let 과제들: Array<학습과제> = [
        과제만들기("Run first program", "10", true)?,
        과제만들기("Build application", "25", false)?,
    ]
    print(요약(과제들))
    Ok(0)
}

토파즈 소스 검증하기

먼저 패키지를 검사합니다. 이어서 선택 테스트를 실행합니다. 마지막으로 기준 출력을 확인합니다.

BASH
topaz check --root . --locked
topaz test tests/plan.tpz --root . --locked
topaz run --root . --locked

테스트 실행 시 tests/plan.tpz: test-ok가 출력됩니다. 실행 결과는 다음과 같습니다.

출력
tasks=2, remaining=25 minutes

검토에는 emit, 배포에는 build

생성된 Cargo 소스 아티팩트를 직접 검토하거나 다른 코드베이스에 통합할 때만 emit을 사용합니다.

BASH
topaz emit --target rust --root . --locked --out-dir ../dist/rust-source

관리형 플랫폼 실행 바이너리는 build로 생성합니다.

BASH
topaz build --target native --root . --locked --out-dir ../dist/native

build --target rust는 올바른 명령이 아닙니다. rust는 emit에 지정하는 타깃입니다. build로 만드는 배포 타깃은 native입니다.

관리형 제품 확인하기

기본 디버그 빌드 시 생성되는 파일 구조는 다음과 같습니다.

출력
dist/native/
├── GENERATED-OUTPUT-NOTICE.txt
├── LICENSE
├── NOTICE
├── target
│   └── debug
│       └── program[.exe]
└── topaz-artifact.json

topaz-artifact.json에는 native 타깃 정보, 실행에 필요한 OS와 아키텍처 요건, 실행 명령, 모든 관리 타깃 파일의 크기 및 SHA-256 해시가 기록됩니다. 토파즈는 아티팩트 명세를 빌드 마지막 단계에 작성합니다. 관리 파일이 변경되었거나, 충돌이 발생했거나, 동일한 출력 디렉터리에 다른 타깃 아티팩트가 존재하는 경우에는 작업을 거부합니다.

토파즈 소스를 사용할 수 없는 곳에서 실행하기

dist 디렉터리는 패키지 외부에 위치합니다. 원본 패키지 디렉터리명을 변경한 후 빌드된 실행 파일만 단독으로 실행합니다.

BASH
cd ..
mv study-plan source-unavailable
./dist/native/target/debug/program

Windows 환경에서는 Rename-Item study-plan source-unavailable을 먼저 실행합니다. 그다음 .\dist\native\target\debug\program.exe를 실행합니다. 실행 결과는 이전과 동일하며, 종료 코드는 0입니다.

타깃별 복구

  • Cargo 툴체인이 없거나 호환되지 않을 때는 빌드 머신 환경을 먼저 조치합니다. 그다음 다시 빌드합니다.
  • --release 옵션은 target/release/program[.exe]를 생성하며, 빌드 프로필만 변경됩니다.
  • 기본 코드 생성 과정에서는 값을 감싸는 공통 Rust 런타임 환경을 사용합니다. 선택 옵션인 --backend native는 검증된 범위만 특수화하며, 지원하지 않는 타입은 추측하지 않고 공통 값 표현 그대로 유지합니다.
  • 생성된 플랫폼 실행 파일을 다른 OS나 아키텍처로 복사한 뒤 공식 지원 배포판으로 취급해서는 안 됩니다.

정확한 경계

생성된 Rust 코드와 런타임 결과물은 언제든 재생성 가능한 빌드 결과물입니다. 수동으로 확장하는 API나 소스 레벨의 Rust FFI가 아닙니다. 정상 실행되었다면 해당 타깃 환경에서 해당 프로그램이 도출한 출력과 종료 코드에 관한 실행 검증을 완료한 것입니다. 사용자가 작성한 래퍼는 별도의 호스트 코드 계약에 따라 검토합니다.

패키지가 제한 리스펙스 규칙을 결합하는 경우 빌드하기 전에 리스펙스 규칙 실행하기를 참고하세요. 승인된 네이티브 타깃만 이 애플리케이션 프로필을 포함하며, 지원하지 않는 경로는 아티팩트를 생성하기 전에 실패합니다. 상호 운용 개요, Python 백엔드, 인터프리터와 백엔드, 아티팩트와 배포 문서도 함께 참고하세요.