ParaWiki/wiki/cimery 실행 가이드.md

---
title: cimery 실행 가이드
tags: [cimery, build, run, dev-ops]
sources:
  - cimery/CLAUDE.md
  - cimery/Cargo.toml
  - cimery/crates/viewer/Cargo.toml
updated: 2026-04-14
---

# cimery 실행 가이드

cimery 개발·테스트·배포에 필요한 모든 실행 명령 레퍼런스.
작업 디렉터리는 항상 `d:/myObsidian/ParaWiki/cimery/` 기준.

---

## 전제 조건

| 항목 | 버전 | 비고 |
|------|------|------|
| Rust | stable 최신 | `rustup update` |
| wasm-pack | 최신 | WASM 빌드 시만 필요 |
| OpenCASCADE (OCCT) | 7.7+ | `--features occt` 시만 필요. VS Dev Cmd 필수 |

---

## 빌드 & 컴파일 확인

```bash
# 전체 워크스페이스 컴파일 확인 (가장 빠름)
cargo check --workspace

# 전체 빌드
cargo build --workspace

# OcctKernel 포함 빌드 (VS Developer Command Prompt에서)
cargo build -p cimery-kernel --features occt

# 릴리스 빌드
cargo build --release -p cimery-viewer
```

---

## 테스트

```bash
# 전체 워크스페이스 테스트
cargo test --workspace

# kernel 테스트만 (4층: insta 스냅샷·기하 불변량·크로스체크·proptest)
cargo test -p cimery-kernel

# 특정 layer만
cargo test -p cimery-kernel --test layer1_snapshots
cargo test -p cimery-kernel --test layer2_invariants
cargo test -p cimery-kernel --test layer3_cross_check
cargo test -p cimery-kernel --test layer4_proptest

# OcctKernel 크로스체크 포함 (--features occt 필요)
cargo test -p cimery-kernel --features occt

# 특정 크레이트
cargo test -p cimery-core
cargo test -p cimery-ir
cargo test -p cimery-dsl
cargo test -p cimery-incremental
cargo test -p cimery-usd
```

### insta 스냅샷 업데이트

IR 구조가 바뀌어 스냅샷을 갱신해야 할 때:

```bash
# 새 스냅샷을 .snap.new 로 생성
INSTA_UPDATE=new cargo test -p cimery-kernel --test layer1_snapshots

# .snap.new → .snap 수동 승인 (cargo-insta 미설치 시)
cd crates/kernel/tests/snapshots
for f in *.snap.new; do mv "$f" "${f%.new}"; done

# 또는 cargo-insta 설치 후
cargo install cargo-insta
cargo insta review
```

---

## 뷰어 실행

```bash
# PureRustKernel (기본, OCCT 불필요)
cargo run -p cimery-viewer

# OcctKernel 포함 (VS Dev Cmd에서)
cargo run -p cimery-viewer --features cimery-kernel/occt

# 릴리스 빌드로 실행 (성능 향상)
cargo run --release -p cimery-viewer
```

### 뷰어 단축키

| 키 | 동작 |
|----|------|
| `F` | ZoomExtents (전체 씬 맞추기) |
| `1` | 정면뷰 |
| `3` | 측면뷰 |
| `7` | 평면뷰 |
| `0` | 투시뷰 |
| 마우스 휠 | 줌 |
| 마우스 중간버튼 드래그 | 팬 |
| 우클릭 드래그 | 궤도 회전 |
| `Enter` | Apply (파라미터 적용) |
| `Ctrl+S` | 프로젝트 저장 |
| `Ctrl+O` | 프로젝트 열기 |

---

## USD 익스포트

```bash
# cimery-usd 크레이트 직접 실행
cargo run -p cimery-usd

# 출력: out/bridge_scene.usda (기본 경로)
```

### USD 파일 구조

```
#usda 1.0
def Xform "BridgeScene" {
    def Xform "Girders" { ... }
    def Xform "DeckSlabs" { ... }
    def Xform "Bearings" { ... }
    def Xform "Piers" { ... }
    def Xform "Abutments" { ... }
    def Xform "CrossBeams" { ... }
    def Xform "ExpansionJoints" { ... }
}
```

---

## WASM / PWA 빌드

