====== Paketformat (.wvdsx) ====== Ein WvdS Add-in wird als ''.wvdsx''-Datei ausgeliefert. Diese Datei ist ein gewöhnliches ZIP-Archiv mit einer festgelegten inneren Struktur. Der Dateiname folgt dem Schema ''{publisher}.{name}-{version}.wvdsx'', also beispielsweise ''wvds.assets-manager-1.2.0.wvdsx''. Das Format orientiert sich am Prinzip der VSIX-Pakete aus dem VSCode-Ökosystem. Es bündelt alles, was der Host braucht, um ein Add-in zu installieren und zu betreiben: Manifest, Binaries, Medien, Übersetzungen und Dokumentation. Der Benutzer installiert das Paket über die [[cli|Kommandozeile]] oder per Drag-and-Drop in die Erweiterungsverwaltung. Zurück zur [[start|Übersicht]]. ===== ZIP-Struktur ===== wvds.assets-manager-1.2.0.wvdsx │ ├── plugin.json ← Manifest (Pflicht) ├── README.md ← Dokumentation für die Erweiterungsliste ├── CHANGELOG.md ← Änderungshistorie ├── LICENSE ← Lizenzdatei │ ├── bin/ ← Binaries │ ├── AssetsManager.dll ← Haupt-DLL des Add-ins │ ├── libssl-3.dll ← Abhängigkeit (z.B. OpenSSL) │ └── libcrypto-3.dll ← Abhängigkeit │ ├── media/ ← Icons und Grafiken │ ├── asset-open.svg ← Command-Icon │ ├── asset-list.svg ← Command-Icon │ └── navigator.svg ← Sidebar-View-Icon │ ├── themes/ ← Theme-Dateien (optional) │ └── highlight.json ← Skin-Token-Definitionen │ ├── package.nls.json ← Standard-Übersetzung (Fallback) ├── package.nls.de.json ← Deutsche Übersetzung ├── package.nls.en.json ← Englische Übersetzung │ └── data/ ← Beliebige Daten des Add-ins └── templates/ └── default-asset.json ← Vorlagen, Konfigurationen etc. ===== Pflichtdateien ===== Nur eine einzige Datei ist zwingend erforderlich: ''plugin.json''. Ohne dieses [[manifest|Manifest]] kann der Host das Paket nicht interpretieren. Alle anderen Dateien sind optional, werden aber dringend empfohlen. ==== plugin.json ==== Das Manifest liegt im Wurzelverzeichnis des Archivs. Es beschreibt das Add-in vollständig: Identität, Kompatibilität, Aktivierung und Contributions. Der Host liest diese Datei zuerst und entscheidet anhand ihres Inhalts, ob das Add-in installiert werden kann. Das ''main''-Feld im Manifest verweist auf die DLL relativ zum Wurzelverzeichnis des Archivs. Im Beispiel oben wäre der Wert ''"main": "bin/AssetsManager.dll"''. Der Host löst diesen Pfad nach der Installation relativ zum Installationsverzeichnis auf. ==== README.md ==== Die README-Datei wird in der Erweiterungsliste als Detailbeschreibung angezeigt. Sie sollte erklären, was das Add-in tut, welche Voraussetzungen es hat und wie man es konfiguriert. Markdown-Formatierung wird vom Host gerendert. ===== Binaries und Abhängigkeiten ===== Die Haupt-DLL und alle ihre Abhängigkeiten gehören in das ''bin/''-Verzeichnis. Der Host setzt das Arbeitsverzeichnis vor dem Laden auf diesen Pfad, damit Windows die Abhängigkeiten findet. Typische Abhängigkeiten sind Bibliotheken wie OpenSSL, SQLite oder andere native DLLs, die das Add-in zur Laufzeit benötigt. Diese Abhängigkeiten werden im Paket mitgeliefert, nicht auf dem Zielsystem vorausgesetzt. Das stellt sicher, dass das Add-in auf jedem Rechner funktioniert, unabhängig davon, was dort installiert ist. Wichtig: Die DLL muss mit derselben Free Pascal Compiler-Version gebaut werden, die auch der Host verwendet. Der ABI-Handshake (siehe [[architektur|Architektur]]) prüft das automatisch und lehnt inkompatible Binaries ab. ===== Medien ===== Icons und Grafiken für Commands, Toolbar-Buttons und Sidebar-Views gehören in das ''media/''-Verzeichnis. Der Host unterstützt SVG- und PNG-Dateien. SVG wird bevorzugt, weil es bei verschiedenen DPI-Einstellungen scharf bleibt. Die Pfade im Manifest sind relativ zum Paketwurzel, also ''media/asset-open.svg'' und nicht ''./media/asset-open.svg'' oder ein absoluter Pfad. ===== Übersetzungen ===== NLS-Dateien (Natural Language Support) liegen im Wurzelverzeichnis des Pakets. Sie ermöglichen die Übersetzung aller Texte, die im Manifest mit ''%schlüssel%''-Platzhaltern versehen sind. * ''package.nls.json'' — Standard-Übersetzung (Fallback, wenn keine passende Sprache gefunden wird) * ''package.nls.de.json'' — Deutsche Übersetzung * ''package.nls.en.json'' — Englische Übersetzung Der Host wählt die passende Datei anhand der konfigurierten Anwendungssprache aus. Fehlt eine Übersetzung, greift er auf ''package.nls.json'' zurück. Ausführliche Dokumentation zur Mehrsprachigkeit steht unter [[lokalisierung|Lokalisierung]]. ===== Themes ===== Theme-Add-ins (''kind'': ''theme'') oder Add-ins, die zusätzlich zum Code ein eigenes Theme mitbringen, legen ihre Theme-Dateien im ''themes/''-Verzeichnis ab. Der Pfad wird im Manifest unter ''contributes.themes[].path'' referenziert. Theme-Dateien enthalten Farbdefinitionen nach dem [[skin-contract|Skin-Vertrag]]. Sie können die Palette, Tokens, Zustandsfarben und Größen-Properties des Hosts überschreiben. ===== Eigene Daten ===== Das ''data/''-Verzeichnis steht für beliebige Dateien zur Verfügung, die das Add-in zur Laufzeit benötigt: Vorlagen, Standardkonfigurationen, Beispieldaten oder andere Ressourcen. Der Pfad zu diesem Verzeichnis steht dem Add-in über ''IExtensionContext.ExtensionPath'' zur Verfügung. ===== Installation ===== Die Installation eines .wvdsx-Pakets erfolgt über die [[cli|Kommandozeile]]: wdochost --install-extension wvds.assets-manager-1.2.0.wvdsx Der Host führt dabei folgende Schritte durch: - **Entpacken** — Das ZIP-Archiv wird in das Benutzer-Erweiterungsverzeichnis entpackt (''~/.wvdsx/extensions/wvds.assets-manager/''). - **Manifest lesen** — ''plugin.json'' wird geparst und validiert. - **Kompatibilität prüfen** — ''engineVersion'' wird gegen die Host-Version geprüft. - **Prüfsumme verifizieren** — Wenn ''dllChecksum'' gesetzt ist, wird die DLL gehasht und verglichen. - **Registrieren** — Das Add-in wird in die Extension-Registry eingetragen und steht beim nächsten Start zur Verfügung. Die Deinstallation entfernt das Verzeichnis und den Registry-Eintrag: wdochost --uninstall-extension wvds.assets-manager ===== Build-Script ===== Für wiederholbare Builds empfiehlt sich ein ''Build-Wvdsx.ps1''-Script, das Kompilierung und Paketierung automatisiert. Das folgende Muster zeigt die wesentlichen Schritte: # --- 1. Kompilieren --- $buildResult = Invoke-LazbuildProject -ProjectDir $PSScriptRoot if (-not $buildResult) { Write-Error 'Build failed.'; return } # --- 2. Version aus plugin.json lesen --- $manifest = Get-Content (Join-Path $PSScriptRoot 'plugin.json') -Raw | ConvertFrom-Json $version = $manifest.version $packageName = "$($manifest.publisher).$($manifest.name)-$version.wvdsx" # --- 3. Staging-Verzeichnis aufbauen --- $staging = Join-Path $env:TEMP "wvdsx-staging-$(Get-Random)" New-Item -Path $staging -ItemType Directory | Out-Null Copy-Item (Join-Path $PSScriptRoot 'plugin.json') $staging Copy-Item (Join-Path $PSScriptRoot 'package.nls*.json') $staging $binDir = Join-Path $staging 'bin' New-Item -Path $binDir -ItemType Directory | Out-Null Copy-Item $dllPath (Join-Path $binDir 'MyPlugin.dll') # media/, sql/, themes/ etc. nach Bedarf kopieren # --- 4. ZIP erstellen --- $outPath = Join-Path $PSScriptRoot "dist\$packageName" Compress-Archive -Path "$staging\*" -DestinationPath $outPath -Force # --- 5. Prüfsumme ausgeben --- $hash = (Get-FileHash $outPath -Algorithm SHA256).Hash.ToLower() Write-Host "Package: $outPath" Write-Host "SHA256: $hash" # --- 6. Aufräumen --- Remove-Item $staging -Recurse -Force Das erzeugte ''.wvdsx''-Paket kann über die [[cli|Kommandozeile]] installiert oder direkt in das Benutzer-Erweiterungsverzeichnis entpackt werden. ===== Konventionen ===== * Dateinamen im Paket sind durchgehend kleingeschrieben und verwenden Bindestriche als Trennzeichen. * Die Verzeichnisstruktur ist flach gehalten. Verschachtelte Unterverzeichnisse unter ''bin/'' oder ''media/'' sind erlaubt, aber selten nötig. * Keine temporären Dateien, Build-Artefakte oder IDE-Konfigurationen in das Paket aufnehmen. * Das Paket sollte so klein wie möglich gehalten werden. Große Binaries (Datenbanken, vortrainierte Modelle) gehören nicht in das Paket, sondern werden bei Bedarf zur Laufzeit nachgeladen. Weiter zum [[sdk:start|SDK]] oder zurück zur [[start|Übersicht]].