토파즈문서
애플리케이션 만들기

애플리케이션 루프

배포 대상에 맞춰 네이티브, Python, Web 또는 제한형 HTTP 경로를 선택하고 완주합니다.

첫 애플리케이션을 마친 뒤 이 페이지를 사용하세요. 작성 과정은 공통이지만 배포 과정은 다릅니다. 모든 대상을 차례로 빌드하지 말고 필요한 제품 하나를 선택합니다.

  • 언어 런타임 없이 특정 플랫폼에서 실행할 파일 하나가 필요하면 네이티브를 선택합니다.
  • 배포 환경에 Python 3.11 이상이 이미 있다면 Python을 선택합니다.
  • 브라우저의 모델, 메시지, 상태 갱신과 화면을 토파즈가 소유한다면 Web 애플리케이션을 선택합니다.
  • 검사된 요청 핸들러를 프로세스 관리자와, 공개 서비스라면 리버스 프록시 뒤에서 실행하려면 제한형 HTTP 서비스를 선택합니다.

Raw Web과 Worker 패키지는 기존 JavaScript 호스트에 연결하는 제품입니다. WASM과 플레이그라운드에서 설명합니다.

공통 작성 과정

검사된 두 모듈 패키지에서 시작합니다. 현재 네이티브 패키지 매니페스트의 식별자는 다음과 같습니다. 파일 이름은 topaz.toml입니다.

TOML
[package]
name = "task_summary"
version = "0.1.0"
language = "5.11"
entry = "src/main.tpz"

[build]
target = "native"
deterministic = true

[dependencies]
std = "5.11"

보조 모듈은 애플리케이션의 계산을 담당합니다.

TOPAZ
export function remainingMinutes(values: Array<int>) -> int {
  let mut total = 0
  for value in values {
    total += value
  }
  total
}

진입 모듈은 계산 결과를 눈으로 확인할 수 있는 명령으로 만듭니다.

TOPAZ
import src.summary { remainingMinutes }

export function main(args: Array<string>, stdin: string) -> Result<int, string> {
  let minutes = remainingMinutes([10, 25])
  print("remaining={minutes}")
  Ok(0)
}

topaz.lock을 한 번 만든 뒤 평소 작업도 같은 순서로 진행합니다.

BASH
topaz lock --root task-summary
topaz fmt --check --root task-summary
topaz check --root task-summary --locked
topaz test --root task-summary --locked
topaz run --root task-summary --locked

fmt --check는 파일을 바꾸지 않고 서식 차이만 알립니다. check나 test가 실패하면 제품을 쓰기 전에 멈춥니다. 첫 토파즈 진단을 고친 뒤 같은 명령을 다시 실행하세요. 진단 코드의 자세한 설명은 topaz explain TPZ####로 확인할 수 있습니다.

경로 A: 네이티브 또는 Python 명령형 애플리케이션

네이티브 빌드에는 현재 운영체제와 아키텍처를 지원하는 Rust 도구 모음이 필요합니다. Python 빌드에는 Rust가 필요하지 않지만 완성 제품을 실행하려면 Python 3.11 이상이 필요합니다.

배포할 제품만 빌드합니다.

BASH
topaz build --release --root task-summary --locked --out-dir native-product
topaz build --target python --root task-summary --locked --out-dir python-product

릴리스 산출물은 다음과 같습니다.

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

python-product/
├── GENERATED-OUTPUT-NOTICE.txt
├── LICENSE
├── NOTICE
├── program.py
├── topaz-artifact.json
└── topaz_py_rt.py

program[.exe]는 Unix의 program과 Windows의 program.exe를 함께 나타냅니다. 선택한 디렉터리 전체를 새 위치로 복사하고 그 루트에서 실행합니다.

BASH
./target/release/program
python3 program.py

첫 명령은 네이티브 제품에서, 둘째 명령은 Python 제품에서 사용합니다. 둘은 대안입니다. 애플리케이션이 [capabilities.fs]를 선언했다면 제품 옆에 data/와 쓰기 가능한 출력 디렉터리를 두고 그 위치를 작업 디렉터리로 유지하세요. 애플리케이션 데이터는 네이티브나 Python 제품에 자동으로 들어가지 않습니다.

Rust 도구 모음이 없다는 빌드 오류가 나오면 맞는 Rust 도구 모음을 설치하거나 Python을 선택하세요. 출력 디렉터리에 다른 대상이나 변경된 관리 파일이 있다면 조사를 위해 보존하고 새 빈 디렉터리에 빌드합니다.

경로 B: 관리형 Web 애플리케이션

Web 애플리케이션 빌드에는 wasm32-unknown-unknown 대상이 설치된 Rust 도구 모음이 필요합니다. 명령형 진입점을 변환하지 말고 검사된 스캐폴드를 만듭니다.

BASH
topaz init --target web-app --root hello-web
topaz lock --root hello-web
topaz fmt --check --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-product

생성된 진입점은 검사되는 생명주기를 사용합니다.

TOPAZ
import std.dom { Html, WebAppEvent, WebAppStep, text }

export record Model {
  message: string,
}

export enum Msg {
  Ready,
}

export function init() -> WebAppStep<Model, Msg> {
  WebAppStep { model: Model { message: "Hello from Topaz" }, commands: [] }
}

export function update(model: Model, message: Msg, event: WebAppEvent) -> WebAppStep<Model, Msg> {
  WebAppStep { model: model, commands: [] }
}

export function view(model: Model) -> Html<Msg> {
  text(model.message)
}

topaz dev는 루프백 개발 서버이며 잘못된 수정 뒤에도 마지막 정상 제품을 유지합니다. 프로덕션 서버는 아닙니다. 최종 디렉터리에는 HTML, 검사된 애플리케이션 호스트, Raw Web 연결 계층, WASM, 권한 메타데이터, 선언한 스타일·자산과 공통 라이선스·산출물 파일이 들어갑니다. 디렉터리 전체를 정적 호스트로 복사해 HTTP로 제공하세요. ES 모듈을 file://로 여는 방식은 배포 경로가 아닙니다.

Data Lens는 이 경로를 사용하는 유지 관리 대상 다중 모듈 예제입니다.

경로 C: 제한형 HTTP 서비스

제품이 명령이나 브라우저 UI가 아니라 요청 핸들러라면 서비스 스캐폴드를 만듭니다.

BASH
topaz init --target http-service --root hello-service
topaz lock --root hello-service
topaz fmt --check --root hello-service
topaz check --root hello-service --locked
topaz test --root hello-service --locked
topaz dev --root hello-service --port 8080
topaz build --root hello-service --locked --release --out-dir service-product

핸들러 경계는 구체적이며 동기식입니다.

TOPAZ
import std.http { HttpRequest, HttpResponse, text }

export function handle(req: HttpRequest) -> HttpResponse {
  if req.url.path() == "/health" {
    return text(200, "ok")
  }
  text(404, "not found")
}

서비스 제품에는 네이티브 실행 파일 하나, 내장된 제한형 기본값, 제3자 고지와 공통 산출물 파일이 들어갑니다. 기본 바인드 주소는 루프백입니다. 루프백이 아닌 주소는 명시적인 프로세스 인수가 필요하며 TLS, HTTP/2, 아웃바운드 네트워크와 범용 Web 프레임워크를 추가하지 않습니다.

제한형 HTTP 서비스에서 예산, 관찰 가능한 실패, 소스 없는 실행과 배포 복구까지 이 경로를 완성합니다.

관련 문서