개발
빌드와 실행
cargo run # empty in-memory workspace
cargo run -- ./data/logs/ # open something straight away
cargo test --workspace # run the test suite, Quick Look engine includedDuckDB는 벤더링된 소스 코드에서 직접 컴파일되므로 첫 빌드는 눈에 띄게 오래 걸리고 몇 기가바이트의 디스크 공간이 필요합니다. 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 불일치 오류로 실패합니다.
./scripts/check-deps.sh이 스크립트는 Cargo가 하지 않는 검사를 합니다. 그 저장소에 대한 모든 의존성이 하나의 리비전을 쓰는지, Cargo.lock이 그것과 일치하는지, 같은 크레이트가 빌드에 두 번(한 번은 저장소에서, 한 번은 crates.io에서) 들어가지 않는지입니다. 매니페스트 두 개만 읽고 그 밖에는 아무것도 하지 않으므로 오프라인에서 즉시 끝납니다. CI는 테스트 전에 이것을 실행합니다. 더 새로운 툴킷으로 옮기려면 Cargo.toml의 모든 rev를 함께 바꾸고, cargo update를 실행한 뒤 스크립트를 실행하세요.
git 리비전에 고정한 것은 DuckLocal 크레이트를 crates.io에 게시할 수 없는 이유이기도 합니다. crates.io는 git 의존성을 거부합니다. 배포는 아래의 릴리스 패키지로 합니다.
macOS 앱 번들 만들기
./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(미리 볼 콘텐츠 타입), 샌드박스 권한 파일이 있습니다.
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는 앱을 한 번 실행하거나 등록한 뒤에 확장 기능을 찾습니다.
패키징, 서명, 공증
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를 설정 |
스크립트는 다음 단계를 수행합니다.
- 번들을 빌드하며, 버전은 인자에서 찍습니다.
build-quicklook.sh로 Quick Look 확장 기능을 빌드하고, Developer ID와 확장 기능 자체의 샌드박스 권한 파일로 서명합니다. 절대scripts/entitlements.plist가 아닙니다. 앱 확장 기능은 샌드박스여야 하고 앱은 그렇지 않기 때문입니다.- 안쪽부터 바깥쪽으로,
--deep없이, 내부 실행 파일과 그다음 앱을--options runtime --timestamp와scripts/entitlements.plist로 서명하고, 결과를codesign --verify --deep --strict로 검증합니다. /Applications심볼릭 링크가 있는 UDZO dmg를 만듭니다.- dmg 자체에 서명합니다.
notarytool submit --wait --timeout 300m로 제출합니다.- 티켓을 스테이플합니다.
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에 있으며, Cloudflare Workers가 정적 자산으로 서비스합니다.
| 주소 | 내용 | 소스 |
|---|---|---|
| ducklocal.app | 제품 페이지 | home/, 정적 HTML과 CSS |
| ducklocal.app/docs | 이 가이드들, 영어와 중국어 | docs/, VitePress 사이트 |
가이드의 내용을 바꾸는 앱 변경은 두 저장소 모두에 풀 리퀘스트가 필요합니다. 가이드를 로컬에서 작업하려면 Node.js 22 이상(24 LTS 권장)과 사이트 저장소 클론이 필요합니다. 그다음 다음을 실행하세요.
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로 다시 읽어 확인합니다.
