diff --git a/docs/.translation-cache/de.json b/docs/.translation-cache/de.json index 2dceb54fabb..fce2217aef3 100644 --- a/docs/.translation-cache/de.json +++ b/docs/.translation-cache/de.json @@ -1,22 +1,430 @@ { "index.mdx": { "hash": "8db97751a16d", - "translated_at": "2026-05-04T00:19:57Z" + "translated_at": "2026-05-05T15:50:50Z" }, "quick-start/why-wails.mdx": { "hash": "053b3578f336", - "translated_at": "2026-05-04T00:20:34Z" + "translated_at": "2026-05-05T15:52:56Z" }, "quick-start/next-steps.mdx": { "hash": "9b4cb8954865", - "translated_at": "2026-05-04T00:20:45Z" + "translated_at": "2026-05-05T15:53:55Z" }, "status.mdx": { "hash": "916ecd7da4d4", - "translated_at": "2026-05-04T00:20:54Z" + "translated_at": "2026-05-05T15:56:24Z" }, "getting-started/installation.mdx": { "hash": "8d33a6a61b02", - "translated_at": "2026-05-04T00:21:22Z" + "translated_at": "2026-05-05T15:57:16Z" + }, + "feedback.mdx": { + "hash": "a66bb5c84083", + "translated_at": "2026-05-06T13:42:39Z" + }, + "credits.mdx": { + "hash": "23aa065f90ef", + "translated_at": "2026-05-06T13:42:58Z" + }, + "community/links.md": { + "hash": "29ee416737c0", + "translated_at": "2026-05-06T13:43:05Z" + }, + "community/templates.md": { + "hash": "ca58feff1eac", + "translated_at": "2026-05-06T13:43:50Z" + }, + "faq.mdx": { + "hash": "eaa8fbfa4acf", + "translated_at": "2026-05-06T13:44:29Z" + }, + "quick-start/first-app.mdx": { + "hash": "c93bc077121b", + "translated_at": "2026-05-06T15:28:54Z" + }, + "getting-started/your-first-app.mdx": { + "hash": "396abb7e4fac", + "translated_at": "2026-05-06T15:30:00Z" + }, + "quick-start/installation.mdx": { + "hash": "87359ef751c8", + "translated_at": "2026-05-06T15:31:41Z" + }, + "concepts/architecture.mdx": { + "hash": "25b91fd732e4", + "translated_at": "2026-05-06T15:33:59Z" + }, + "concepts/bridge.mdx": { + "hash": "a60fbffa68bd", + "translated_at": "2026-05-06T15:35:59Z" + }, + "concepts/lifecycle.mdx": { + "hash": "b6f00029b744", + "translated_at": "2026-05-06T15:38:39Z" + }, + "concepts/manager-api.mdx": { + "hash": "e341d18b7b82", + "translated_at": "2026-05-06T15:39:24Z" + }, + "concepts/build-system.mdx": { + "hash": "fecbef0d115c", + "translated_at": "2026-05-06T15:41:25Z" + }, + "contributing.mdx": { + "hash": "306f4c3d7ea3", + "translated_at": "2026-05-06T15:42:04Z" + }, + "contributing/architecture/bindings.mdx": { + "hash": "1a645275cef3", + "translated_at": "2026-05-06T15:42:50Z" + }, + "contributing/architecture.mdx": { + "hash": "0da96d95fc40", + "translated_at": "2026-05-07T12:29:09Z" + }, + "contributing/asset-server.mdx": { + "hash": "bb202d50ab3d", + "translated_at": "2026-05-07T12:30:04Z" + }, + "contributing/binding-system.mdx": { + "hash": "15a1847702e6", + "translated_at": "2026-05-07T12:30:57Z" + }, + "contributing/build-packaging.mdx": { + "hash": "38819d5bdc3c", + "translated_at": "2026-05-07T12:31:53Z" + }, + "contributing/codebase-layout.mdx": { + "hash": "7f458a077ad7", + "translated_at": "2026-05-07T12:32:50Z" + }, + "contributing/extending-wails.mdx": { + "hash": "f3b3f52588fc", + "translated_at": "2026-05-07T12:33:38Z" + }, + "contributing/getting-started.mdx": { + "hash": "b440f9d48686", + "translated_at": "2026-05-07T12:34:57Z" + }, + "contributing/index.mdx": { + "hash": "6ec1a3542787", + "translated_at": "2026-05-07T12:35:24Z" + }, + "contributing/runtime-internals.mdx": { + "hash": "76e0f9076c9f", + "translated_at": "2026-05-07T12:36:40Z" + }, + "contributing/setup.mdx": { + "hash": "fa6ba1d71330", + "translated_at": "2026-05-07T12:37:23Z" + }, + "contributing/standards.mdx": { + "hash": "dff5cfcb8913", + "translated_at": "2026-05-07T12:38:31Z" + }, + "contributing/template-system.mdx": { + "hash": "694bc43c635b", + "translated_at": "2026-05-07T12:39:21Z" + }, + "contributing/testing-ci.mdx": { + "hash": "dd3e51012196", + "translated_at": "2026-05-07T12:40:08Z" + }, + "features/bindings/advanced.mdx": { + "hash": "dbe24ee2af58", + "translated_at": "2026-05-07T12:41:10Z" + }, + "features/bindings/best-practices.mdx": { + "hash": "24dae313b7f3", + "translated_at": "2026-05-07T12:43:08Z" + }, + "features/bindings/enums.mdx": { + "hash": "190ad53a8c23", + "translated_at": "2026-05-07T12:44:41Z" + }, + "features/bindings/methods.mdx": { + "hash": "81d390a468d6", + "translated_at": "2026-05-07T12:46:27Z" + }, + "features/bindings/models.mdx": { + "hash": "9f9ef8652dfb", + "translated_at": "2026-05-07T12:48:16Z" + }, + "features/bindings/services.mdx": { + "hash": "ce894343645a", + "translated_at": "2026-05-07T12:50:27Z" + }, + "features/browser/integration.mdx": { + "hash": "fdfdb4b62817", + "translated_at": "2026-05-07T12:52:03Z" + }, + "features/clipboard/basics.mdx": { + "hash": "4518bfb618be", + "translated_at": "2026-05-07T12:53:21Z" + }, + "features/dialogs/custom.mdx": { + "hash": "3c4459e7f9be", + "translated_at": "2026-05-07T12:55:03Z" + }, + "features/dialogs/file.mdx": { + "hash": "56f503b264ff", + "translated_at": "2026-05-07T12:56:39Z" + }, + "features/dialogs/message.mdx": { + "hash": "a0dbc0aa205c", + "translated_at": "2026-05-07T12:58:09Z" + }, + "features/dialogs/overview.mdx": { + "hash": "a53f2f2dbf57", + "translated_at": "2026-05-07T12:59:36Z" + }, + "features/drag-and-drop/files.mdx": { + "hash": "93cde3617c0a", + "translated_at": "2026-05-07T13:00:20Z" + }, + "features/drag-and-drop/html.mdx": { + "hash": "29d1b815879f", + "translated_at": "2026-05-07T13:01:07Z" + }, + "features/environment/info.mdx": { + "hash": "879b5e369c35", + "translated_at": "2026-05-07T13:03:09Z" + }, + "features/events/system.mdx": { + "hash": "99933796a4cd", + "translated_at": "2026-05-07T13:04:47Z" + }, + "features/keyboard/shortcuts.mdx": { + "hash": "0707801c419f", + "translated_at": "2026-05-07T13:06:18Z" + }, + "features/menus/application.mdx": { + "hash": "f3012e184058", + "translated_at": "2026-05-07T13:08:31Z" + }, + "features/menus/context.mdx": { + "hash": "0da9502ee8f9", + "translated_at": "2026-05-07T13:10:53Z" + }, + "features/menus/reference.mdx": { + "hash": "50c7083c6804", + "translated_at": "2026-05-07T13:12:30Z" + }, + "features/menus/systray.mdx": { + "hash": "35456a6a7c94", + "translated_at": "2026-05-07T13:14:44Z" + }, + "features/notifications/overview.mdx": { + "hash": "fd054a949c5c", + "translated_at": "2026-05-07T13:15:51Z" + }, + "features/platform/dock.mdx": { + "hash": "5508d0260390", + "translated_at": "2026-05-07T13:16:44Z" + }, + "features/screens/info.mdx": { + "hash": "7c75b63845ac", + "translated_at": "2026-05-07T13:18:09Z" + }, + "features/windows/basics.mdx": { + "hash": "22ab3ac2c722", + "translated_at": "2026-05-07T13:19:50Z" + }, + "features/windows/events.mdx": { + "hash": "68ae278863a2", + "translated_at": "2026-05-07T13:21:37Z" + }, + "features/windows/frameless.mdx": { + "hash": "8250472da67d", + "translated_at": "2026-05-07T13:24:05Z" + }, + "features/windows/multiple.mdx": { + "hash": "67f02d26da23", + "translated_at": "2026-05-07T13:26:18Z" + }, + "features/windows/options.mdx": { + "hash": "a56b6c508b23", + "translated_at": "2026-05-07T13:29:35Z" + }, + "guides/architecture.mdx": { + "hash": "656401718a17", + "translated_at": "2026-05-07T13:29:59Z" + }, + "guides/build/building.mdx": { + "hash": "b307db98ff3b", + "translated_at": "2026-05-07T13:30:21Z" + }, + "guides/build/cross-platform.mdx": { + "hash": "fe856503784b", + "translated_at": "2026-05-07T13:31:33Z" + }, + "guides/build/customization.mdx": { + "hash": "5fdb39dad876", + "translated_at": "2026-05-07T13:32:44Z" + }, + "guides/build/linux.mdx": { + "hash": "afa4feb031ad", + "translated_at": "2026-05-07T13:33:33Z" + }, + "guides/build/macos.mdx": { + "hash": "453cb1df5afe", + "translated_at": "2026-05-07T13:34:02Z" + }, + "guides/build/signing.mdx": { + "hash": "adcc7414ca8e", + "translated_at": "2026-05-07T13:37:11Z" + }, + "guides/build/windows.mdx": { + "hash": "34fb150bd1d1", + "translated_at": "2026-05-07T13:37:31Z" + }, + "guides/cli.mdx": { + "hash": "734e59534ff1", + "translated_at": "2026-05-07T13:40:05Z" + }, + "guides/custom-templates.mdx": { + "hash": "fd0479b54490", + "translated_at": "2026-05-07T13:41:27Z" + }, + "guides/custom-transport.mdx": { + "hash": "1f60cc55f45f", + "translated_at": "2026-05-07T13:42:05Z" + }, + "guides/customising-windows.mdx": { + "hash": "b2c0f84a76db", + "translated_at": "2026-05-07T13:42:31Z" + }, + "guides/distribution/auto-updates.mdx": { + "hash": "e511338ccc89", + "translated_at": "2026-05-07T13:44:27Z" + }, + "guides/distribution/custom-protocols.mdx": { + "hash": "d7e39edb8d62", + "translated_at": "2026-05-07T13:46:49Z" + }, + "guides/e2e-testing.mdx": { + "hash": "409942e28dff", + "translated_at": "2026-05-07T13:47:13Z" + }, + "guides/events-reference.mdx": { + "hash": "e1c103b7e422", + "translated_at": "2026-05-07T13:49:19Z" + }, + "guides/file-associations.mdx": { + "hash": "5756c5fd62ec", + "translated_at": "2026-05-07T13:49:58Z" + }, + "guides/gin-routing.mdx": { + "hash": "4b51d1052334", + "translated_at": "2026-05-07T13:50:52Z" + }, + "guides/gin-services.mdx": { + "hash": "4336b2c6dd73", + "translated_at": "2026-05-07T13:53:02Z" + }, + "guides/installers.mdx": { + "hash": "eb492627c525", + "translated_at": "2026-05-07T13:53:27Z" + }, + "guides/menus.mdx": { + "hash": "c43696cd9e44", + "translated_at": "2026-05-07T13:55:37Z" + }, + "guides/panic-handling.mdx": { + "hash": "cd4e3d40f28d", + "translated_at": "2026-05-07T13:56:10Z" + }, + "guides/performance.mdx": { + "hash": "2cd3efcd296b", + "translated_at": "2026-05-07T13:56:54Z" + }, + "guides/raw-messages.mdx": { + "hash": "974513802fdc", + "translated_at": "2026-05-07T13:58:16Z" + }, + "guides/routing.mdx": { + "hash": "1a9624a10457", + "translated_at": "2026-05-07T13:58:40Z" + }, + "guides/security.mdx": { + "hash": "4b98f155146f", + "translated_at": "2026-05-07T13:59:18Z" + }, + "guides/server-build.mdx": { + "hash": "14b9185722c8", + "translated_at": "2026-05-07T14:00:34Z" + }, + "guides/single-instance.mdx": { + "hash": "c9d6b1edf953", + "translated_at": "2026-05-07T14:01:13Z" + }, + "guides/testing.mdx": { + "hash": "8073196a1496", + "translated_at": "2026-05-07T14:01:40Z" + }, + "guides/windows-uac.mdx": { + "hash": "91140294509d", + "translated_at": "2026-05-07T14:02:15Z" + }, + "migration/v2-to-v3.mdx": { + "hash": "ba7228eb5374", + "translated_at": "2026-05-07T14:04:32Z" + }, + "reference/application.mdx": { + "hash": "6b97eb24f8db", + "translated_at": "2026-05-07T14:05:46Z" + }, + "reference/cli.mdx": { + "hash": "da0cd943a3de", + "translated_at": "2026-05-07T14:05:53Z" + }, + "reference/dialogs.mdx": { + "hash": "4a2534a0eb49", + "translated_at": "2026-05-07T14:08:11Z" + }, + "reference/events.mdx": { + "hash": "34ff503157f7", + "translated_at": "2026-05-07T14:10:57Z" + }, + "reference/frontend-runtime.mdx": { + "hash": "1040ebd9dffd", + "translated_at": "2026-05-07T14:13:23Z" + }, + "reference/menu.mdx": { + "hash": "1ac85e9b0a6d", + "translated_at": "2026-05-07T14:15:24Z" + }, + "reference/overview.mdx": { + "hash": "78b1b9e99288", + "translated_at": "2026-05-07T14:16:16Z" + }, + "reference/updater.mdx": { + "hash": "841cdfe235d9", + "translated_at": "2026-05-07T14:17:40Z" + }, + "reference/window.mdx": { + "hash": "c23046463063", + "translated_at": "2026-05-07T14:19:32Z" + }, + "troubleshooting/mac-syso.mdx": { + "hash": "7aa5d722de2d", + "translated_at": "2026-05-07T14:19:41Z" + }, + "tutorials/01-creating-a-service.mdx": { + "hash": "759d28b3e03b", + "translated_at": "2026-05-07T14:22:36Z" + }, + "tutorials/02-todo-vanilla.mdx": { + "hash": "a50167163c77", + "translated_at": "2026-05-07T14:25:23Z" + }, + "tutorials/03-notes-vanilla.mdx": { + "hash": "7da37d8fbf9c", + "translated_at": "2026-05-07T14:27:46Z" + }, + "tutorials/overview.mdx": { + "hash": "24d96283170f", + "translated_at": "2026-05-07T14:28:09Z" } } \ No newline at end of file diff --git a/docs/src/content/docs/de/contributing/architecture.mdx b/docs/src/content/docs/de/contributing/architecture.mdx new file mode 100644 index 00000000000..a833c24bd44 --- /dev/null +++ b/docs/src/content/docs/de/contributing/architecture.mdx @@ -0,0 +1,99 @@ +--- +title: Wails v3-Architektur +description: Detaillierte Diagramme und Erklärungen zu allen Komponenten in Wails v3 +sidebar: + order: 1 +--- + +Wails v3 ist ein **Full-Stack-Desktop-Framework**, das aus einer Go-Laufzeitumgebung, +einer JavaScript-Schnittstelle, einer aufgabenorientierten Toolchain und einer Sammlung von Vorlagen +besteht, mit denen Sie native Anwendungen, die von modernen Webtechnologien angetrieben werden, +veröffentlichen können. + +Diese Seite zeigt das *Gesamtbild* in vier Diagrammen: + +1. **Gesamtarchitektur** – wie jedes Subsystem verbunden ist +2. **Laufzeitfluss** – was passiert, wenn JS Go aufruft und umgekehrt +3. **Entwicklung vs. Produktion** – zwei Modi des Asset-Servers +4. **Plattform-Implementierungen** – wo der OS-spezifische Code lebt + +--- + +## 1 · Gesamtarchitektur + +**Wails v3 – High-Level-Stack** + +{/* +TODO: Fix D2 diagram generation (triple quotes for multi-line strings) or embed as image. +The previous D2 code block was causing MDX parsing errors in the build pipeline. +*/} + +**[High-Level-Stack-Diagramm-Platzhalter]** + +--- + +## 2 · Laufzeit-Aufruffluss + +**Laufzeit – JavaScript ⇄ Go-Aufrufpfad** + +{/* +TODO: Fix D2 diagram generation (triple quotes for multi-line strings) or embed as image. +The previous D2 code block was causing MDX parsing errors in the build pipeline. +*/} + +**[Diagramm-Platzhalter für den Laufzeit-Aufruffluss]** + +Wichtige Punkte: + +* **Kein HTTP / IPC** – die Brücke verwendet den speicherinternen Kanal des nativen WebView +* **Methoden-IDs** – deterministisches FNV-Hashing ermöglicht O(1)-Suche in Go +* **Promises** – Fehler werden als Rejections mit Stack und Code weitergegeben + +--- + +## 3 · Asset-Fluss: Entwicklung vs. Produktion + +**Dev ↔ Prod Asset-Server** + +{/* +TODO: Fix D2 diagram generation (triple quotes for multi-line strings) or embed as image. +The previous D2 code block was causing MDX parsing errors in the build pipeline. +*/} + +**[Diagramm-Platzhalter für den Asset-Fluss]** + +* Im **Dev**-Modus proxyt der Server unbekannte Pfade an den Live-Reload-Server + des Frameworks und stellt statische Assets von der Festplatte bereit. +* Im **Prod**-Modus wird dieselbe API durch `go:embed` unterstützt, wodurch ein + binäres Programm ohne Abhängigkeiten erzeugt wird. + +--- + +## 4 · Plattform-spezifische Laufzeittrennung + +**Pro-Betriebssystem-Laufzeitdateien** + +{/* +TODO: Fix D2 diagram generation (triple quotes for multi-line strings) or embed as image. +The previous D2 code block was causing MDX parsing errors in the build pipeline. +*/} + +**[Diagramm-Platzhalter für die Plattform-Trennung]** + +Jede Funktion folgt diesem Muster: + +1. **Gemeinsame Schnittstelle** in `pkg/application` +2. **Eingabepunkt des Nachrichtenprozessors** in `pkg/application/messageprocessor_*.go` +3. **Implementierung** pro OS unter `internal/runtime/*.go`, geschützt durch Build-Tags + +Fehlende Funktionen auf einem OS sollten `ErrCapability` zurückgeben und die +Verfügbarkeit über `internal/capabilities` registrieren. + +--- + +## Zusammenfassung + +Diese Diagramme skizzieren, **wo der Code lebt**, **wie Daten bewegt werden** und +**welche Schichten für welche Verantwortlichkeiten zuständig sind**. +Halten Sie sie bereit, während Sie die detaillierten Seiten erkunden, die folgen – sie sind Ihr +Kompass zum Wails v3-Quellcode-Verzeichnis. \ No newline at end of file diff --git a/docs/src/content/docs/de/contributing/asset-server.mdx b/docs/src/content/docs/de/contributing/asset-server.mdx new file mode 100644 index 00000000000..9b5a00614a4 --- /dev/null +++ b/docs/src/content/docs/de/contributing/asset-server.mdx @@ -0,0 +1,200 @@ +--- +title: Asset-Server +description: Wie Wails v3 Ihre Web-Assets in Entwicklung und Produktion bereitstellt und einbettet +sidebar: + order: 4 +--- + +## Übersicht + +Jede Wails-Anwendung liefert einen **einzelnen nativen ausführbaren Datei**, der Folgendes kombiniert: + +1. Ihr *Go*-Backend +2. Ein *Web*-Frontend (HTML + JS + CSS) + +Der **Asset-Server** ist der Klebstoff, der dies ermöglicht. +Er verfügt über **zwei Betriebsmodi**, die zur Kompilierzeit über Go-Build-Tags ausgewählt werden: + +| Modus | Tag | Zweck | +|------|-----|---------| +| **Entwicklung** | `//go:build dev` | Schnelle Iteration mit Hot-Reload | +| **Produktion** | `//go:build !dev` | Abhängigkeitsfreie, eingebettete Assets | + +Die Implementierung befindet sich in +`v3/internal/assetserver/` mit klarer Dateiaufteilung: + +``` +assetserver_dev.go # ⬅️ Laufzeit-Dev-Server +assetserver_production.go # ⬅️ eingebetteter Server +assetserver_darwin.go # OS-spezifische Hilfsprogramme (gleicher Code für Linux/Windows) +asset_fileserver.go # Gemeinsame Logik für statische Dateien +content_type_sniffer.go | MIME-Typ-Erkennung +ringqueue.go # Winzige LRU für MIME-Cache +``` + +--- + +## Entwicklungsmodus + +### Lebenszyklus + +1. `wails3 dev` startet und **startet Ihren Frontend-Dev-Server** + (Vite, SvelteKit, React-SWC …), indem es die in + `build/Taskfile.yml` definierte Aufgabe ausführt (normalerweise `npm run dev`). +2. Wails startet den **Dev Asset Server**, der auf `localhost:` lauscht, und + weist die Go-Laufzeit an, `http://:` als Fenster-URL zu laden. +3. Eingehende Anfragen werden von `assetserver_dev.go` verarbeitet: + + ``` + ┌─────────┐ /runtime/... ┌─────────────┐ + │ Browser │ ── native Brücke ───▶ │ Laufzeit │ + ├─────────┤ └─────────────┘ + │ JS │ / (index.html) proxy / -> Vite + └─────────┘ ◀─────────────┐ + AssetServer │ + ▼ + ┌────────────┐ + │ Vite Dev │ + │ Server │ + └────────────┘ + ``` + +4. Statische Dateien (`/assets/logo.svg`) werden **direkt von der Festplatte** über + `asset_fileserver.go` bereitgestellt (für Geschwindigkeit), während alles Unbekannte **an den** + Framework-Dev-Server **weitergeleitet** wird, was Ihnen *sofortiges* Hot-Module-Replacement ermöglicht. + +### Funktionen + +* **Live Reload** – Vite/Snowpack/… injiziert ein HMR-WebSocket; Wails muss es nur + weiterleiten. +* **Source-Map-Unterstützung** – Da die Assets nicht gebündelt werden, können Ihre Browser-DevTools + Fehler auf den ursprünglichen Quellcode zurückführen. +* **Kein Go-Neukompilieren** – Nur das Frontend wird neu erstellt; Go-Code bleibt aktiv, bis + Sie `.go`-Dateien ändern. + +### Wechseln der Frameworks + +Der Dev-Proxy ist **framework-agnostisch**: + +* Die Root-`Taskfile.yml`-Aufgabendatei injiziert zwei Umgebungsvariablen: + `APP_NAME` & `WAILS_VITE_PORT`. +* Taskfiles für jede Vorlage geben diese Variablen aus, bevor sie ihre Dev-Server starten. +* `assetserver_dev.go` leitet einfach an dieses Ziel weiter. + +Eine neue Vorlage hinzufügen → deren Dev-Aufgabe definieren → Asset Server funktioniert einfach. + +--- + +## Produktionsmodus + +Wenn Sie `wails3 build` ausführen, durchläuft die Pipeline: + +1. Führt den Frontend-**Produktionsaufbau** (`npm run build`) aus, der + `/frontend/dist/**` erzeugt. +2. **Bettet** diesen Ordner zur Kompilierzeit in das `go:embed`-Dateisystem ein (siehe + `bundled_assetserver.go` generierte Datei). +3. Kompiliert die Go-Binärdatei mit `-tags production` (implizit). + +### Anfrageverarbeitung + +```go +func (h *Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) { + // 1. Versuche eingebettete statische Assets (exakter Pfad) + // 2. Fallback auf index.html für SPA-Routing + // 3. MIME-Typ ermitteln, wenn Erweiterung unbekannt + // 4. Starke Cache-Header setzen +} +``` + +* **MIME-Erkennung** – Wenn das Build-Tool erweiterungslose Dateien erzeugt hat (z.B. + `/assets/manifest`), untersucht `content_type_sniffer.go` die ersten 512 Bytes und + zwischenspeichert das Ergebnis in einer winzigen sperrfreien LRU. +* **Ring-Queue-Caching** – Häufig zugriffene Assets (Logo, CSS) werden im Speicher + für die Lebensdauer der App gehalten, wodurch Nachschlagevorgänge auf der Festplatte oder im eingebetteten Dateisystem + entfallen. +* **Sicherheits-Header** – Verhindert `file://`-Navigation, aktiviert `nosniff`. + +Da alles eingebettet ist, hat die ausgelieferte Binärdatei **keine externen +Abhängigkeiten** (auch nicht unter Windows). + +--- + +## Brücke zwischen Dev ↔ Prod + +Beide Modi stellen die **gleiche öffentliche Schnittstelle** bereit: + +```go +type AssetServer interface { + URL() string // dev: http://localhost:34115, prod: wails://app + Open() error // Starten des Lauschens + Close() // Graceful Shutdown +} +``` + +`pkg/application` verwendet gerne die jeweils kompilierte Implementierung, was bedeutet, +**dass sich Ihr Anwendungscode zwischen `dev` und `build` nicht ändert**. + +--- + +## Integration von Frontend-Frameworks + +### Vorlagen + +Jede offizielle Vorlage (React, Vue, Svelte, Solid…) enthält: + +* `build/Taskfile.yml` +* `frontend/vite.config.ts` (oder Äquivalent) + +Sie exportieren mehrere Aufgaben, darunter: + +| Aufgabe | Zweck | +|------|---------| +| `dev:frontend` | Startet den Framework-Dev-Server auf einem **zufälligen freien Port** und gibt ihn an stdout aus (`PORT=5173`). | +| `build:frontend` | Erzeugt statische Assets in `dist/` + Manifest für Cache-Busting. | + +`internal/commands/dev.go` setzt die Umgebungsvariable `FRONTEND_DEVSERVER_URL` unter Verwendung von `localhost` als `host` und der ausgegebenen Umgebungsvariable `VITE_PORT` als `port` und startet den **Dev Asset Server**. + +Frameworks bleiben vollständig entkoppelt von Go: + +* Keine Notwendigkeit, das Wails JS SDK zur Build-Zeit zu importieren – die Laufzeit injiziert es bei der Fenstererstellung. +* Jedes Framework mit einem HTTP-Dev-Server kann eingebunden werden. + +--- + +## Erweitern / Anpassen + +Benötigen Sie benutzerdefinierte Header, Authentifizierung oder gzip? + +1. Implementieren Sie `type Middleware func(http.Handler) http.Handler` +2. Registrieren Sie es über `internal/assetserver/options.go` +3. Denken Sie für die Produktion daran, denselben Middleware auch in `assetserver_production.go` hinzuzufügen. + +--- + +## Wichtige Quelldateien + +| Datei | Rolle | +|------|------| +| `assetserver_dev.go` | Reverse Proxy + Festplatten-Dateiserver | +| `assetserver_production.go` | Eingebetteter FS-Handler | +| `options.go` | Konfigurationsstruktur, die aus `pkg/options/assetserver`_parsed wird | +| `build_dev.go` / `build_production.go` | Build-Tag-Wrapper, die die korrekte Implementierung auswählen | +| `bundled_assetserver.go` | Generierte Embed-Daten (nur in Produktionsbuilds vorhanden) | + +--- + +## Fallstricke & Debugging + +* **Weißer Bildschirm in Prod** – meist SPA-Routing: Stellen Sie sicher, dass `History API Fallback` + in der Entwicklung aktiviert ist und der `index.html`-Fallback in der Produktion funktioniert. +* **404 in Dev** – nicht übereinstimmender `FRONTEND_DEV_PORT`; starten Sie mit + `WAILSDEV_VERBOSE=1`, um jede weitergeleitete Anfrage auszugeben. +* **Große Assets** – sie werden eingebettet; erwägen Sie + [`assetserver.WithExternalDir("/path")`](https://pkg.go.dev), um von der Festplatte zu laden. + +--- + +Sie wissen nun, wie der Wails **Asset Server** Ihren Web-Code in beiden **Entwicklungs**- und **Produktions**-Modi an das native +Fenster übergibt. +Beherrschen Sie diese Schicht, und Sie können Lade-Probleme debuggen, Middlewares hinzufügen oder sogar +zuverlässig eine völlig andere Frontend-Toolchain austauschen. \ No newline at end of file diff --git a/docs/src/content/docs/de/contributing/binding-system.mdx b/docs/src/content/docs/de/contributing/binding-system.mdx new file mode 100644 index 00000000000..c5049d3453c --- /dev/null +++ b/docs/src/content/docs/de/contributing/binding-system.mdx @@ -0,0 +1,240 @@ +--- +title: Bindungssystem +description: Wie Wails v3 Go und JavaScript ohne Boilerplate-Code gegenseitig aufrufen lässt +sidebar: + order: 5 +--- + +> „Bindings“ sind der **typsichere Vertrag**, der es Ihnen ermöglicht, Folgendes zu schreiben: + +```go +msg, err := chatService.Send("Hello") +``` + +in Go *und* + +```ts +const msg = await window.backend.ChatService.Send("Hello") +``` + +in TypeScript **ohne manuellen Klebe-Code**. +Dieses Dokument erklärt, wie dieser Zauber funktioniert, von der **statischen Analyse** +zur Build-Zeit über die **Code-Generierung** bis hin zur **Laufzeit-Brücke**, die +Bytes über die WebView überträgt. + +--- + +## 1. 30-Sekunden-Übersicht + +| Stufe | Komponente | Ausgabe | +|-------|-----------|--------| +| **Analyse** | `internal/generator/analyse.go` | In-Memory-AST von exportierten Go-Strukturen, Methoden, Parametern, Rückgabetypen | +| **Generierung** | `internal/generator/render/*.tmpl` | • `pkg/application/bindings.go` (Go)
• `frontend/src/wailsjs/**.ts` (TS-Definitionen)
• `runtime/desktop/@wailsio/runtime/internal/bindings.json` | +| **Laufzeit** | `pkg/application/messageprocessor_call.go` + JS-Laufzeit (`invoke.ts`) | JSON-Nachrichten über die WebView-Native-Brücke | + +Der Ablauf wird von der `wails3`-CLI orchestriert: + +``` +wails3 generate ─┬─> generator.Collect() // Go-Pakete parsen + ├─> generator.Analyse() // semantisches Modell aufbauen + └─> generator.Render() // Dateien schreiben + `go fmt` +``` + +--- + +## 2. Statische Analyse + +### Einstiegspunkt + +``` +internal/generator/analyse.go +``` + +`Analyse(cfg generator.Config)`: + +1. Lädt rekursiv die angegebenen Go-Pakete mit `go/packages`. +2. Durchläuft die *Typ*- und *Wert*-Spezifikationen jeder AST-Datei. +3. Filtert **exportierte** Symbole (großgeschrieben) außerhalb von `internal/`-Paketen. +4. Speichert: + * Empfängertyp (`struct`, `interface`) + * Methodenname + * Parameterliste (Name, Typ, Zeiger, variadisch) + * Rückgabe-Tupel (Werte + Vorhandensein von Fehler) +5. Normalisiert Typen auf eine **serialisierbare Menge** + (`int`, `float64`, `string`, `[]byte`, Slices, Maps, Strukturen, Zeiger). + +Nicht unterstützte Typen führen zu einem **Kompilierzeitfehler**, sodass Fehler frühzeitig erkannt werden. + +### Modell + +```go +type Method struct { + ID uint32 // stabiler Hash für Laufzeitsuche + Name string + Params []Param + Results []Result + Receiver *Struct // nil für Paketfunktionen +} +``` + +Ein deterministischer **FNV-1a**-Hash (`internal/hash/fnv.go`) von +`.()` wird zur *Methoden-ID* verwendet, die zur Laufzeit genutzt wird. + +--- + +## 3. Code-Generierung + +### Vorlagen + +`internal/generator/render/` enthält text/template-Dateien: + +| Vorlage | Ziel | +|----------|--------| +| `go_bindings.tmpl` | `pkg/application/bindings.go` | +| `ts_bindings.tmpl` | `frontend/wailsjs/go/models.d.ts` | +| `ts_index.tmpl` | `frontend/wailsjs/index.ts` | + +Fügen Sie hier Vorlagen hinzu oder passen Sie sie an, um die Generierung anzupassen. + +### Go-Ausgabe + +`bindings.go` registriert eine Lookup-Tabelle: + +```go +var bindings = []application.BoundMethod{ + {ID: 0x7A1201D3, Name: "ChatService.Send", Call: chatServiceSend}, +} + +func chatServiceSend(ctx context.Context, in []byte) ([]byte, error) { + var req struct{ Msg string } + if err := json.Unmarshal(in, &req); err != nil { return nil, err } + res, err := chatService.Send(req.Msg) + return json.Marshal(res), err +} +``` + +Wichtige Punkte: + +* **Keine Reflexion** zur Laufzeit → Leistung. +* Marshal/Unmarshal ist **pro Methode** mit generierten Struktur-Wrappern. + +### TypeScript-Ausgabe + +```ts +export namespace backend { + export namespace ChatService { + function Send(msg: string): Promise; + } +} +``` + +* Wird als **ES-Module** ausgegeben, sodass jeder Bundler Tree-Shaking durchführen kann. +* Methoden-IDs werden in einer automatisch generierten `bindings.json` für die JS- + Laufzeit eingebettet. + +--- + +## 4. Laufzeit-Aufrufprotokoll + +### JavaScript-Seite + +```ts +import { System } from "@wailsio/runtime"; + +await System.invoke(0x7a1201d3 /* ChatService.Send */, ["Hello"]); +``` + +Implementierung: `runtime/desktop/@wailsio/runtime/invoke.ts` + +1. Packt `{t:"c", id:, p:[...args]}` in JSON. +2. Ruft `window.external.invoke(payload)` auf (WebView2) oder Äquivalent. +3. Gibt ein `Promise` zurück, das basierend auf der Antwort aufgelöst oder abgelehnt wird. + +### Go-Seite + +1. `messageprocessor_call.go` empfängt das JSON. +2. Sucht `methodID` im `bindings`-Slice. +3. Führt den generierten Stub aus (`chatServiceSend`). +4. Serialisiert `{result, error}` zurück an JS. + +### Fehlerzuordnung + +| Go | JavaScript | +|----|------------| +| `error == nil` | `Promise` wird mit Ergebnis aufgelöst | +| `errors.New(...)` | `Promise` wird abgelehnt mit `{message, stack, code}` | + +Der Zuordnungscode befindet sich in `runtime/desktop/@wailsio/runtime/errors.ts`. + +--- + +## 5. Aufruf von JavaScript aus Go + +*Browser → Go* wurde oben abgedeckt. +*Go → Browser* verwendet **Events** oder **Eval**: + +```go +window.Eval(`alert("Hi")`) +app.Publish("chat:new-message", msg) +``` + +Die Bindungsgenerierung ist einseitig (Go-Methoden). +Für JS-exponierte Funktionen verwenden Sie `runtime.EventsOn` in JS und `application.Publish` +aus Go. + +--- + +## 6. Erweitern & Fehlerbehebung + +### Eigene Serialisierer hinzufügen + +* Implementieren Sie die `generator.TypeConverter`-Schnittstelle. +* Registrieren Sie sie in `generator.Config.Converters`. +* Aktualisieren Sie die JS-Laufzeit-Deserialisierung bei Bedarf. + +### Fehler für nicht unterstützte Typen + +``` +error: field "Client" uses unsupported type: chan struct{} +``` + +→ Wickeln Sie den Kanal in eine Struktur mit einer exponierten API ein oder überdenken Sie das Design. + +### Versionsunterschiede + +Bindings werden bei **jedem** `wails3 dev` / `wails3 build` neu generiert. +Wenn die IDE-Intellisense veraltete Stubs anzeigt, löschen Sie `frontend/wailsjs` und bauen Sie neu. + +### Leistungstipps + +* Bevorzugen Sie **Value**-Empfänger für kleine Strukturen, um Allokationen zu reduzieren. +* Vermeiden Sie große Byte-Slices über die Brücke; verwenden Sie stattdessen `application.FileServer`. +* Bündeln Sie mehrere schnelle Aufrufe in einer Methode, um die Brücken-Latenz zu minimieren. + +--- + +## 7. Wichtige Dateien-Übersicht + +| Anliegen | Datei | +|---------|------| +| Einstiegspunkt der statischen Analyse | `internal/generator/analyse.go` | +| Render-Pipeline | `internal/generator/generate.go` | +| Vorlagen-Assets | `internal/generator/render/*.tmpl` | +| Go-Bindungstabelle | `pkg/application/bindings.go` (generiert) | +| Aufrufprozessor | `pkg/application/messageprocessor_call.go` | +| JS-Laufzeit | `runtime/desktop/@wailsio/runtime/invoke.ts` | +| Fehlerzuordnung | `runtime/desktop/@wailsio/runtime/errors.ts` | + +Halten Sie dieses Spickzettel bereit, wenn Sie einen Brücken-Bug nachverfolgen. + +--- + +## 8. Zusammenfassung + +1. **Generator** scannt Ihren Go-Code → semantisches Modell. +2. **Vorlagen** emitieren **Go-Stubs** + **TypeScript-Definitionen**. +3. **Message Processor** führt Stubs zur Laufzeit aus. +4. **JS-Laufzeit** packt alles in idiomatische Promises. + +Alles ohne Reflexion, ohne IPC-Server und ohne dass Sie auch nur eine Zeile +Boilerplate-Code schreiben müssen. Das ist das Wails v3-Bindungssystem. Los geht's und binden Sie los! \ No newline at end of file diff --git a/docs/src/content/docs/de/contributing/build-packaging.mdx b/docs/src/content/docs/de/contributing/build-packaging.mdx new file mode 100644 index 00000000000..930e82865e0 --- /dev/null +++ b/docs/src/content/docs/de/contributing/build-packaging.mdx @@ -0,0 +1,197 @@ +--- +title: Build- und Packaging-Pipeline +description: Was passiert unter der Haube, wenn Sie `wails3 build` ausführen, wie plattformübergreifende Binärdateien erzeugt werden und wie Installer für jedes Betriebssystem generiert werden. +sidebar: + order: 6 +--- + +`wails3 build` ist ein **einzelner Befehl**, der eine _mehrstufige_ Pipeline antreibt: + +1. **Frontend-Produktionsbuild** (Vite / React / …) +2. **Asset-Einbettung** in Go-Quellcode +3. **Native Kompilierung** für das Ziel-Betriebssystem/die Ziel-Architektur +4. **Nachbearbeitung** (Symbolinjektion, Versionsinformationen, Codesigning) +5. **Packaging** in ein verteilbares Artefakt (AppImage, DMG, MSI, …) + +Dieses Dokument verfolgt jede Stufe, zeigt, wo der Code lebt, und erklärt, wie Sie ihn anpassen oder debuggen können. + +--- + +## 1. Einstiegspunkt: `internal/commands/build-assets.go` + +``` +wails3 build # cmd/wails3/main.go +└─ internal/commands.Build() # build-assets.go +``` + +Hochrangige Aufgaben werden an **Taskfile**-Ziele delegiert, damit dieselbe Logik in CI oder lokal ausgeführt wird. + +| Stufe | Taskfile-Ziel | Go-Implementierung | +|-------|-----------------|-------------------| +| Frontend-Build | `frontend:build` | `internal/commands/task.go` | +| Assets einbetten | `embed:assets` | generierte `bundled_assetserver.go` | +| Go-Compile | `build:go` | `tool_buildinfo.go`, `tool_package.go` | +| Packaging | `package:*` | `internal/packager`, `internal/commands/*` | + +--- + +## 2. Frontend-Produktionsbuild + +1. Die CLI wechselt in `frontend/` und führt die in der Projektdatei `Taskfile.yml` gefundene `build`-Aufgabe aus (standardmäßig `npm run build`). +2. Die Ausgabe wird in `frontend/dist/` geschrieben. +3. Ein **Content-Hash**-Manifest wird erzeugt (`manifest.json`), damit Cache-Busting standardmäßig funktioniert. + +Wenn die Aufgabe fehlschlägt, bricht die Pipeline frühzeitig ab und gibt den Exit-Code Ihres Build-Tools zurück. + +--- + +## 3. Einbetten von Assets + +Implementiert in `internal/assetserver/build_production.go`: + +* Durchläuft `frontend/dist` und generiert eine `go:embed`-Datei + `bundled_assetserver.go` (von git ignoriert). +* Fügt den Build-Tag `production` hinzu. + +Ergebnis: Das finale Binary enthält jedes HTML/JS/CSS-Byte, sodass die ausführbare Datei selbstständig ist. + +--- + +## 4. Native Kompilierung + +### Build-Flags + +| Flag | Zweck | +|------|---------| +| `-tags production` | Wählt prod Asset Server & Runtime-Stubs aus | +| `-ldflags "-s -w"` | Entfernt Symboltabelle & DWARF (kleinere Binaries) | +| `-X internal/buildinfo.BuildTime=$(date)` | Einbetten reproduzierbarer Metadaten | + +`internal/commands/tool_buildinfo.go` sammelt Version, Git-Commit und Build-Zeit und injiziert diese mittels `go build -ldflags`. + +### Cross-Compilation-Matrix + +| OS | Arch | Build-Tag | CGO | Hinweise | +|----|------|-----------|-----|-------| +| Windows | amd64 / arm64 | `windows` | cgo für WebView2 aktiviert | Generiert `.syso` via `internal/commands/syso.go` | +| macOS | amd64 / arm64 | `darwin` | cgo aktiv (Objective-C) | Codesign- & Notarisierungsaufgaben verfügbar | +| Linux | amd64 / arm64 | `linux` | reines Go (webkit-Option) | GTK/WebKitGTK-Header für CGO-Build erforderlich | + +`wails3 build -platform darwin/arm64` überschreibt GOOS/GOARCH. +Wenn CGO auf dem Host benötigt wird, der das Ziel nicht kompilieren kann (z. B. Windows-Build von Linux aus), fällt die CLI auf **Docker**-Images zurück (`ghcr.io/wailsapp/cross-compiler`). + +--- + +## 5. Nachbearbeitung + +### Symbole & Ressourcen + +* **Windows** – `syso.go` fügt Ihr PNG/ICO in eine `.syso`-Datei zusammen, die `go build` automatisch verlinkt. Schreibt auch `manifest.xml`, um High-DPI-Unterstützung zu aktivieren. +* **macOS** – `icons.go` wandelt `icon.png` in `.icns` um und injiziert es in + `MyApp.app/Contents/Resources`. +* **Linux** – `.desktop`-Dateien werden in `/usr/share/applications` von jedem Packager-Backend generiert. + +### Code Signing (Optional) + +* macOS: `codesign` + `xcrun altool --notarize-app` +* Windows: `signtool.exe` +* Linux: Nicht üblich (Repository-GPG wird extern gehandhabt) + +Task-Ziele: `sign:mac`, `sign:windows`. + +--- + +## 6. Packaging-Back-Ends + +### Linux + +| Artefakt | Code-Pfad | Tooling | +|----------|-----------|---------| +| **AppImage** (Standard) | `internal/commands/appimage.go` | `linuxdeploy` + `linuxdeploy-plugin-gtk` | +| **deb / rpm / pacman** | `internal/packager` | `fpm` (via Go aufgerufen) | + +Flags: + +``` +wails3 build -package deb # erzeugt myapp_1.0.0_amd64.deb +wails3 build -package rpm +``` + +### macOS + +* **DMG** – `internal/commands/packager.go` ruft `appdmg` auf, um einen Drag-&-Drop-Installer zu generieren. +* **ZIP** – Fallback, wenn `appdmg` fehlt. +* Setzt CFBundle-Identifikatoren und Versions-Plist automatisch. + +### Windows + +* **MSI** – `internal/commands/packager.go` kapselt die **WiX**-Tools candle & light. + Heat generiert automatisch den Komponent-Baum aus der gebauten `.exe`. + +Zusätzliche Ressourcen: + +* `internal/commands/windows_resources/` enthält templated **.wxs**-Fragmente. +* Versionsinformationen werden über das Utility `rsrc` injiziert. + +--- + +## 7. Build-Artefakt-Layout + +Nach einem erfolgreichen Build gibt die CLI Folgendes aus: + +``` +build/bin/ +├── myapp-linux-amd64 +└── myapp-linux-amd64.AppImage + +build/package/ +└── myapp_1.0.0_amd64.deb +``` + +Die genauen Dateien hängen von den Flags `-platform` und `-package` ab. + +--- + +## 8. Anpassen der Pipeline + +| Bedarf | Ansatz | +|------|----------| +| Linter vor dem Build ausführen | Fügen Sie eine `lint`-Aufgabe in **Taskfile.yml** hinzu und lassen Sie `build` davon abhängen. | +| Zusätzliche Linker-Flags | `wails3 build -ldflags "-H windowsgui"` | +| Packaging überspringen | `wails3 build -skip-package` (behält das rohe Binary). | +| Eigenen Packager verwenden | Implementieren Sie `internal/packager/.go`, registrieren Sie ihn in `packager.go`. | + +Alle Taskfile-Ziele verwenden Umgebungsvariablen, die von der CLI exportiert werden, sodass Sie Werte wie `$WAILS_VERSION` oder `$WAILS_PLATFORM` in benutzerdefinierten Aufgaben referenzieren können. + +--- + +## 9. Fehlerbehebung + +| Symptom | Wahrscheinliche Ursache | Lösung | +|---------|--------------|-----| +| **`ld: framework not found WebKit`** (mac) | Xcode CLI-Tools fehlen | `xcode-select --install` | +| **Leeres Fenster im Prod-Build** | Frontend-Build fehlgeschlagen oder SPA-Routing | Prüfen, ob `frontend/dist/index.html` existiert und `History API Fallback` eingestellt ist. | +| **`wixl` nicht gefunden** (Linux MSI Cross-Build) | WiX-Toolset nicht im Docker-Image installiert | Verwenden Sie `--docker`-Build oder installieren Sie WiX manuell. | +| **Dupliziertes Symbol `_WinMain`** | Gemischte `windowsgui`-Flag und syso | Entfernen Sie benutzerdefinierte `-ldflags` oder lassen Sie Wails die Ressourcen verwalten. | + +Verbose-Modus: `wails3 build -verbose` gibt jeden ausgeführten Befehl aus. + +--- + +## 10. Wichtige Quellcode-Zuordnung + +| Anliegen | Datei | +|---------|------| +| Task-Runner-Kleber | `internal/commands/task_wrapper.go` | +| Build-Dispatcher | `internal/commands/build-assets.go` | +| AppImage-Builder | `internal/commands/appimage.go` | +| Generische Packager-Schnittstelle | `internal/packager/packager.go` | +| Windows-Ressourcengenerator | `internal/commands/syso.go` | +| Build-Info-Injektor | `internal/commands/tool_buildinfo.go` | +| Versionskonstanten | `internal/version/version.go` | + +Halten Sie diese Tabelle bereit, wenn Sie einen Build-Fehler nachverfolgen. + +--- + +Sie haben nun das vollständige Bild von **Quellcode** bis **Installer**. Mit diesem Wissen können Sie die Pipeline anpassen, neue Packaging-Ziele hinzufügen oder Cross-Compilation-Probleme debuggen, ohne Angst zu haben. Viel Erfolg beim Veröffentlichen! \ No newline at end of file diff --git a/docs/src/content/docs/de/contributing/codebase-layout.mdx b/docs/src/content/docs/de/contributing/codebase-layout.mdx new file mode 100644 index 00000000000..c538528754a --- /dev/null +++ b/docs/src/content/docs/de/contributing/codebase-layout.mdx @@ -0,0 +1,216 @@ +--- +title: Codebase-Layout +description: Wie das Wails v3-Repository organisiert ist und wie die Teile zusammenpassen +sidebar: + order: 2 +--- + +Wails v3 lebt in einem **Monorepo**, das die Framework-Laufzeitumgebung, die CLI, +Beispiele, Dokumentation und die Build-Toolchain enthält. +Diese Seite führt durch die *Verzeichnisstruktur*, die für alle relevant ist, die +sich in die Interna einarbeiten. + +## Überblick auf oberster Ebene + +``` +wails/ +├── v3/ # ⬅️ Alles, was spezifisch für Wails v3 ist, befindet sich hier +├── v2/ # Legacy-v2-Implementierung (kann für v3-Arbeiten ignoriert werden) +├── docs/ # Astro-basierte v3-Dokumentationsseite (diese Seite!) +├── website/ # Docusaurus-v2-Seite und Marketing-Seiten (Hauptseite) +├── scripts/ # Verschiedene Hilfsskripte (z. B. Sponsor-Bildgenerator) +├── mkdocs-website/ # Veralteter v3-Dokumentationsprototyp +└── *.md # Projektweite Metadateien (CHANGELOG, LICENSE, …) +``` + +Von hier aus zoomen wir in den **`v3/`**-Baum. + +## `v3/`-Stammverzeichnis + +``` +v3/ +├── cmd/ # Kompilierbare Befehle (derzeit nur wails3 CLI) +├── examples/ # Praktische Beispiel-Apps, die jedes Feature testen +├── internal/ # Framework-Implementierung (keine öffentliche API) +├── pkg/ # Öffentliche Go-Pakete ‑ die API-Oberfläche +├── tasks/ # Taskfile-basierte Release-Hilfsprogramme +├── templates/ # RFC-ähnliche Vorschläge (WEP) + gemeinsame Assets +├── go.mod +└── go.sum +``` + +### Mentales Modell + +1. **`pkg/`** stellt *dasjenige bereit, was Anwendungs-Entwickler importieren* +2. **`internal/`** enthält *wie die Magie implementiert ist* +3. **`cmd/wails3`** steuert *Projekt-Lebenszyklus & Builds* +4. **`examples/`** dienen als *lebende Tests* und *Referenzcode* + +Alles andere unterstützt diese drei Säulen. + +--- + +## `cmd/` – Befehle + +| Pfad | Anmerkungen | +|------|-------| +| `v3/cmd/wails3` | Der **CLI-Einstiegspunkt**. Ein kleines `main.go` delegiert die gesamte Logik an Pakete in `internal/commands`. | +| `internal/commands/*` | Untergeordnete Befehle (init, dev, build, doctor, …). Jeder befindet sich in seiner eigenen Datei zur einfachen Auffindbarkeit. | +| `internal/commands/task_wrapper.go` | Brücke zwischen CLI-Flags und der Taskfile-Build-Pipeline. | + +Die CLI ist zuständig für: + +* **Projektgerüst** (`init`, Template-Generierung) +* **Dev-Server-Orchestrierung** (`dev`, Live-Reload) +* **Produktions-Builds & Verpackung** (`build`, `package`, Plattform-Wrapper) +* **Diagnose** (`doctor`) + +--- + +## `internal/` – Der Motorraum + +``` +internal/ +├── assetserver/ # Bereitstellung & Einbettung von Web-Assets +├── buildinfo/ # Reproduzierbare Build-Metadaten +├── commands/ # CLI-Mechaniken (siehe oben) +├── runtime/ # Desktop-Laufzeitumgebung (plattformabhängig) +├── generator/ # Statische Analyse & Bindungs-Generator +├── templates/ # Projekt-Templates (Frontend-Stacks) +├── packager/ # Linux AppImage/deb/rpm, Windows MSI, macOS DMG +├── capabilities/ # Abfrage der Host-OS-Fähigkeiten +├── dbus/ # Linux-System-Tray-Integration +├── service/ # IPC-Mikrodienst-Framework +└── ... # [andere Hilfsunterpakete] +``` + +### Wichtige Unter-Pakete + +| Paket | Verantwortung | Verbindungspunkt | +|---------|----------------|-------------------| +| `runtime` | Fenster/Event-Loop, Zwischenablage, Dialoge, System-Tray. Eine Datei pro OS mit Build-Tags (`*_darwin.go`, `*_linux.go`, …). | Aufgerufen von `pkg/application` und Nachrichtenprozessor. | +| `assetserver` | Dual-Modus-Dateiserver:
• Dev: dient von der Festplatte & proxyt Vite
• Prod: bettet Assets via `go:embed` ein | Initialisiert von `pkg/application` beim Start. | +| `generator` | Analysiert Go-Quellcode, um **Bindungs-Metadaten** zu erstellen, die später TypeScript-Stubs und Go-Marshal/Unmarshal-Code erzeugen. | Ausgelöst durch `wails3 init` / `wails3 generate`. | +| `packager` | Verpackt plattformspezifische Packaging-CLIs (z. B. `electron-builder`-Äquivalente) in Go für plattformübergreifende Automatisierung. | Aufgerufen von `wails3 package`. | + +Unterstützende Hilfsprogramme (z. B. `s/`, `hash/`, `flags/`) halten interne Belange entkoppelt. + +--- + +## `pkg/` – Öffentliche API + +``` +pkg/ +├── application/ # Kern-API: Fenster, Menüs, Dialoge, Events, … +├── runtime/ # JS-seitige Hilfsprogramme (Bridge, Events, Screen, ...) +├── options/ # Stark typisierte Konfigurationsstrukturen +├── menu/ # Deklarative Menü-DSL +└── ... # Plattform-Hilfsprogramme (mac/, windows/, assetserver/, …) +``` + +`pkg/application` initialisiert ein Wails-Programm: + +```go +func main() { + app := application.New(application.Options{ + Name: "MyApp", + Assets: application.NewAssetsFS(assetsFS), + }) + window := app.Window.New(&application.WebviewWindowOptions{ + Title: "Hello", + Width: 1024, + Height: 768, + }) + app.Run() +} +``` + +Unter der Haube tut es Folgendes: + +1. Startet `internal.runtime.*` +2. Richtet einen `assetserver` ein +3. Registriert Bindungen, die von `internal.generator` generiert wurden +4. Betritt den OS-Hauptthread + +--- + +## `examples/` – Lebende Spezifikationen + +Jeder Unterordner ist eine **in sich geschlossene Anwendung**, die ein Feature demonstriert. +Muster, die Sie auch in echtem Code wiederfinden: + +* Bindungsdienste (`examples/binding/`) +* Mehrere Fenster (`examples/window/`) +* System-Tray (`examples/systray-*`) +* Verpackung (`examples/file-association/`) + +Wenn Sie unsicher sind, beginnen Sie hier und tauchen Sie in die Implementierung ein. + +--- + +## `templates/` – Gerüst-Blaupausen + +`internal/templates` liefert **Basis-Templates** (Go-Layout) und **Frontend-Skins** +(React, Svelte, Vue, …). +Bei `wails3 init -t react` führt die CLI Folgendes aus: + +1. Kopiert `_common`-Go-Dateien +2. Fügt das gewünschte Frontend-Paket zusammen +3. Führt `npm install` + `task deps` aus + +Das Bearbeiten von Templates **hat keine Auswirkungen** auf bestehende Apps, nur auf zukünftige `init`-Aufrufe. + +--- + +## `tasks/` – Release-Automatisierung + +Taskfiles kapseln komplexe Cross-Kompilierung, Versionsaktualisierung und Changelog- +Generierung. Sie werden programmatisch von `internal/commands/task.go` verwendet, +damit dieselbe Logik **CLI** und **CI** antreibt. + +--- + +## Wie die Teile interagieren + +```d2 +direction: down +CLI: "wails3 CLI" +Generator: "internal/generator" +AssetDev: "assetserver (dev)" +Packager: "internal/packager" +AppRuntime: { + label: "App runtime" + ApplicationPkg: "pkg.application" + InternalRuntime: "internal.runtime" + OSAPIs: "OS APIs" +} +CLI -> Generator: "build / generate" +CLI -> AssetDev: "dev" +CLI -> Packager: "package" +Generator -> ApplicationPkg: "bindings" +ApplicationPkg -> InternalRuntime +InternalRuntime -> OSAPIs +ApplicationPkg -> AssetDev +``` + +*CLI → Generator → Laufzeitumgebung* bildet den Kernpfad von der **Quelle** zur **laufenden +Desktop-App**. + +--- + +## Orientierungshilfen + +| Möchten Sie verstehen… | Schauen Sie sich an… | +|---------------------|----------| +| Plattform-Adapter | `internal/runtime/*_DARWIN.go`, `*_windows.go`, … | +| Bridge-Protokoll | `pkg/application/messageprocessor_*.go` | +| Asset-Workflow | `internal/assetserver`, `v3/templates/base/assets` | +| Packaging-Flow | `internal/commands/appimage.go`, `internal/packager` | +| Template-Engine | `internal/templates/templates.go` | +| Statische Analyse | `internal/generator/*` | + +--- + +Sie haben nun eine **mentale Karte** des Repositories. +Verwenden Sie sie mit `ripgrep`, der Funktion „Gehe zu Datei/Symbol“ Ihrer IDE und den Beispiel-Apps, +um tiefer in jedes Feature einzutauchen. Viel Spaß beim Hacking! \ No newline at end of file diff --git a/docs/src/content/docs/de/contributing/extending-wails.mdx b/docs/src/content/docs/de/contributing/extending-wails.mdx new file mode 100644 index 00000000000..90ec86396ea --- /dev/null +++ b/docs/src/content/docs/de/contributing/extending-wails.mdx @@ -0,0 +1,244 @@ +--- +title: Wails erweitern +description: Praktischer Leitfaden zum Hinzufügen neuer Funktionen und Plattformen zu Wails v3 +sidebar: + order: 8 +--- + +> Wails ist so konzipiert, dass es **hackbar** ist. +> Jedes wichtige Subsystem befindet sich in Go-Code, den Sie lesen, modifizieren und veröffentlichen können. +> Diese Seite zeigt, _wo_ Sie anfangen und _wie_ Sie plattformübergreifend kompatibel bleiben, wenn Sie: + +* Einen **Service** hinzufügen (Dateiserver, KV-Speicher, benutzerdefiniertes IPC…) +* Einen **neuen CLI-Befehl** erstellen (`wails3 `) +* Die **Runtime** erweitern (Fenster-API, Dialoge, Ereignisse) +* Eine **Plattformfähigkeit** einführen (Wayland, Apple Vision OS…) +* **Plattformübergreifende Kompatibilität** aufrechterhalten, ohne in `//go:build`-Tags zu ertrinken + +--- + +## 1. Hinzufügen eines Services + +Services sind Go-Komponenten im Hintergrund, die über `application.Context` an Apps verfügbar gemacht werden. + +``` +internal/service/ +├── template/ # Boilerplate für neue Services +│ ├── template.go +│ └── README.md +└── service.go # Registrierung + Lebenszyklus-Schnittstellen +``` + +### 1.1 Service definieren + +```go +package chat + +type Service struct { + messages []string +} + +func New() *Service { return &Service{} } + +func (s *Service) Send(msg string) string { + s.messages = append(s.messages, msg) + return "ok" +} +``` + +### 1.2 `service.Service` implementieren + +```go +func (s *Service) Init(ctx *application.Context) error { return nil } +func (s *Service) Shutdown() error { return nil } +``` + +### 1.3 Generator registrieren + +*Zu* `internal/generator/collect/services.go` *hinzufügen* + +```go +services.Register("chat", chat.New) +``` + +> Jetzt generiert `wails3 generate` Bindungen, damit JS `window.backend.chat.Send("hi")` aufrufen kann. + +### 1.4 Ein Beispiel veröffentlichen + +Kopieren Sie `v3/examples/services/` und passen Sie es an. + +--- + +## 2. Schreiben eines neuen CLI-Befehls + +Die CLI-Logik befindet sich unter `internal/commands/`. +Jeder Befehl ist **eine Datei**, die sich in `init()` registriert. + +### 2.1 Datei erstellen + +`v3/internal/commands/hello.go` + +```go +package commands + +import ( + "github.com/spf13/cobra" +) + +func init() { + Add(&cobra.Command{ + Use: "hello", + Short: "Prints Hello World", + RunE: func(cmd *cobra.Command, args []string) error { + cmd.Println("Hello Wails!") + return nil + }, + }) +} +``` + +`Add()` registriert sich mit der Root in `cmd/wails3/main.go`. + +### 2.2 CLI neu kompilieren + +``` +go install ./v3/cmd/wails3 +wails3 hello +``` + +Wenn Ihr Befehl eine **Taskfile**-Integration benötigt, verwenden Sie die Hilfsfunktionen in +`internal/commands/task_wrapper.go`. + +--- + +## 3. Ändern der Runtime + +Häufige Gründe: + +* Neue Fensterfunktion (`SetOpacity`, `Shake`, …) +* Zusätzlicher Dialog (`ColorPicker`) +* System-API (Helligkeit des Bildschirms) + +### 3.1 Öffentliche API + +Zu `pkg/application/window.go` hinzufügen: + +```go +func (w *WebviewWindow) SetOpacity(o float32) { + w.ctx.Call("window:setOpacity", o) +} +``` + +### 3.2 Nachrichtenprozessor + +Erstellen Sie `messageprocessor_window_opacity.go`: + +```go +const MsgSetOpacity = "window:setOpacity" + +func init() { register(MsgSetOpacity, handleSetOpacity) } + +func handleSetOpacity(ctx *Context, params json.RawMessage) ([]byte, error) { + var req struct { + ID uint64 `json:"id"` + Opacity float32 `json:"o"` + } + json.Unmarshal(params, &req) + return nil, runtime.SetOpacity(req.ID, req.Opacity) +} +``` + +### 3.3 Plattformimplementierung + +``` +internal/runtime/ + webview_window_darwin.go + webview_window_linux.go + webview_window_windows.go +``` + +Fügen Sie `SetOpacity()` zu jeder Datei hinzu, geschützt durch Build-Tags. +Wenn eine Plattform dies nicht unterstützen kann, geben Sie `ErrCapability` zurück. + +### 3.4 Fähigkeitsflag + +Über `internal/capabilities` verfügbar machen. + +```go +const CapOpacity = "window:opacity" +``` + +Runtime-Dateien `*_darwin.go` usw. sollten `registerCapability(CapOpacity)` aufrufen, wenn +die Initialisierung erfolgreich war. + +Apps können abfragen: + +```go +if application.HasCapability(application.CapOpacity) { ... } +``` + +--- + +## 4. Hinzufügen neuer Plattformfähigkeiten + +Beispiel: **Wayland**-Zwischenablage unter Linux. + +1. Forken Sie `internal/runtime/clipboard_linux.go`. +2. Datei aufteilen: + * `clipboard_linux_x11.go` → `//go:build linux && !wayland` + * `clipboard_linux_wayland.go` → `//go:build linux && wayland` +3. CLI-Flag `--tags wayland` in `internal/commands/dev.go` hinzufügen + (`goEnv.BuildTags += ",wayland"`). +4. In **Asset Server** & README dokumentieren. + +> Halten Sie die standardmäßigen Build-Tags minimal; reservieren Sie opt-in-Tags für Nischenfunktionen. + +--- + +## 5. Checkliste für plattformübergreifende Kompatibilität + +| ✅ Schritt | Warum | +|---------|-----| +| Stellen Sie **jede** öffentliche Methode in allen Plattformdateien bereit (auch wenn nur als Stub) | Hält den Build auf allen OS/Archs grün | +| Kapseln Sie plattformspezifische Details hinter **Fähigkeiten** | Ermöglicht Apps, gracefully zu degradieren | +| Verwenden Sie zuerst **pure Go**, CGO nur bei Bedarf | Vereinfacht Cross-Compiles | +| Testen Sie mit `task matrix:test` | Führt `go test ./...` auf linux/mac/windows in Docker aus | +| Dokumentieren Sie neue Build-Tags in `docs/getting-started/installation.mdx` | Benutzer müssen die Flags kennen | + +--- + +## 6. Debug-Builds & Iterationsgeschwindigkeit + +* `wails3 dev -tags debug` fügt zusätzliche Log-Hooks hinzu (`logger_dev*.go`). +* Verwenden Sie `task reload`, um die Runtime neu zu kompilieren, ohne die gesamte App neu zu starten. +* Race-Detektor: `wails3 dev -race` (siehe `pkg/application/RACE.md`). + +--- + +## 7. Beiträge an das Hauptprojekt + +1. Öffnen Sie ein **Issue**, um die Idee und das Design zu besprechen. +2. Folgen Sie den oben genannten Techniken zur Implementierung. +3. Hinzufügen: + * Unit-Tests (`*_test.go`) + * Beispiel (`v3/examples//`) + * Dokumentation (diese Datei oder API-Referenz) +4. Stellen Sie sicher, dass `go vet`, `golangci-lint` und die CI-Matrix bestehen. + +--- + +### Schnelllinks + +| Bereich | Ort | +|------|----------| +| Service-Framework | `internal/service/` | +| CLI-Kern | `internal/commands/` | +| Runtime pro OS | `internal/runtime/` | +| Hilfsfunktionen für Fähigkeiten | `internal/capabilities/` | +| Taskfile DSL | `tasks/Taskfile.yml` | +| Dev-Matrix-Tests | `tasks/events/generate.go` | + +--- + +Sie haben nun einen **Fahrplan**, um Wails nach Ihren Wünschen zu formen – fügen Sie Services hinzu, verteilen Sie CLI-Magie, hacken Sie die Runtime oder bringen Sie völlig neue OS-Features ein. +Viel Spaß beim Erweitern! \ No newline at end of file diff --git a/docs/src/content/docs/de/contributing/getting-started.mdx b/docs/src/content/docs/de/contributing/getting-started.mdx new file mode 100644 index 00000000000..ed47241433c --- /dev/null +++ b/docs/src/content/docs/de/contributing/getting-started.mdx @@ -0,0 +1,367 @@ +--- +title: Erste Schritte +description: So tragen Sie zu Wails v3 bei +--- + +import { Steps, Tabs, TabItem } from '@astrojs/starlight/components'; + +## Willkommen, Mitwirkender! + +Vielen Dank für Ihr Interesse an der Mitarbeit an Wails! Dieser Leitfaden hilft Ihnen bei Ihrem ersten Beitrag. + +## Voraussetzungen + +Stellen Sie vor dem Start sicher, dass Folgendes installiert ist: + +- **Go 1.25+** ([download](https://go.dev/dl/)) +- **Node.js 20+** und **npm** ([download](https://nodejs.org/)) +- **Git**, das mit Ihrem GitHub-Konto konfiguriert ist +- Grundlegende Kenntnisse in Go und JavaScript/TypeScript + +### Plattformspezifische Anforderungen + +**macOS:** +- Xcode Command Line Tools: `xcode-select --install` + +**Windows:** +- MSYS2 oder eine ähnliche Unix-ähnliche Umgebung wird empfohlen +- WebView2-Laufzeitumgebung (auf Windows 11 in der Regel vorinstalliert) + +**Linux:** +- `gcc`, `pkg-config`, `libgtk-3-dev`, `libwebkit2gtk-4.0-dev` +- Installation über: `sudo apt install build-essential pkg-config libgtk-3-dev libwebkit2gtk-4.0-dev` (Debian/Ubuntu) + +## Überblick über den Beitragsprozess + +Der typische Workflow für Beiträge folgt diesen Schritten: + +1. **Fork & Clone** - Erstellen Sie Ihre eigene Kopie des Wails-Repositorys +2. **Einrichtung** - Erstellen Sie die Wails CLI und überprüfen Sie Ihre Umgebung +3. **Branch** - Erstellen Sie einen Feature-Branch für Ihre Änderungen +4. **Entwicklung** - Nehmen Sie Ihre Änderungen gemäß unseren Coding-Standards vor +5. **Tests** - Führen Sie Tests aus, um sicherzustellen, dass alles funktioniert +6. **Commit** - Committen Sie mit klaren, konventionellen Commit-Nachrichten +7. **Einreichen** - Öffnen Sie einen Pull Request zur Überprüfung +8. **Iteration** - Reagieren Sie auf Feedback und nehmen Sie Anpassungen vor +9. **Zusammenführung** - Nach der Freigabe werden Ihre Änderungen Teil von Wails! + +## Schritt-für-Schritt-Anleitung + +Wählen Sie Ihre Art des Beitrags: + + + + + + +1. **Bug finden oder melden** + + - Prüfen Sie, ob der Bug bereits in [GitHub Issues](https://github.com/wailsapp/wails/issues) gemeldet wurde + - Wenn nicht, erstellen Sie ein neues Issue mit den Schritten zur Reproduktion + - Warten Sie auf Bestätigung, bevor Sie mit der Arbeit beginnen + +2. **Fork und Clone** + + Forken Sie das Repository unter [github.com/wailsapp/wails/fork](https://github.com/wailsapp/wails/fork) + + Klonen Sie Ihren Fork: + ```bash + git clone https://github.com/YOUR_USERNAME/wails.git + cd wails + git remote add upstream https://github.com/wailsapp/wails.git + ``` + +3. **Erstellen und Überprüfen** + + Erstellen Sie Wails und überprüfen Sie, ob Sie den Bug reproduzieren können: + ```bash + cd v3 + go build -o ../wails3 ./cmd/wails3 + + # Reproduzieren Sie den Bug, um ihn zu verstehen + ``` + +4. **Erstellen Sie einen Bug-Fix-Branch** + + Erstellen Sie einen Branch für Ihre Korrektur: + ```bash + git checkout -b fix/issue-123-window-crash + ``` + +5. **Den Bug beheben** + + - Nehmen Sie die minimal notwendigen Änderungen vor, um den Bug zu beheben + - Refaktorieren Sie keinen unrelateden Code + - Fügen Sie Tests hinzu oder aktualisieren Sie diese, um Regressionen zu verhindern + + ```bash + # Nehmen Sie Ihre Änderungen vor + # Fügen Sie Tests in *_test.go-Dateien hinzu + ``` + +6. **Ihre Korrektur testen** + + Führen Sie Tests aus, um sicherzustellen, dass die Korrektur funktioniert: + ```bash + go test ./... + + # Testen Sie das spezifische Paket + go test ./pkg/application -v + + # Ausführen mit Race-Detector + go test ./... -race + ``` + +7. **Ihre Korrektur committen** + + Committen Sie mit einer klaren Nachricht: + ```bash + git commit -m "fix: prevent window crash when closing during initialization + + Fixes #123" + ``` + +8. **Pull Request einreichen** + + Pushen und PR erstellen: + ```bash + git push origin fix/issue-123-window-crash + ``` + + In Ihrer PR-Beschreibung: + - Erklären Sie den Bug und die Ursache + - Beschreiben Sie Ihre Korrektur + - Verweisen Sie auf das Issue: "Fixes #123" + - Fügen Sie Verhalten vor/nach hinzu + +9. **Auf Feedback reagieren** + + Bearbeiten Sie Review-Kommentare und aktualisieren Sie Ihren PR nach Bedarf. + + + + + + + + +1. **Die Funktion diskutieren** + + - Öffnen Sie eine [GitHub Discussion](https://github.com/wailsapp/wails/discussions) oder ein Issue + - Beschreiben Sie, was Sie hinzufügen möchten und warum + - Warten Sie auf Feedback der Maintainer, bevor Sie mit der Implementierung beginnen + - Stellen Sie sicher, dass es mit den Zielen von Wails übereinstimmt + +2. **Fork und Clone** + + Forken Sie das Repository unter [github.com/wailsapp/wails/fork](https://github.com/wailsapp/wails/fork) + + Klonen Sie Ihren Fork: + ```bash + git clone https://github.com/YOUR_USERNAME/wails.git + cd wails + git remote add upstream https://github.com/wailsapp/wails.git + ``` + +3. **Entwicklungsumgebung einrichten** + + Erstellen Sie Wails und überprüfen Sie Ihre Umgebung: + ```bash + cd v3 + go build -o ../wails3 ./cmd/wails3 + + # Führen Sie Tests aus, um sicherzustellen, dass alles funktioniert + go test ./... + ``` + +4. **Erstellen Sie einen Feature-Branch** + + Erstellen Sie einen beschreibenden Branch: + ```bash + git checkout -b feat/window-transparency-support + ``` + +5. **Die Funktion implementieren** + + - Befolgen Sie unsere [Coding Standards](/de/contributing/standards) + - Halten Sie die Änderungen auf die Funktion fokussiert + - Schreiben Sie sauberen, dokumentierten Code + - Fügen Sie umfassende Tests hinzu + + ```bash + # Beispiel: Hinzufügen einer neuen Fenstermethode + # 1. Zur window.go-Schnittstelle hinzufügen + # 2. In Plattform-Dateien implementieren (darwin, windows, linux) + # 3. Tests hinzufügen + # 4. Dokumentation aktualisieren + ``` + +6. **Gründlich testen** + + Testen Sie Ihre Funktion: + ```bash + # Unit-Tests + go test ./pkg/application -v + + # Integrationstest - erstellen Sie eine Test-App + cd .. + ./wails3 init -n feature-test + cd feature-test + # Fügen Sie Code hinzu, der Ihre neue Funktion verwendet + ../wails3 dev + ``` + +7. **Ihre Funktion dokumentieren** + + - Fügen Sie Docstrings zu allen öffentlichen APIs hinzu + - Aktualisieren Sie die relevante Dokumentation in `/docs` + - Fügen Sie Beispiele hinzu, falls zutreffend + +8. **Mit Konvention committen** + + Verwenden Sie konventionelle Commits: + ```bash + git commit -m "feat: add window transparency support + + - Add SetTransparent() method to Window API + - Implement for macOS, Windows, and Linux + - Add tests and documentation + + Closes #456" + ``` + +9. **Pull Request einreichen** + + Pushen und PR erstellen: + ```bash + git push origin feat/window-transparency-support + ``` + + In Ihrem PR: + - Beschreiben Sie die Funktion und Anwendungsfälle + - Zeigen Sie Beispiele oder Screenshots + - Listen Sie alle Breaking Changes auf + - Verweisen Sie auf die Diskussion/das Issue + +10. **Basierend auf dem Review iterieren** + + Maintainer können Änderungen anfordern. Seien Sie geduldig und kooperativ. + + + + + + + + +1. **Dokumentationsbedarf identifizieren** + + - Haben Sie veraltete Dokumente während der Nutzung von Wails gefunden? + - Fehlen Beispiele oder Erklärungen? + - Möchten Sie Tippfehler korrigieren oder die Klarheit verbessern? + - Prüfen Sie [Dokumentations-Issues](https://github.com/wailsapp/wails/labels/documentation) + +2. **Fork und Clone** + + Forken Sie das Repository unter [github.com/wailsapp/wails/fork](https://github.com/wailsapp/wails/fork) + + Klonen Sie Ihren Fork: + ```bash + git clone https://github.com/YOUR_USERNAME/wails.git + cd wails + git remote add upstream https://github.com/wailsapp/wails.git + ``` + +3. **Dokumentationsumgebung einrichten** + + Die Docs befinden sich in `/docs` und werden mit Astro erstellt: + ```bash + cd docs + npm install + npm run dev + ``` + + Öffnen Sie http://localhost:4321/, um Änderungen live vorzubereiten. + +4. **Erstellen Sie einen Dokumentations-Branch** + + Erstellen Sie einen Branch für Ihre Änderungen: + ```bash + git checkout -b docs/improve-window-api-examples + ``` + +5. **Ihre Änderungen vornehmen** + + Die Dokumentationsdateien befinden sich in `/docs/src/content/docs/`: + ```bash + # Bearbeiten Sie MDX-Dateien + # Überprüfen Sie die Vorschau in Ihrem Browser + # Stellen Sie sicher, dass das Format korrekt ist + ``` + + **Best Practices:** + - Verwenden Sie klare, prägnante Sprache + - Fügen Sie praktische Code-Beispiele hinzu + - Fügen Sie Links zu verwandten Abschnitten hinzu + - Prüfen Sie Rechtschreibung und Grammatik + - Testen Sie alle Code-Beispiele + +6. **Ihre Änderungen überprüfen** + + Überprüfen Sie die Live-Vorschau und stellen Sie sicher: + - Links funktionieren korrekt + - Code-Beispiele sind genau + - Formatierung wird korrekt gerendert + - Keine defekten Bilder oder Referenzen + +7. **Dokumentationsänderungen committen** + + Committen Sie mit einer klaren Nachricht: + ```bash + git commit -m "docs: add practical examples to Window API guide + + - Add window positioning examples + - Include common patterns section + - Fix broken links to Event API" + ``` + +8. **Pull Request einreichen** + + Pushen und PR erstellen: + ```bash + git push origin docs/improve-window-api-examples + ```In deinem PR: +- Beschreibe, welche Dokumentation du verbessert hast +- Erkläre, warum die Änderung den Nutzern hilft +- Füge Screenshots hinzu, wenn visuelle Änderungen vorgenommen wurden + +9. **Review-Feedback bearbeiten** + +Dokumentations-Pull Requests werden in der Regel schnell geprüft und zusammengeführt! + + + + + + +## Finden von Issues zur Bearbeitung + +- Suche nach [`good first issue`](https://github.com/wailsapp/wails/labels/good%20first%20issue)-Labels +- Prüfe [`help wanted`](https://github.com/wailsapp/wails/labels/help%20wanted)-Issues +- Durchsuche [offene Issues](https://github.com/wailsapp/wails/issues) und bitte um Zuweisung + +## Hilfe erhalten + +- **Discord:** Tritt dem [Wails Discord](https://discord.gg/JDdSxwjhGf) bei +- **Diskussionen:** Poste in [GitHub Discussions](https://github.com/wailsapp/wails/discussions) +- **Issues:** Öffne ein Issue, wenn du einen Bug findest oder eine Frage hast + +## Verhaltenskodex + +Sei respektvoll, konstruktiv und einladend. Wir bauen eine freundliche Community auf, die sich darauf konzentriert, großartige Software gemeinsam zu entwickeln. + +## Nächste Schritte + +- Richte deine [Entwicklungsumgebung](/de/contributing/setup) ein +- Überprüfe unsere [Coding-Standards](/de/contributing/standards) +- Entdecke die [technische Dokumentation](/de/contributing) \ No newline at end of file diff --git a/docs/src/content/docs/de/contributing/index.mdx b/docs/src/content/docs/de/contributing/index.mdx new file mode 100644 index 00000000000..8ac08ac0ca0 --- /dev/null +++ b/docs/src/content/docs/de/contributing/index.mdx @@ -0,0 +1,94 @@ +--- +title: Technischer Überblick +description: Hochrangige Architektur und Roadmap zum Wails v3-Codebase +sidebar: + order: 1 +--- + +import { Card, CardGrid } from "@astrojs/starlight/components"; + +## Willkommen zur technischen Dokumentation von Wails v3 + +Dieser Abschnitt handelt **nicht** von Community-Richtlinien oder wie man einen Pull-Request erstellt. +Stattdessen taucht er tief ein in die **Art und Weise, wie Wails v3 gebaut ist**, damit Sie sich schnell +im Codebase zurechtfinden und mit Vertrauen an der Codeentwicklung arbeiten können. + +Egal, ob Sie planen, die Laufzeit zu patchen, die CLI zu erweitern, neue Templates zu erstellen oder +einfach die Interna zu verstehen, die folgenden Seiten bieten den technischen +Kontext, den Sie benötigen. + +--- + +## Hochrangige Architektur + + + + Das Herzstück jeder Wails-App ist Go-Code, der zu einer nativen ausführbaren Datei kompiliert wird. + Er übernimmt die Anwendungslogik, die Systemintegration und performancekritische + Operationen. + + + + Die UI wird mit Standard-Webtechnologien (React, Vue, Svelte, Vanilla, …) geschrieben + und von einem leichtgewichtigen System-WebView gerendert (WebKit auf Linux/macOS, WebView2 auf + Windows). + + + + Eine speicherlose, im Speicher befindliche Brücke ermöglicht **Go⇄JavaScript**-Aufrufe mit automatischer + Typkonvertierung, Ereignisweitergabe und Fehlerweiterleitung. + + + + `wails3` orchestriert die Projekterstellung, den Live-Reload-Dev-Server, das Asset-Bündeln, + die Cross-Kompilierung und das Packaging (deb, rpm, AppImage, msi, dmg…). + + + +--- + +## Architektonischer Überblick + +**Wails v3 – End-to-End-Flow** + +{/* +TODO: Fix D2 diagram generation (triple quotes for multi-line strings) or embed as image. +The previous D2 code block was causing MDX parsing errors in the build pipeline. +*/} + +**[End-to-End-Flow-Diagramm-Platzhalter]** + + +Das Diagramm zeigt den **End-to-End-Flow**: + +1. Die **CLI** steuert die Generierung, den Dev-Server, die Kompilierung und das Packaging. +2. Das **Binding-System** erzeugt Klebecode, der es dem **Web-Frontend** ermöglicht, in das **Go-Backend** aufzurufen. +3. Während der Entwicklung proxyt der **Asset-Server** zum Framework-Dev-Server; in der Produktion werden eingebettete Dateien ausgeliefert. +4. zur Laufzeit verwaltet das **Desktop-Runtime** Fenster und OS-APIs, während die **Bridge** Nachrichten zwischen Go und JavaScript transportiert. + +--- + +## Was diese Dokumentation abdeckt + +| Thema | Warum es wichtig ist | +| ----- | -------------- | +| **Codebase-Layout** | Karte der `/v3`-Verzeichnisse und wie Module interagieren. | +| **Runtime-Internals** | Fenster-Management, System-APIs, Nachrichtenprozessor und Platform-Shims. | +| **Asset- & Dev-Server** | Wie Web-Assets im Dev-Betrieb ausgeliefert und in der Produktion eingebettet werden. | +| **Build- & Packaging-Pipeline** | Taskfile-basierter Workflow, plattformübergreifende Kompilierung und Installer-Generierung. | +| **Binding-System** | Statische Analyse-Pipeline, die typsichere Go⇄TS-Bindings generiert. | +| **Template-System** | Generator-Architektur, die `wails init -t ` antreibt. | +| **Testing & CI** | Unit-/Integrationstest-Harness, GitHub Actions, Hinweise zum Race-Detector. | +| **Erweitern von Wails** | Hinzufügen von Services, Templates oder CLI-Unterbefehlen. | + +Jede nachfolgende Seite geht tiefer in diese Bereiche ein, mit konkreten Codebeispielen, +Diagrammen und Verweisen auf die relevanten Quelldateien. + +--- + +:::note +Voraussetzungen: Sie sollten mit **Go 1.25+**, grundlegendem TypeScript +und modernen Frontend-Build-Tools vertraut sein. Wenn Sie neu in Go sind, betrachten Sie es als empfehlenswert, zuerst den offiziellen Tour durchzuarbeiten. +::: + +Viel Spaß beim Erkunden — und willkommen in den Wails v3-Internals! \ No newline at end of file diff --git a/docs/src/content/docs/de/contributing/runtime-internals.mdx b/docs/src/content/docs/de/contributing/runtime-internals.mdx new file mode 100644 index 00000000000..f2e6e7cc083 --- /dev/null +++ b/docs/src/content/docs/de/contributing/runtime-internals.mdx @@ -0,0 +1,204 @@ +--- +title: Laufzeit-Internals +description: Tiefgehender Einblick darin, wie Wails v3 startet, läuft und mit dem Betriebssystem kommuniziert +sidebar: + order: 3 +--- + +Die **Laufzeitumgebung** (Runtime) ist die Schicht, die gewöhnliche Go-Funktionen in eine plattformübergreifende Desktop-Anwendung verwandelt. +Dieses Dokument erklärt die Komponenten, die Sie beim Durchlaufen des Quellcodes kennenlernen werden. + +--- + +## 1. Anwendungslebenszyklus + +| Phase | Code-Pfad | Was passiert | +|-------|-----------|--------------| +| **Bootstrap** | `pkg/application/application.go:init()` | Registriert Build-Zeit-Daten, erstellt ein globales `application`-Singleton. | +| **New()** | `application.New(...)` | Validiert `Options`, startet den **AssetServer**, initialisiert das Logging. | +| **Run()** | `application.(*App).Run()` | 1. Ruft plattformspezifisches `mainthread.X()` auf, um in den OS-UI-Thread einzutreten.
2. Startet die **Laufzeitumgebung** (`internal/runtime`).
3. Blockiert, bis das letzte Fenster geschlossen wird oder `Quit()` aufgerufen wird. | +| **Shutdown** | `application.(*App).Quit()` | Sendet `application:shutdown`-Ereignis, leert den Log, baut Fenster & Dienste ab. | + +Der Lebenszyklus ist strikt **Single-Entry**: Sie können viele Fenster erstellen, aber das Anwendungsobjekt selbst wird nur einmal initialisiert. + +--- + +## 2. Fensterverwaltung + +### Öffentliche API + +```go +win := app.Window.New(&application.WebviewWindowOptions{ + Title: "Dashboard", + Width: 1280, + Height: 720, +}) +win.Show() +``` + +`app.Window.New()` delegiert an `internal/runtime/webview_window_*.go`, wo die plattformspezifischen Konstruktoren liegen: + +``` +internal/runtime/ +├── webview_window_darwin.go +├── webview_window_linux.go +└── webview_window_windows.go +``` + +Jede Datei: + +1. Erstellt ein natives WebView (WKWebView, WebKitGTK, WebView2). +2. Registriert einen **Message Processor** Callback. +3. Mappt Wails-Ereignisse (`WindowResized`, `Focus`, `DropFile`, …) auf Laufzeit-Ereignis-IDs. + +Fenster werden von `screenmanager.go` verwaltet, das **Query-APIs** (alle Displays, DPI, aktives Fenster) anbietet und das Buchführen von Resize-/Move-Operationen zentralisiert. + +--- + +## 3. Nachrichtenverarbeitungs-Pipeline + +Die Brücke zwischen JavaScript und Go wird durch die Familie der **Message Processors** in `pkg/application/messageprocessor_*.go` implementiert. + +Ablauf: + +1. **JavaScript** ruft `window.runtime.Invoke("Greet", "Alice")` auf. +2. Die Laufzeitumgebung serialisiert die Anfrage: + `{"t":"c","id":"123","m":"Greet","p":["Alice"]}` + (`t` = Typ, `c` = Aufruf). +3. **Go** empfängt dieses JSON über den WebView-Callback. +4. `messageprocessor_call.go` sucht die gebundene Methode in der generierten Tabelle (`application.bindings.go`) und führt sie aus. +5. Das Ergebnis oder der Fehler wird zurück an JS gemarshalled, wo ein `Promise` aufgelöst wird. + +Spezialisierte Prozessoren: + +| Datei | Zweck | +|------|---------| +| `messageprocessor_window.go` | Fensteraktionen (ausblenden, maximieren, …) | +| `messageprocessor_dialog.go` | Native Dialoge (`OpenFile`, `MessageBox`, …) | +| `messageprocessor_clipboard.go` | Zwischenablage lesen/schreiben | +| `messageprocessor_events.go` | Ereignis abonnieren / senden | +| `messageprocessor_browser.go` | Browser-Navigation, DevTools | + +Prozessoren sind **zustandslos** – sie ziehen alles, was sie benötigen, aus dem `ApplicationContext`, das mit jeder Nachricht übergeben wird. + +--- + +## 4. Ereignissystem + +Ereignisse sind namespaced Strings, die über drei Schichten hinweg verteilt werden: + +1. **Anwendungsereignisse**: globaler Lebenszyklus (`application:ready`, + `application:shutdown`). +2. **Fensterereignisse**: pro Fenster (`window:focus`, `window:resize`). +3. **Benutzerdefinierte Ereignisse**: benutzerdefiniert (`chat:new-message`). + +Implementierungsdetails: + +* Konstanten werden aus `internal/events/defaults.go` generiert. +* Go-Seite: + `app.On("window:focus", func(e application.WindowEvent) {...})` +* JS-Seite: + `window.runtime.EventsOn("chat:new-message", cb)` + +Unter der Haube mappen beide auf denselben **EventBus** in +`pkg/application/events.go`. +Abonnenten sind referenzgezählt; wenn ein Fenster geschlossen wird, werden seine Callbacks automatisch abgemeldet, um Speicherlecks zu vermeiden. + +--- + +## 5. Plattformspezifische Implementierungen + +Bedingte Kompilierung hält die öffentliche API identisch, während OS-spezifische Details verborgen werden. + +| Anliegen | Darwin | Linux | Windows | +|---------|--------|-------|---------| +| Hauptthread | `mainthread_darwin.go` (Cgo zu Foundation) | `mainthread_linux.go` (GTK) | `mainthread_windows.go` (Win32 `AttachThreadInput`) | +| Dialoge | `dialogs_darwin.*` (NSAlert) | `dialogs_linux.go` (GtkFileChooser) | `dialogs_windows.go` (IFileOpenDialog) | +| Zwischenablage | `clipboard_darwin.go` | `clipboard_linux.go` | `clipboard_windows.go` | +| Tray-Icons | `systemtray_darwin.*` | `systemtray_linux.go` (DBus) | `systemtray_windows.go` (Shell_NotifyIcon) | + +Wichtige Prinzipien: + +* **Kein Cgo auf Windows/Linux**, es sei denn, es ist unvermeidbar (Performance, Portabilität). +* Verwenden Sie **Build-Tags** (`//go:build darwin && !production`), um die Dateien lesbar zu halten. +* Bieten Sie **Funktionen** über `internal/capabilities` an, damit höhere Schichten graceful degradieren können. + +--- + +## 6. Dateiführer + +| Datei | Warum Sie sie bearbeiten würden | +|------|--------------------| +| `internal/runtime/runtime_*.go` | Globale Startlogik ändern, Debug-Hooks hinzufügen. | +| `internal/runtime/webview_window_*.go` | Neue Fenster-Hinweise oder Verhalten implementieren. | +| `pkg/application/messageprocessor_*.go` | Neue Brückenbefehle hinzufügen, die von JS aufrufbar sind. | +| `pkg/application/events_*.go` | Eingebaute Ereignisdefinitionen erweitern. | +| `internal/assetserver/*` | Dev/Production-Asset-Verarbeitung anpassen. | + +--- + +## 7. Debugging-Tipps + +* Starten Sie mit `WAILS_LOG_LEVEL=debug`, um jede Nachricht zu drucken, die die Brücke überquert. +* Verwenden Sie `wails3 dev -verbose`, um Live-Reload & Asset-Anfragen zu sehen. +* Führen Sie auf macOS unter `lldb --` aus, um Objective-C-Ausnahmen frühzeitig abzufangen. +* Für WebView2-Probleme unter Windows aktivieren Sie die Debug-Logs: + `set WEBVIEW2_ADDITIONAL_BROWSER_ARGUMENTS=--remote-debugging-port=9222` + +--- + +## 8. Erweitern der Laufzeitumgebung + +1. Definieren Sie ein **Capability-Flag** in `internal/capabilities`. +2. Implementieren Sie die Funktion in jeder Plattformsdatei unter Verwendung von Build-Tags. +3. Fügen Sie die öffentliche API in `pkg/application` hinzu. +4. Registrieren Sie einen neuen Nachrichtentyp oder ein Ereignis, wenn JS es aufrufen muss. +5. Aktualisieren Sie mindestens ein Beispiel in `v3/examples/`, das die Funktion nutzt. + +Folgen Sie dieser Checkliste, und Sie halten den plattformübergreifenden Vertrag intakt. + +--- + +## 9. Drag-and-Drop + +Datei-Drag-and-Drop verwendet auf allen Plattformen einen **JavaScript-first-Ansatz**. Die nativen Schicht fängt OS-Drag-Ereignisse ab, aber die eigentliche Drop-Verarbeitung und DOM-Interaktion erfolgt in JavaScript. + +### Ablauf + +1. Benutzer zieht Dateien vom OS über das Wails-Fenster +2. Die native Schicht erkennt den Drag und benachrichtigt JavaScript für Hover-Effekte +3. Benutzer lässt die Dateien los +4. Die native Schicht sendet Dateipfade + Koordinaten an JavaScript +5. JavaScript findet das Drop-Zielelement (`data-file-drop-target`) +6. JavaScript sendet Dateipfade + Elementdetails an das Go-Backend +7. Go sendet `WindowFilesDropped`-Ereignis mit vollem Kontext + +### Plattformspezifische Implementierungen + +| Plattform | Native Schicht | Herausforderung | +|----------|--------------|---------------| +| **Windows** | Eingebaute Drag-Unterstützung von WebView2 | Koordinaten in CSS-Pixeln, keine Konvertierung nötig | +| **macOS** | NSWindow Drag-Delegates | Fenster-relative zu WebView-relativen Koordinaten konvertieren | +| **Linux** | GTK3 Drag-Signale | Muss Dateidrag von internem HTML5-Drag unterscheiden | + +### Linux: Unterscheiden von Drag-Typen + +Sowohl GTK als auch WebKit wollen Drag-Ereignisse verarbeiten. Der Schlüssel liegt im Überprüfen des Drag-Zieltyps: + +```c +static gboolean is_file_drag(GdkDragContext *context) { + GList *targets = gdk_drag_context_list_targets(context); + for (GList *l = targets; l != NULL; l = l->next) { + GdkAtom atom = GDK_POINTER_TO_ATOM(l->data); + gchar *name = gdk_atom_name(atom); + if (name && g_strcmp0(name, "text/uri-list") == 0) { + g_free(name); + return TRUE; // Externer Datei-Drag + } + g_free(name); + } + return FALSE; // Interner HTML5-Drag +} +``` + +Signal-Handler geben `FALSE` für interne Dags zurück (WebKit sie verarbeiten lassen) und `TRUE` für Datei-Drag (selbst verarbeiten).Sie haben nun einen geführten Rundgang durch die Interna der Laufzeitumgebung erhalten. Kombinieren Sie dieses Wissen mit der Karte des **Codebase Layout** und der Dokumentation des **Asset Server**, um sicher zu navigieren und wirkungsvolle Beiträge zu leisten. Viel Spaß beim Coden! \ No newline at end of file diff --git a/docs/src/content/docs/de/contributing/setup.mdx b/docs/src/content/docs/de/contributing/setup.mdx new file mode 100644 index 00000000000..1bd85796218 --- /dev/null +++ b/docs/src/content/docs/de/contributing/setup.mdx @@ -0,0 +1,297 @@ +--- +title: Entwicklungsumgebung einrichten +description: Richten Sie Ihre Entwicklungsumgebung für die Wails v3-Entwicklung ein +--- + +## Einrichtung der Entwicklungsumgebung + +Dieser Leitfaden führt Sie durch die Einrichtung einer vollständigen Entwicklungsumgebung für die Arbeit an Wails v3. + +## Erforderliche Tools + +### Go-Entwicklung + +1. **Go 1.25 oder höher installieren:** + ```bash + # Download from https://go.dev/dl/ + go version # Verify installation + ``` + +2. **Go-Umgebung konfigurieren:** + ```bash + # Add to your shell profile (.bashrc, .zshrc, etc.) + export GOPATH=$HOME/go + export PATH=$PATH:$GOPATH/bin + ``` + +3. **Nützliche Go-Tools installieren:** + ```bash + go install golang.org/x/tools/cmd/goimports@latest + go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest + ``` + +### Node.js und npm + +Erforderlich zum Erstellen der Dokumentation und zum Testen von Frontend-Integrationen. + +```bash +# Install Node.js 20+ and npm +node --version # Should be 20+ +npm --version +``` + +### Plattform-spezifische Abhängigkeiten + +**macOS:** + +```bash +# Install Xcode Command Line Tools +xcode-select --install + +# Verify installation +xcode-select -p # Should output a path +``` + +**Windows:** + +1. Installieren Sie [MSYS2](https://www.msys2.org/) für eine unixähnliche Umgebung +2. WebView2 Runtime (auf Windows 11 vorinstalliert, [Download](https://developer.microsoft.com/en-us/microsoft-edge/webview2/) für Windows 10) +3. Optional: Installieren Sie [Git for Windows](https://git-scm.com/download/win) + +**Linux (Debian/Ubuntu):** + +```bash +sudo apt update +sudo apt install build-essential pkg-config libgtk-3-dev libwebkit2gtk-4.0-dev +``` + +**Linux (Fedora/RHEL):** + +```bash +sudo dnf install gcc pkg-config gtk3-devel webkit2gtk3-devel +``` + +**Linux (Arch):** + +```bash +sudo pacman -S base-devel gtk3 webkit2gtk +``` + +## Repository-Einrichtung + +### Klonen und Konfigurieren + +```bash +# Clone your fork +git clone https://github.com/YOUR_USERNAME/wails.git +cd wails + +# Add upstream remote +git remote add upstream https://github.com/wailsapp/wails.git + +# Verify remotes +git remote -v +``` + +### Erstellen der Wails CLI + +```bash +# Navigate to v3 directory +cd v3 + +# Build the CLI +go build -o ../wails3 ./cmd/wails3 + +# Test the build +cd .. +./wails3 version +``` + +### Zum PATH hinzufügen (Optional) + +**Linux/macOS:** + +```bash +# Add to ~/.bashrc or ~/.zshrc +export PATH=$PATH:/path/to/wails +``` + +**Windows:** + +Fügen Sie das Wails-Verzeichnis über die Systemeigenschaften Ihrer PATH-Umgebungsvariablen hinzu. + +## IDE-Einrichtung + +### VS Code (Empfohlen) + +1. **VS Code installieren:** [Download](https://code.visualstudio.com/) + +2. **Erweiterungen installieren:** + - Go (von Go Team at Google) + - ESLint + - Prettier + - MDX (für Dokumentation) + +3. **Arbeitsbereichseinstellungen konfigurieren** (`.vscode/settings.json`): + ```json + { + "go.useLanguageServer": true, + "go.lintTool": "golangci-lint", + "go.lintOnSave": "workspace", + "editor.formatOnSave": true, + "go.formatTool": "goimports" + } + ``` + +### GoLand + +1. **GoLand installieren:** [Download](https://www.jetbrains.com/go/) + +2. **Konfigurieren:** + - Go-Module-Unterstützung aktivieren + - File Watcher für `goimports` einrichten + - Code-Stil an die Projektkonventionen anpassen + +## Überprüfung Ihrer Einrichtung + +Führen Sie diese Befehle aus, um zu überprüfen, ob alles funktioniert: + +```bash +# Go version check +go version + +# Build Wails +cd v3 +go build ./cmd/wails3 + +# Run tests +go test ./pkg/... + +# Create a test app +cd .. +./wails3 init -n mytest -t vanilla +cd mytest +../wails3 dev +``` + +Wenn die Test-App erstellt und ausgeführt wird, ist Ihre Umgebung bereit! + +## Tests ausführen + +### Unit-Tests + +```bash +cd v3 +go test ./... +``` + +### Tests für spezifische Pakete + +```bash +go test ./pkg/application +go test ./pkg/events -v # Verbose output +``` + +### Mit Abdeckungsanalyse (Coverage) ausführen + +```bash +go test ./... -coverprofile=coverage.out +go tool cover -html=coverage.out +``` + +### Mit Race-Detector ausführen + +```bash +go test ./... -race +``` + +## Arbeiten mit der Dokumentation + +Die Wails-Dokumentation wird mit Astro und Starlight erstellt. + +```bash +cd docs + +# Install dependencies +npm install + +# Start dev server +npm run dev + +# Build for production +npm run build +``` + +Die Dokumentation ist unter `http://localhost:4321/` verfügbar. + +## Debugging + +### Go-Code debuggen + +**VS Code:** + +Erstellen Sie `.vscode/launch.json`: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Debug Wails CLI", + "type": "go", + "request": "launch", + "mode": "debug", + "program": "${workspaceFolder}/v3/cmd/wails3", + "args": ["dev"] + } + ] +} +``` + +**Befehlszeile:** + +```bash +# Use Delve debugger +go install github.com/go-delve/delve/cmd/dlv@latest +dlv debug ./cmd/wails3 -- dev +``` + +### Plattform-Code debuggen + +Das Debuggen plattformspezifischen Codes erfordert plattformspezifische Tools: + +- **macOS:** Xcode Instruments +- **Windows:** Visual Studio Debugger +- **Linux:** GDB + +## Häufige Probleme + +### "command not found: wails3" + +Fügen Sie das Wails-Verzeichnis zu Ihrem PATH hinzu oder verwenden Sie `./wails3` vom Projektstammverzeichnis aus. + +### "webkit2gtk not found" (Linux) + +Installieren Sie die WebKit2GTK-Entwicklungspakete: + +```bash +sudo apt install libwebkit2gtk-4.0-dev # Debian/Ubuntu +``` + +### Build schlägt mit Go-Module-Fehlern fehl + +```bash +cd v3 +go mod tidy +go mod download +``` + +### "CGO_ENABLED"-Fehler unter Windows + +Stellen Sie sicher, dass Sie einen C-Compiler (MinGW-w64 über MSYS2) in Ihrem PATH haben. + +## Nächste Schritte + +- [Coding Standards](/de/contributing/standards) überprüfen +- Die [Technische Dokumentation](/de/contributing) erkunden +- Ein zu bearbeitendes Problem finden: [Good First Issues](https://github.com/wailsapp/wails/labels/good%20first%20issue) \ No newline at end of file diff --git a/docs/src/content/docs/de/contributing/standards.mdx b/docs/src/content/docs/de/contributing/standards.mdx new file mode 100644 index 00000000000..a6eb717cebc --- /dev/null +++ b/docs/src/content/docs/de/contributing/standards.mdx @@ -0,0 +1,463 @@ +--- +title: Coding Standards +description: Code-Stil, Konventionen und Best Practices für Wails v3 +--- + +## Code-Stil und Konventionen + +Die Einhaltung konsistenter Coding-Standards macht die Codebasis leichter lesbar, wartbar und einfacher zur Mitarbeit beizutragen. + +## Go-Code-Standards + +### Code-Formatierung + +Verwenden Sie die Standard-Go-Formatierungstools: + +```bash +# Formatieren Sie den gesamten Code +gofmt -w . + +# Verwenden Sie goimports zur Organisation der Imports +goimports -w . +``` + +**Erforderlich:** Der gesamte Go-Code muss `gofmt` und `goimports` bestehen, bevor er committed wird. + +### Namenskonventionen + +**Pakete:** +- Kleinbuchstaben, möglichst ein einzelnes Wort +- `package application`, `package events` +- Vermeiden Sie Unterstriche oder gemischte Groß-/Kleinschreibung + +**Exportierte Namen:** +- PascalCase für Typen, Funktionen und Konstanten +- `type WebviewWindow struct`, `func NewApplication()` + +**Nicht exportierte Namen:** +- camelCase für interne Typen, Funktionen und Variablen +- `type windowImpl struct`, `func createWindow()` + +**Schnittstellen (Interfaces):** +- Namen nach Verhalten: `Reader`, `Writer`, `Handler` +- Schnittstellen mit einer einzigen Methode: Name mit Suffix `-er` + +```go +// Gut +type Closer interface { + Close() error +} + +// Vermeiden +type CloseInterface interface { + Close() error +} +``` + +### Fehlerbehandlung + +**Fehler immer prüfen:** + +```go +// Gut +result, err := doSomething() +if err != nil { + return fmt.Errorf("failed to do something: %w", err) +} + +// Schlecht - Fehler ignorieren +result, _ := doSomething() +``` + +**Fehler umschließen (Error Wrapping):** + +```go +// Fehler umschließen, um Kontext bereitzustellen +if err := validate(); err != nil { + return fmt.Errorf("validation failed: %w", err) +} +``` + +**Erstellen Sie benutzerdefinierte Fehlertypen, wenn nötig:** + +```go +type ValidationError struct { + Field string + Value string +} + +func (e *ValidationError) Error() string { + return fmt.Sprintf("invalid value %q for field %q", e.Value, e.Field) +} +``` + +### Kommentare und Dokumentation + +**Paket-Kommentare:** + +```go +// Package application provides the core Wails application runtime. +// +// It handles window management, event dispatching, and service lifecycle. +package application +``` + +**Exportierte Deklarationen:** + +```go +// NewApplication creates a new Wails application with the given options. +// +// The application must be started with Run() or RunWithContext(). +func NewApplication(opts Options) *Application { + // ... +} +``` + +**Implementierungskommentare:** + +```go +// processEvent handles incoming events from the runtime. +// It dispatches to registered handlers and manages event lifecycle. +func (a *Application) processEvent(event *Event) { + // Validate event before processing + if event == nil { + return + } + + // Find and invoke handlers + // ... +} +``` + +### Struktur von Funktionen und Methoden + +**Funktionen fokussiert halten:** + +```go +// Gut - einzelne Verantwortung +func (w *Window) setTitle(title string) { + w.title = title + w.updateNativeTitle() +} + +// Schlecht - zu viel tun +func (w *Window) updateEverything() { + w.setTitle(w.title) + w.setSize(w.width, w.height) + w.setPosition(w.x, w.y) + // ... 20 weitere Operationen +} +``` + +**Frühe Rückgaben verwenden:** + +```go +// Gut +func validate(input string) error { + if input == "" { + return errors.New("empty input") + } + + if len(input) > 100 { + return errors.New("input too long") + } + + return nil +} + +// Vermeiden Sie tiefe Verschachtelung +``` + +### Nebenläufigkeit (Concurrency) + +**Kontext für Abbrüche verwenden:** + +```go +func (a *Application) RunWithContext(ctx context.Context) error { + select { + case <-ctx.Done(): + return ctx.Err() + case <-a.done: + return nil + } +} +``` + +**Gemeinsame Zustände mit Mutexes schützen:** + +```go +type SafeCounter struct { + mu sync.Mutex + count int +} + +func (c *SafeCounter) Increment() { + c.mu.Lock() + defer c.mu.Unlock() + c.count++ +} +``` + +**Goroutine-Leaks vermeiden:** + +```go +// Gut - Goroutine hat eine Exit-Bedingung +func (a *Application) startWorker(ctx context.Context) { + go func() { + for { + select { + case <-ctx.Done(): + return // Sauberer Exit + case work := <-a.workChan: + a.process(work) + } + } + }() +} +``` + +### Tests + +**Namensgebung von Testdateien:** + +```go +// Implementierung: window.go +// Tests: window_test.go +``` + +**Tabellengetriebene Tests:** + +```go +func TestValidate(t *testing.T) { + tests := []struct { + name string + input string + wantErr bool + }{ + {"empty input", "", true}, + {"valid input", "hello", false}, + {"too long", strings.Repeat("a", 101), true}, + } + + for _, tt := range tests { + t.Run(tt.name, func(t *testing.T) { + err := validate(tt.input) + if (err != nil) != tt.wantErr { + t.Errorf("validate() error = %v, wantErr %v", err, tt.wantErr) + } + }) + } +} +``` + +## JavaScript/TypeScript-Standards + +### Code-Formatierung + +Verwenden Sie Prettier für eine konsistente Formatierung: + +```json +{ + "semi": false, + "singleQuote": true, + "tabWidth": 2, + "trailingComma": "es5" +} +``` + +### Namenskonventionen + +**Variablen und Funktionen:** +- camelCase: `const userName = "John"` + +**Klassen und Typen:** +- PascalCase: `class WindowManager` + +**Konstanten:** +- UPPER_SNAKE_CASE: `const MAX_RETRIES = 3` + +### TypeScript + +**Explizite Typen verwenden:** + +```typescript +// Gut +function greet(name: string): string { + return `Hello, ${name}` +} + +// Vermeiden Sie implizites any +function process(data) { // Schlecht + return data +} +``` + +**Schnittstellen definieren:** + +```typescript +interface WindowOptions { + title: string + width: number + height: number +} + +function createWindow(options: WindowOptions): void { + // ... +} +``` + +## Commit-Nachrichten-Format + +Verwenden Sie [Conventional Commits](https://www.conventionalcommits.org/): + +``` +(): + + + +