# 개발

> Rust와 DuckDB로 소스에서 DuckLocal을 빌드하고, 테스트를 실행하고, macOS 앱을 번들로 묶고, macOS, Linux, Windows용 릴리스를 만듭니다.

Source: https://ducklocal.app/docs/ko/development

## 빌드와 실행 {#build-and-run}

```bash
cargo run                     # empty in-memory workspace
cargo run -- ./data/logs/     # open something straight away
cargo test --workspace        # run the test suite, Quick Look engine included
```

DuckDB는 벤더링된 소스 코드에서 직접 컴파일되므로 첫 빌드는 눈에 띄게 오래 걸리고 몇 기가바이트의 디스크 공간이 필요합니다. dev 프로파일의 의존성은 `opt-level = 3`으로 컴파일되므로 첫 빌드는 더 길어지지만, 반복 개발은 쾌적하게 유지됩니다. 이후 컴파일에서는 `ducklocal`만 다시 빌드합니다.

**컴팩트 빌드.** `cargo build --profile compact --locked`는 더 작은 바이너리를 `target/compact/`에 씁니다. `compact` 프로파일은 `release`(LTO, 심볼 제거, `panic = "abort"`)를 상속하되 Rust는 크기 기준으로 컴파일하고(`opt-level = "s"`), `libduckdb-sys`는 `opt-level = 3`을 유지하므로 DuckDB의 스캔, 필터, 집계 루프는 빠른 채로 남습니다. 다운로드 크기나 디스크 크기가 프레임과 쿼리 속도보다 중요할 때 사용하세요. 둘 다 대상 머신에서 측정하세요. 릴리스 워크플로와 그것이 배포하는 패키지는 일반 `release` 프로파일을 씁니다.

**툴체인.** `rust-toolchain.toml`도 `rust-version` 키도 없으므로, 실질적인 하한은 의존성이 정합니다. `duckdb`가 요구하는 `1.85.1`입니다. CI는 그냥 stable을 씁니다.

## 고정된 툴킷

UI 툴킷인 `gpui-kit`은 `longbridge/gpui-kit` 저장소에서 오며, 의도적으로 단일 git 리비전에 고정되어 있습니다. 두 리비전을 섞으면 `gpui-base` 사본 두 개가 빌드에 들어가고, 빌드는 실제 원인을 알려주지 않는 trait 불일치 오류로 실패합니다.

```bash
./scripts/check-deps.sh
```

이 스크립트는 Cargo가 하지 않는 검사를 합니다. 그 저장소에 대한 모든 의존성이 하나의 리비전을 쓰는지, `Cargo.lock`이 그것과 일치하는지, 같은 크레이트가 빌드에 두 번(한 번은 저장소에서, 한 번은 crates.io에서) 들어가지 않는지입니다. 매니페스트 두 개만 읽고 그 밖에는 아무것도 하지 않으므로 오프라인에서 즉시 끝납니다. CI는 테스트 전에 이것을 실행합니다. 더 새로운 툴킷으로 옮기려면 `Cargo.toml`의 모든 `rev`를 함께 바꾸고, `cargo update`를 실행한 뒤 스크립트를 실행하세요.

git 리비전에 고정한 것은 DuckLocal 크레이트를 crates.io에 게시할 수 없는 이유이기도 합니다. crates.io는 git 의존성을 거부합니다. 배포는 아래의 릴리스 패키지로 합니다.

## macOS 앱 번들 만들기

```bash
./scripts/bundle.sh
# produces target/release/DuckLocal.app
```

이 스크립트는 번들을 조립합니다. 바이너리는 `Contents/MacOS/ducklocal`에, 그 밖에 `assets/Info.plist`, `assets/AppIcon.icns`, Quick Look 확장 기능이 들어갑니다. 하지만 배포용 **서명은 하지 않습니다**. 결과물은 본인 머신에서는 실행되지만, 다른 곳에서는 Gatekeeper가 거부합니다.

### Quick Look 확장 기능

Finder에서 Parquet, DuckDB, CSV, TSV, JSON Lines 파일을 스페이스 바로 미리 보는 기능은 앱 확장 기능 `DuckLocalPreview.appex`이며, 앱의 `Contents/PlugIns`에 있습니다. 두 부분으로 되어 있습니다.

- `quicklook/`은 워크스페이스 크레이트 `ducklocal-quicklook`입니다. Rust로 작성된 미리보기 엔진을 정적 라이브러리로 빌드합니다. 앱과 같은 번들 DuckDB(같은 lockfile에서 오므로 DuckDB는 한 번만 컴파일됩니다)로 파일을 열고, 열과 처음 50행을 하나의 자족적인 HTML 페이지로 렌더링합니다. 확장 기능은 자체 샌드박스 프로세스이므로 앱을 호출할 수 없습니다.
- `quicklook/extension/`은 그 주위의 Swift 껍데기입니다. `PreviewProvider.swift`, C 헤더, 확장 기능의 `Info.plist`(미리 볼 콘텐츠 타입), 샌드박스 권한 파일이 있습니다.

