콘텐츠로 이동

릴리스 빌드

이 페이지는 CLAUDE.md의 구현 노트를 미러합니다. 서브시스템 변경 시 양쪽 다 업데이트하세요.

Cue는 서명되고 노타리된 .app / DMG (macOS)와 PyInstaller 빌드된 .exe + Inno Setup installer (Windows)로 ship. macOS 경로가 더 복잡 — hardened runtime + Apple notary 요구사항 때문.

macOS — Nuitka + Developer ID + 노타리제이션

단일 명령:

bash scripts/build_nuitka.sh

스크립트가 하는 일:

  1. conda cue env 활성화 (uv 빌드 env는 dev용; 빌드 env는 Python / PyGObject / GStreamer / GStreamer 플러그인 간 ABI 일관성 위해 conda). scripts/environment.yml 참고.
  2. Nuitka로 .app 번들로 컴파일.
  3. vendoring된 owa 패키지의 dist-info 번들 — 그래야 importlib.metadata.entry_points()가 플러그인 등록 발견.
  4. 시스템 경로에서 GStreamer.framework 해결 (번들 안 함 — 너무 큼; 사용자가 시스템 전역 GStreamer 설치). PyGObject가 GNU iconv* 심볼셋 찾도록 작은 libiconv 호환성 shim 빌드.
  5. 온디바이스 추론용 llama-server 바이너리를 Cue.app/Contents/MacOS/bin/llama-b<tag>/ 아래 번들 (스크립트가 없으면 자동 다운로드).
  6. Codesign 모든 Mach-O 바이너리 — Developer ID Application 인증서, hardened runtime, embedded entitlements (scripts/release/entitlements.plist), secure timestamp로 serial. 일시적 timestamp-server hiccup에 retry.
  7. Notarize .app을 keychain profile (한 번 xcrun notarytool store-credentials로 설정)으로 xcrun notarytool submit --wait.
  8. notary ticket을 .app에 staple.
  9. DMG 빌드, 같은 Developer ID 신원으로 서명, notary 제출, staple.

산출물은 dist/Cue.app과 dist/Cue-<version>.dmg로 land.

Hardened runtime entitlements

scripts/release/entitlements.plist:

  • com.apple.security.cs.disable-library-validation — 필수, GStreamer.framework dylib이 우리 team-id로 서명되지 않아서.
  • com.apple.security.cs.allow-dyld-environment-variables — run.py가 시스템 GStreamer.framework를 가리키도록 DYLD_LIBRARY_PATH / GST_PLUGIN_PATH / GI_TYPELIB_PATH 설정 후 자기 재실행. Hardened runtime이 이 entitlement 없으면 이런 env var 제거.
  • com.apple.security.cs.allow-jit — GStreamer의 orc SIMD JIT 컴파일러가 pthread_jit_write_protect_np 호출하여 W^X 메모리 토글하기 때문에 필수.

Apple Developer 사전 요구사항

  • Apple Developer Program 멤버십.
  • login keychain에 설치된 Developer ID Application 인증서 (security find-identity -v -p codesigning로 검증).
  • Apple ID + app-specific password + Team ID로 xcrun notarytool store-credentials cue-notarize 한 번 실행.
  • 인증서에 security set-key-partition-list -S apple-tool:,apple: 한 번 실행 — 그래야 codesign이 매 바이너리마다 keychain access 프롬프트 안 함.

빌드 스크립트가 security find-identity로 Developer ID 신원 자동 감지. 없으면 ad-hoc 서명 (--sign -)으로 fallback — 배포 안 하는 로컬 스모크 테스트에 유용.

Windows — PyInstaller + Inno Setup

python scripts/build_installer.py

또는 단계별:

scripts\build_windows.bat       # PyInstaller .exe
python scripts/build_installer.py  # Inno Setup .msi

PyInstaller가 번들된 llama-server.exe를 Cue\bin\llama-b<tag>\ 아래 포함하는 one-folder Cue/ distribution 생성. Inno Setup (scripts/release/cue_setup.iss)이 이를 Windows installer로 wrap — 앱 등록, Start Menu 단축키 셋업, 첫 실행 시 데이터 디렉토리 생성.

Windows 코드 서명은 현재 TBD — installer는 Authenticode 인증서로 SignTool 통해 서명 가능하지만 기본 빌드는 이 단계 skip.

Selftest

Frozen 빌드는 사용자가 hit하기 전에 누락된 native lib을 잡기 위한 selftest 지원:

Cue.app/Contents/MacOS/run --selftest=llama_server_health
Cue.app/Contents/MacOS/run --selftest=llama_server_import

CI 단계가 빌드 후 이를 실행.

번들된 llama-server

온디바이스 디지스트 백엔드는 llama-cpp-python이 아닌 외부 멀티모달 추론 바이너리 사용. 이유는 온디바이스 비전 참고.

빌드 매트릭스:

  • macOS arm64 / x64 — ggml-org/llama.cpp의 llama-<tag>-bin-macos-{arm64,x64}.tar.gz 릴리스 아티팩트.
  • Windows x64 — llama-<tag>-bin-win-cpu-x64.zip 릴리스 아티팩트.

scripts/build_nuitka.sh와 scripts/build_installer.py이 이 바이너리를 다운로드 + 검증 + 번들로 추출. 핀된 릴리스 태그는 scripts/의 매니페스트 편집으로 업데이트.

CI 통합

.github/workflows/ci.yml이 매 push에 ruff lint + format 실행. 앱 릴리스 빌드는 CI에서 안 함 (CI에 없는 keychain 액세스와 Apple Developer 인증서 필요).

.github/workflows/docs.yml은 별도 워크플로:

  • 매 PR + main push에 uv pip install -e ".[docs]"와 uv run --no-sync mkdocs build --strict 실행. 깨진 nav, 누락된 앵커, mkdocstrings import regression을 deploy 전에 잡음.
  • main push 시에는 cloudflare/wrangler-action@v3로 CLOUDFLARE_API_TOKEN + CLOUDFLARE_ACCOUNT_ID repo secret을 사용해 빌드된 site/를 cue Cloudflare Pages 프로젝트에 push (pages deploy site --project-name=cue --branch=main).
  • 이 워크플로에서 서브모듈 fetch는 의도적으로 off — docs 빌드는 ocap이나 owa가 필요 없고, Cloudflare git-connect 플로우는 어차피 우리 private vendor 서브모듈을 못 읽음. 그게 deploy를 Cloudflare Git 통합 대신 GitHub Actions로 보낸 이유.

공개 docs URL: https://cue-aif.pages.dev/.

버전

단일 진실 공급원: pyproject.toml → version. main.py의 _VERSION과 README 푸터도 업데이트.

더 보기