```bash
# wasm-pack으로 viewer 빌드
wasm-pack build crates/viewer --target web --features wasm

# 출력 디렉터리: crates/viewer/pkg/
# Cloudflare Pages 배포: .github/workflows/wasm.yml 참조
```

---

## CI/CD

| 워크플로 | 경로 | 트리거 | 내용 |
|----------|------|--------|------|
| Gitea CI | `.gitea/workflows/ci.yml` | push/PR | check → test → clippy → fmt |
| GitHub CI | `.github/workflows/ci.yml` | push/PR | 멀티플랫폼(Ubuntu·Windows·macOS), OCCT 조건부 |
| GitHub Release | `.github/workflows/release.yml` | `v*` 태그 | 바이너리 빌드 + GitHub Release 업로드 |
| WASM Deploy | `.github/workflows/wasm.yml` | main push | wasm-pack 빌드 + Cloudflare Pages 배포 |

```bash
# 릴리스 태그 생성 (자동 빌드 트리거)
git tag v0.1.0
git push origin v0.1.0
```

---

## 크레이트 의존 관계

```
core → ir → { dsl, kernel, usd } → incremental → evaluator
                                               ↓
                                            viewer
```

| 크레이트 | 역할 |
|----------|------|
| `cimery-core` | 단위 타입(Mm·M), 도메인 열거형 |
| `cimery-ir` | IR 구조체 + serde JSON 직렬화 |
| `cimery-dsl` | Feature 빌더 + 검증 |
| `cimery-kernel` | GeomKernel trait + StubKernel + PureRustKernel + OcctKernel |
| `cimery-incremental` | dirty-tracking 증분 캐시 |
| `cimery-evaluator` | IR → kernel 연결 레이어 |
| `cimery-usd` | USD 텍스트 익스포터 |
| `cimery-viewer` | wgpu + egui 3D 뷰어 |
| `cimery-app` | Tauri v2 데스크톱 래퍼 (개발 중) |

---

## 프로젝트 파일 (`.cimery`)

뷰어에서 저장하는 JSON 포맷:

```json
{
  "version": 1,
  "span_m": 40.0,
  "girder_count": 5,
  "girder_spacing_mm": 2500.0,
  "girder_height_mm": 1800.0,
  "slab_thickness_mm": 220.0,
  "show_cross_beams": true,
  "cross_beam_interval_m": 5.0,
  "show_expansion_joints": true
}
```

저장/불러오기: 뷰어 SidePanel → **▼ 프로젝트** → 저장 / 열기

---

## 자주 쓰는 커맨드 조합

```bash
# 개발 루프: 변경 후 즉시 확인
cargo check -p cimery-kernel && cargo test -p cimery-kernel && cargo run -p cimery-viewer

# 커밋 전 전체 검증
cargo test --workspace && cargo clippy --workspace -- -D warnings

# 새 crate 추가 후 workspace 등록 확인
cargo check --workspace
```

---

### 아키텍처

```
cimery-app (Tauri v2)
  │  WebView: frontend/index.html  ← 런처 UI (다크 테마)
  │  IPC: #[tauri::command]        ← commands.rs
  │
  └─ cimery-viewer (사이드카)
       egui+wgpu 3D 뷰어 (기존 바이너리)
       exe/앱 번들과 같은 디렉터리에서 탐색 → PATH fallback
```

### 다음 빌드 명령

```bash
# 뷰어 먼저 릴리스 빌드 (앱과 같은 디렉터리에 복사 필요)
cargo build --release -p cimery-viewer

# Tauri 개발 서버 (설치 없이 실행)
```bash
cd cimery/crates/app
cargo tauri dev
```
```
cargo tauri dev -p cimery-app

# 설치 파일 생성 (Win: .msi/.exe, macOS: .dmg, Linux: .deb)
cargo tauri build -p cimery-app
```



## 관련 문서

- [[cimery 아키텍처 개요]] (미작성 — ADR-001 참조)
- `Output/guides/cimery-dev-guide.md` — 상세 개발 지침
- `Output/reports/ADR-001-tech-stack.md` — 기술 스택 결정
- `Output/reports/ADR-002-feature-dsl.md` — Feature DSL 아키텍처
- `Output/reports/ADR-003-architecture-followups.md` — 후속 12개 결정