```bash
scripts/build-quicklook.sh <DuckLocal.app> [signing identity]
```

이 스크립트는 엔진을 빌드하고(`cargo build --release -p ducklocal-quicklook`, 또는 릴리스 워크플로처럼 `RUST_TARGET`이 설정되어 있으면 그 대상으로 빌드하므로 앱의 DuckDB 빌드가 재사용됩니다), macOS 12용으로 `swiftc`로 Swift 껍데기를 그것에 맞춰 컴파일하고, 앱 버전이 찍힌 `Info.plist`를 복사하며, 확장 기능 자체의 권한 파일로 `.appex`에 서명합니다. 서명 identity가 없으면 ad hoc 서명입니다. `bundle.sh`는 identity 없이 이것을 호출합니다. macOS는 앱을 한 번 실행하거나 등록한 뒤에 확장 기능을 찾습니다.

## 패키징, 서명, 공증

```bash
scripts/package-macos.sh <binary> <output.dmg> <version>
```

저장소 루트에서 실행하세요. 작업 디렉터리에 `DuckLocal.app`과 `dmg-root`를 만들고 그 옆에 dmg를 씁니다. 이 스크립트는 자격 증명 없이는 실행을 거부합니다. 공증되지 않은 산출물은 요즘 macOS에서 사용자가 열 수 없으므로, 실수로 만들어 내는 대신 빨리 실패합니다.

필요한 것:

| 변수 | 의미 |
| --- | --- |
| `NOTARY_KEY` | App Store Connect API 키(`.p8`)의 경로 |
| `NOTARY_KEY_ID` | 그 키의 Key ID |
| `NOTARY_ISSUER` | 그 키가 속한 발급자 UUID |
| Developer ID Application identity | 키체인에 정확히 하나 있으면 자동 감지되고, 아니면 `MACOS_SIGN_IDENTITY`를 설정 |

스크립트는 다음 단계를 수행합니다.

1. 번들을 빌드하며, 버전은 인자에서 찍습니다.
2. `build-quicklook.sh`로 Quick Look 확장 기능을 빌드하고, Developer ID와 확장 기능 자체의 샌드박스 권한 파일로 서명합니다. 절대 `scripts/entitlements.plist`가 아닙니다. 앱 확장 기능은 샌드박스여야 하고 앱은 그렇지 않기 때문입니다.
3. 안쪽부터 바깥쪽으로, `--deep` 없이, 내부 실행 파일과 그다음 앱을 `--options runtime --timestamp`와 `scripts/entitlements.plist`로 서명하고, 결과를 `codesign --verify --deep --strict`로 검증합니다.
4. `/Applications` 심볼릭 링크가 있는 UDZO dmg를 만듭니다.
5. **dmg 자체에 서명합니다.**
6. `notarytool submit --wait --timeout 300m`로 제출합니다.
7. 티켓을 스테이플합니다.
8. `stapler validate`와 두 번의 `spctl --assess` 검사로 마무리합니다.

사용하기 전에 알아 둘 두 가지가 있습니다.

- 5시간 타임아웃은 클라이언트 쪽 대기 시간이지 취소가 아닙니다. 만료되더라도 제출은 Apple 쪽에서 계속 처리되고 티켓은 나중에 받을 수 있습니다. 다만 **티켓은 제출된 바로 그 바이트에 묶이므로** 다시 빌드하지 말고, 제출했던 파일에 스테이플하세요.
- 공증되는 것은 dmg뿐이므로 내부의 `.app`에는 스테이플된 티켓이 없습니다. 방금 마운트한 이미지에서 처음 실행할 때는 Apple과 확인하기 위해 네트워크가 필요합니다.

`com.apple.security.cs.disable-library-validation` 권한이 필요한 이유는 DuckDB가 확장 기능을 `dlopen`하기 때문이며, `httpfs`도 그중 하나입니다.

## CI와 릴리스

