Zum Inhalt springen

Getting Started

Dieser Inhalt ist noch nicht in deiner Sprache verfügbar.

This chapter gets a new contributor from a fresh clone to a running development build.

ToolWhyNotes
Rust (stable)Backend, all workspace cratesInstall via rustup. The pinned toolchain is set in the workspace Cargo.toml (rust-version).
Node.js (LTS) + npmFrontend (Vite, React, TypeScript)Any current LTS works.
Tauri CLIBuild/run the desktop appcargo install tauri-cli (or use npm run tauri).
System WebViewTauri’s rendererWebView2 on Windows, WebKitGTK on Linux, WKWebView on macOS. See the Tauri prerequisites.
Terminal window
git clone https://github.com/Timtam/aperio
cd aperio
# Frontend dependencies
npm install
# Rust dependencies are fetched on first build.
Terminal window
# Starts Vite + the Tauri shell with hot-reload.
npm run tauri dev
# (equivalent to `cargo tauri dev`)

The first build compiles the whole Rust workspace and can take a while; subsequent builds are incremental.

Settings, Feedback sends through Static Forms with a key the build carries (APERIO_STATICFORMS_API_KEY, DESIGN.md §17.6). A local build has none, so the form shows a note instead. To try it, put the key into oauth-clients.local.env beside the workspace root, the file the built-in OAuth clients come from; crates/builtin-oauth/README.md describes it. CI reads the key from the repository secret of the same name.

Notifications on Windows in a development build

Section titled “Notifications on Windows in a development build”

Windows shows a notification only when a Start menu shortcut carries the notification’s app id; the portable app offers that shortcut under Settings, General, Windows notifications (DESIGN.md §14.3, §17.5).

A development build needs none. When the exe lies in a cargo target\debug or target\release folder, tauri-plugin-notification sends its notifications under PowerShell’s app id, so they appear as Windows PowerShell without any shortcut. Aperio follows the same rule (platform::toasts_use_powershell_id, a port of the plugin’s, case-sensitive like it): the settings section says it is a development build and offers no buttons, the hint never opens, and the repair at start changes nothing.

A build in any other CARGO_TARGET_DIR, or a cross-compiled target\<triple>\release, counts as a real copy to the plugin. Its notifications go out as com.aperio.app and need the shortcut, and at start it points your real Start menu entry at itself, because the entry then points at another copy. Start your everyday copy again, or set the entry up from it, to point it back.

Frontend (package.json scripts):

Terminal window
npm run dev # Vite dev server only (no Tauri shell)
npx tsc --noEmit # TypeScript type-check
npm run lint # ESLint (.ts/.tsx)
npm run test # Vitest (unit tests)
npm run build # tsc --noEmit && vite build (what CI runs)

Backend / workspace:

Terminal window
cargo test --workspace
cargo clippy --workspace --all-targets -- -D warnings # exactly what CI runs
cargo fmt --all -- --check # CI's first gate
# After changing a type in cal-core / plugin-core / host-core: regenerate the
# TypeScript declarations the frontends parse. CI checks they are current.
cargo xtask ts-types
cargo xtask ts-types --check # what CI runs
# After a chrono-tz update, or a new CLDR windowsZones file in
# crates/cal-core/cldr/: regenerate the zone tables, in this order.
# CI checks both are current.
cargo xtask tz-list
cargo xtask windows-zones
cargo xtask tz-list --check && cargo xtask windows-zones --check # what CI runs

Match CI locally. CI runs clippy --workspace --all-targets -D warnings, which lints test code too and fails on any warning. A plain cargo clippy skips test targets and can pass while CI fails. Always run the full command above (and cargo fmt --all -- --check) before pushing.

Pick the layer that matches your interest:

You want to work on…Start in…
Domain types & traits shared by everythingcrates/cal-core
The host: Tauri commands, DB, sync, plugin hostsrc-tauri/src
The UIsrc/ (React/TS)
A specific provider (Google, iCloud, …)crates/adapter-* — see Adapters
iCalendar text ↔ events (CalDAV, feeds, file import, Exchange’s imported invitations)crates/ical-mapping
The sync engine (event log, CRDT-ish merge)crates/sync-core, src-tauri/src/event_log, src-tauri/src/sync
Writing a new provider as a pluginthe Plugin Developer docs

The Architecture chapter explains how these pieces talk to each other.