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

애플리케이션 루프

배포 대상에 맞춰 네이티브, 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.15"
entry = "src/main.tpz"

[build]
target = "native"
deterministic = true

[dependencies]
std = "5.15"

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

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 서비스에서 이 경로를 끝까지 다룹니다. 예산, 관찰 가능한 실패, 소스 없는 실행과 배포 복구를 이어서 봅니다.

관련 문서