| 워크플로 | 트리거 | 하는 일 |
| --- | --- | --- |
| `ci.yml` | `main`으로의 푸시, 모든 풀 리퀘스트 | `macos-latest`에서: `scripts/check-deps.sh`, `cargo fmt --all --check`, `cargo clippy --locked --workspace --all-targets -- -D warnings`, 그다음 `cargo test --locked --workspace`(앱과 Quick Look 크레이트). `windows-latest`에서: `cargo test --locked`(`perf_probe` 테스트는 건너뜀), 그다음 디버그 실행 파일에 `scripts/check-windows.py`. `ubuntu-22.04`에서: `cargo build --locked` |
| `release.yml` | `v*`와 일치하는 태그, 또는 버전을 지정한 수동 실행 | 빌드 세 개: `aarch64-apple-darwin`은 `package-macos.sh`로 서명·공증해 `ducklocal-macos-arm64.dmg`로, Linux는 Ubuntu 22.04에서 `ducklocal-linux-x86_64.tar.gz`로, Windows는 `scripts/check-windows.py`가 릴리스 실행 파일을 검증한 뒤 `ducklocal-windows-x86_64.zip`으로. 릴리스 작업은 세 빌드를 모두 기다리며, 하나가 실패하면 릴리스가 실패하고, 자동 생성된 노트로 GitHub 릴리스를 만듭니다 |
| `gh-pages.yml` | 리다이렉트 스크립트나 워크플로를 건드리는 `main`으로의 푸시, 또는 수동 실행 | 예전 `jetsquirrel.github.io/DuckLocal/` 주소에서 GitHub Pages의 새 사이트로 가는 리다이렉트를 게시합니다 |

릴리스 빌드에는 다음 저장소 시크릿이 필요합니다: `MACOS_CERTIFICATE`, `MACOS_CERTIFICATE_PWD`, `NOTARY_KEY_BASE64`, `NOTARY_KEY_ID`, `NOTARY_ISSUER`.

## 플랫폼 지원

| 플랫폼 | 패키지 | 비고 |
| --- | --- | --- |
| macOS 12+, Apple silicon | `.dmg`, 서명 및 공증, Quick Look 확장 기능 포함 | CI에서 테스트하며 Quick Look 크레이트도 포함 |
| Linux x86_64 | 바이너리 `.tar.gz` | Ubuntu 22.04에서 빌드해 대부분의 배포판에 맞는 충분히 오래된 glibc를 쓰며, gpui-kit 자체 CI가 설치하는 시스템 라이브러리를 포함 |
| Windows x86_64 | `ducklocal.exe`의 `.zip` | CI에서 테스트. 코드 서명 없음: Windows 인증서가 없어 첫 실행 시 SmartScreen 경고가 뜸 |

