콘텐츠로 이동

개발 ​

빌드와 실행 ​

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_KEYApp 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.ymlmain으로의 푸시, 모든 풀 리퀘스트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.ymlv*와 일치하는 태그, 또는 버전을 지정한 수동 실행빌드 세 개: 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.gzUbuntu 22.04에서 빌드해 대부분의 배포판에 맞는 충분히 오래된 glibc를 쓰며, gpui-kit 자체 CI가 설치하는 시스템 라이브러리를 포함
Windows x86_64ducklocal.exe의 .zipCI에서 테스트. 코드 서명 없음: 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 권장)과 사이트 저장소 클론이 필요합니다. 그다음 다음을 실행하세요.

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.rsDuckDB 연결, 파일 연결, 서버 정보
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.rsducklocal schema: 쿼리할 관계와 열. 프롬프트에 맞춘 크기
src/profile.rsducklocal schema --stats 뒤의 열 통계
src/remote.rsducklocal open: 실행 중인 창과의 루프백 채널, 양방향
src/schema.rs사이드바를 위한 카탈로그 내부 조회
src/spec/.dash 대시보드: 파서, 검증, 소스, 필터, 검토 주석(ducklocal comments), ducklocal lsp, 그리고 plot이 있는 대시보드 탭
src/excel.rsExcel과 ODS 워크북. 시트마다 테이블 하나로 불러오기
src/setup.rs명령줄 및 AI…: ducklocal을 PATH에 넣고 에이전트 스킬 설치
src/recents.rs사이드바에 나열되는 최근에 연 대시보드
src/history.rs앱 자체의 데이터베이스: 기록, 등록된 파일, 연결된 데이터베이스, 설정
src/s3.rsSigV4 서명과 S3 목록 조회
src/i18n.rs문자열 테이블과 언어 선택
src/state.rs뷰들이 공유하는 애플리케이션 상태
src/ui/편집기, 결과 그리드, 차트와 지도(OpenStreetMap 타일 포함), 사이드바, 대화 상자, 제목 표시줄과 상태 표시줄, 업데이트 확인
src/windows.rsWindows 시작: 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로 다시 읽어 확인합니다.

Apache-2.0 라이선스로 공개되었습니다.