테스트는 macOS와 Windows에서 실행됩니다. Linux는 모든 풀 리퀘스트에서 컴파일되지만 테스트되지는 않습니다. Windows에서 테스트하는 이유는 그 경로(드라이브 문자, `\`, `$HOME` 없음)가 macOS 실행으로는 잡지 못하는 실수가 있는 곳이기 때문입니다. 이어서 `scripts/check-windows.py`(표준 라이브러리만 쓰는 Python, Windows에서 실행)가 GUI를 실행하지 않고 실행 파일을 검사합니다. GUI 서브시스템이라 콘솔 창이 열리지 않는지, 내장된 오리 아이콘, 그리고 `--version`과 `query`가 리다이렉트된 출력에 쓰는지입니다. Intel Mac 빌드는 없습니다.

단축키는 gpui의 `secondary` 수정자로 지정됩니다. macOS에서는 ⌘, Windows와 Linux에서는 Ctrl입니다. `cmd`를 쓰면 Windows와 Linux에서 Windows 키가 되어 모든 단축키에 닿을 수 없게 됩니다.

## 문서 사이트

웹사이트는 별도 저장소 [JetSquirrel/ducklocal-site](https://github.com/JetSquirrel/ducklocal-site)에 있으며, Cloudflare Workers가 정적 자산으로 서비스합니다.

| 주소 | 내용 | 소스 |
| --- | --- | --- |
| [ducklocal.app](https://ducklocal.app/) | 제품 페이지 | `home/`, 정적 HTML과 CSS |
| [ducklocal.app/docs](https://ducklocal.app/docs/) | 이 가이드들, 영어와 중국어 | `docs/`, [VitePress](https://vitepress.dev/) 사이트 |

가이드의 내용을 바꾸는 앱 변경은 두 저장소 모두에 풀 리퀘스트가 필요합니다. 가이드를 로컬에서 작업하려면 Node.js 22 이상(24 LTS 권장)과 사이트 저장소 클론이 필요합니다. 그다음 다음을 실행하세요.

```bash
npm --prefix docs ci             # install the locked dependencies
npm --prefix docs run dev        # http://localhost:5173/docs/
sh scripts/build.sh              # the whole site, product page and docs, in dist/site
```

예전 GitHub Pages 주소인 `jetsquirrel.github.io/DuckLocal/`은 해당하는 새 페이지로 가는 리다이렉트 모음으로 유지되며, 이 저장소의 `gh-pages.yml`이 그것을 게시합니다.

## 프로젝트 구조

| 경로 | 내용 |
| --- | --- |
| `src/main.rs` | 진입점, 초기 CLI 디스패치, GUI 창 설정 |
| `src/cli.rs` | 헤드리스 인자, DuckDB 파서 검증, 격리된 연결, JSON 오류와 그 힌트 |
| `tests/cli.rs` | 실제 실행 파일 통합 테스트. 임시 데이터는 `target/cli-tests` 아래 |
| `skills/ducklocal/` | 공식 스키마 우선 SQL 에이전트 스킬과 CLI 레퍼런스 |
| `src/sources.rs` | 경로를 연결할 파일과 열 데이터베이스로 해석 |
| `src/db.rs` | DuckDB 연결, 파일 연결, 서버 정보 |
| `src/query.rs` | 쿼리 실행, 결과 직렬화, 내보내기, EXPLAIN, 그리고 **프로파일** 뒤의 EXPLAIN ANALYZE 프로파일 |
| `src/script.rs` | 편집기 텍스트를 실행이 순서대로 수행할 문으로 나누기. 점 명령 포함 |
| `src/overview.rs` | 결과의 **개요** 탭: 열별 통계와 분포 |
| `src/extensions.rs` | 사이드바의 **확장 기능** 탭: 목록, `INSTALL`, `LOAD`, `UPDATE EXTENSIONS` |
| `src/storage.rs` | `.duckdb` 파일 헤더 읽기: 파일이 열리지 않는 이유, 열리는 파일은 어느 DuckDB가 읽는지 |
| `src/schema_cli.rs` | `ducklocal schema`: 쿼리할 관계와 열. 프롬프트에 맞춘 크기 |
| `src/profile.rs` | `ducklocal schema --stats` 뒤의 열 통계 |
| `src/remote.rs` | `ducklocal open`: 실행 중인 창과의 루프백 채널, 양방향 |
| `src/schema.rs` | 사이드바를 위한 카탈로그 내부 조회 |
| `src/spec/` | `.dash` 대시보드: 파서, 검증, 소스, 필터, 검토 주석(`ducklocal comments`), `ducklocal lsp`, 그리고 plot이 있는 대시보드 탭 |
| `src/excel.rs` | Excel과 ODS 워크북. 시트마다 테이블 하나로 불러오기 |
| `src/setup.rs` | **명령줄 및 AI…**: `ducklocal`을 PATH에 넣고 에이전트 스킬 설치 |
| `src/recents.rs` | 사이드바에 나열되는 최근에 연 대시보드 |
| `src/history.rs` | 앱 자체의 데이터베이스: 기록, 등록된 파일, 연결된 데이터베이스, 설정 |
| `src/s3.rs` | SigV4 서명과 S3 목록 조회 |
| `src/i18n.rs` | 문자열 테이블과 언어 선택 |
| `src/state.rs` | 뷰들이 공유하는 애플리케이션 상태 |
| `src/ui/` | 편집기, 결과 그리드, 차트와 지도(OpenStreetMap 타일 포함), 사이드바, 대화 상자, 제목 표시줄과 상태 표시줄, 업데이트 확인 |
| `src/windows.rs` | Windows 시작: CLI 명령은 호출자의 콘솔을 쓰고, GUI 실행은 콘솔을 열지 않음 |
| `quicklook/` | macOS Quick Look 미리보기: Swift 확장 기능이 링크하는 Rust 라이브러리, `scripts/build-quicklook.sh`가 빌드 |
| `src/assets.rs` | 컴포넌트 라이브러리 기본값 외에 내장된 아이콘 |
| `src/perf_probe.rs` | 테스트 전용 성능 프로브 하네스: 데이터 크기에 따라 커지는 경로의 실시간, 할당 횟수, 바이트 수 |
| `assets/` | 아이콘(`.icns`, Windows `.ico`와 리소스 스크립트), Finder가 DuckLocal로 여는 문서 타입을 담은 `Info.plist`, README와 문서에서 쓰는 다이어그램 |
| `scripts/` | `bundle.sh`, `build-quicklook.sh`, `package-macos.sh`, `check-deps.sh`, `check-windows.py`, `make-icons.py`, 권한 파일 |

## 테스트 참고 사항

테스트 스위트는 `cargo test --workspace`입니다. 그냥 `cargo test`는 앱만 다루고 `quicklook/` 크레이트는 포함하지 않습니다. 쿼리 실행 테스트는 인메모리 연결을 통해 DuckDB를 실행합니다. 내보내기 테스트는 CSV와 Parquet를 모두 다루며, 후자는 쓴 파일을 `read_parquet`로 다시 읽어 확인합니다.
