How vslavik/winsparkle works
1. What this repo is
WinSparkle is a Windows auto-update library, not an application. The core deliverable is a WinSparkle.dll that hosts embed into their own desktop apps. The repo also includes a small command-line signing tool, example host apps, language bindings, and packaging/build files.
2. Public integration boundary
The main external API is the C header in include/winsparkle.h, plus version metadata in include/winsparkle-version.h. Host applications link against the DLL and configure it with their update feed URL, app identity, and cryptographic public key. The readme highlights two key integration modes for the public key: a Windows resource or a runtime API call.
3. Update lifecycle and control flow
The runtime path is centered in src/appcontroller.cpp. It coordinates the update check flow: read settings, fetch the appcast, decide whether a newer release exists, verify it, and then hand off to download/UI. This is the architectural “spine” of the library.
4. Feed retrieval and release discovery
src/updatechecker.cpp, src/download.cpp, and src/appcast.cpp handle the network-facing part of the system. The appcast is the update manifest format, compatible with Sparkle, and contains the release metadata plus a signed download enclosure. The data flow is: update URL → appcast fetch → XML parse → candidate release selection.
5. Manifest parsing
src/appcast.* is the boundary between the raw XML feed and internal update records. It extracts release fields, enclosure information, and signature attributes from the appcast format. Expat appears in 3rdparty/expat, indicating XML parsing is a deliberate external dependency rather than ad hoc string processing.
6. Security and signature verification
src/signatureverifier.cpp is the security gate before any installer is trusted. The readme says WinSparkle supports modern EdDSA/Ed25519 signatures and legacy DSA signatures for compatibility. Crypto dependencies are bundled under 3rdparty/ed25519, 3rdparty/openssl, and related build files, showing that verification is a first-class subsystem rather than a helper.
7. Download and install handoff
src/updatedownloader.cpp and src/download.cpp are responsible for fetching the update payload after a release is accepted. The library does not itself perform the application upgrade logic; instead it downloads the installer and then delegates user-facing install/launch behavior to the host/runtime contract.
8. User interaction layer
src/ui.cpp is the visible update experience: prompts, progress, and decision dialogs. The repo includes 3rdparty/wxWidgets, and the translations directory strongly suggests the UI is built on wxWidgets and localized through gettext-style .po files. This is a separate presentation boundary from the update-checking logic.
9. Settings, persistence, and runtime state
src/settings.cpp stores library configuration and user/update-check state. This is where the library remembers things like update frequency, deferred choices, or other preferences across launches. It acts as the persistence boundary between the host app and the update engine.
10. DLL and Windows-specific entry points
src/dll_api.cpp and src/dllmain.cpp are the Windows DLL-facing layers, wiring exported functions and process attach/detach behavior. The src/winsparkle.rc resource file and translations/translations.rc suggest Windows resource embedding is used for versioning, branding, and localization.
11. Threading and concurrency
src/threads.cpp indicates background work is separated from the host UI thread. That matters architecturally because update checks and downloads are asynchronous operations that should not block the application’s main message loop.
12. Tooling and signing companion
tools/winsparkle-tool.cpp builds a separate CLI used to generate EdDSA keys and sign update binaries. This is a distinct utility boundary: the application runtime consumes signed update metadata, while the tool produces the signatures offline. The bin/legacy_*.bat scripts preserve older DSA workflows.
13. Example hosts and bindings
examples/psdk and examples/qt show how different host-app UI stacks integrate the library. pascal/ contains Delphi/Lazarus bindings, and the README references .NET, Python, and Go bindings maintained externally. These are integration surfaces, not part of the core update engine.
14. Build, packaging, and distribution
The project supports Visual Studio solution/project files at the root, NuGet packaging in nuget/, and an “unsupported” CMake path under cmake/. CI is handled by GitHub Actions (.github/workflows/build.yml and translation checks). Third-party dependencies are vendored under 3rdparty/ and wired into the build, which makes the repo self-contained for Windows builds.
15. External dependencies and services
The update payload comes from an appcast hosted elsewhere on the internet, and translations are synced through Crowdin (crowdin.yml). The library itself depends materially on wxWidgets for UI, Expat for XML, and OpenSSL/Ed25519 for crypto, but the app’s actual installer/update distribution remains external to this repo.
Main entry points: appcontroller.cpp Controller · winsparkle.h Public API · CMakeLists.txt CMake build · appcast.cpp Appcast parse
Components 25
Core runtime
Library runtime that checks for updates, verifies releases, downloads installers, and coordinates UI.
- Settings · Persistent configuration and update-check state.
src/settings.cpp - Controller · Coordinates the end-to-end update lifecycle.
src/appcontroller.cpp - Check updates · Starts update checks and orchestrates appcast retrieval.
src/updatechecker.cpp - Appcast parse · Parses update manifest XML into release records.
src/appcast.cpp - Verify sig · Validates release signatures before trust or install.
src/signatureverifier.cpp - Download · Retrieves update payloads from the release enclosure.
src/download.cpp - Installer handoff · Manages post-acceptance download and install transition.
src/updatedownloader.cpp - Update UI · Dialogs, prompts, and progress UI shown to the user.
src/ui.cpp - Background work · Runs update activity off the host UI thread.
src/threads.cpp
Public surface
Headers, DLL entry points, and host integration points exposed to applications.
- Public API · Main host-facing API for configuring and driving WinSparkle.
include/winsparkle.h - Version info · Compile-time version metadata exposed to hosts and packaging.
include/winsparkle-version.h - DLL exports · Exported functions that form the Windows DLL boundary.
src/dll_api.cpp - DLL init · Process attach/detach and library initialization hooks.
src/dllmain.cpp
Tooling
Offline signing and packaging utilities.
- Signing tool · Generates keys and signs update binaries offline.
tools/winsparkle-tool.cpp
Examples and bindings
Sample hosts and language bindings showing integration patterns.
- PSDK example · Native Windows example showing host integration.
examples/psdk/app_psdk.c - Qt example · Qt-based example demonstrating GUI integration.
examples/qt/main.cpp - Pascal bindings · Delphi/Lazarus bindings for integrating the library.
pascal/winsparkle.pas
Bundled deps
Vendored third-party libraries used by the core runtime and tooling.
- wxWidgets · Third-party GUI toolkit used by the user interaction layer.
3rdparty/wxWidgets - Expat · XML parsing dependency used for appcast handling.
3rdparty/expat - OpenSSL · Bundled crypto dependency supporting legacy verification paths.
3rdparty/openssl - Ed25519 · Bundled modern signature implementation for update verification.
3rdparty/ed25519
Build and release
Project files, packaging manifests, CI, and localization assets.
- VS solution · Primary Visual Studio build entry point.
WinSparkle.sln - CMake build · Alternative CMake build and packaging path.
cmake/CMakeLists.txt - NuGet package · NuGet packaging metadata for consumers.
nuget/WinSparkle.nuspec - Translations · Localized UI strings and translation resources.
translations/translations.rc
Connections 29
- Public API → DLL exports: declares · Public API is implemented by exported DLL entry points.
- Version info → NuGet package: versions · Version metadata feeds packaging and distribution identity.
- DLL init → Controller: starts · DLL lifecycle leads into runtime controller setup.
- DLL exports → Settings: configures · Host calls set app identity, feed URL, and keys via the DLL boundary.
- DLL exports → Controller: drives · Exported API triggers the update lifecycle controller.
- Controller → Settings: reads/writes · Controller consults persistent config and update state.
- Controller → Check updates: checks · Controller delegates update discovery to the checker.
- Check updates → Appcast parse: fetches/parses · Update URL is resolved into an appcast manifest and release record.
- Appcast parse → Expat: parses with · XML manifest parsing relies on Expat.
- Appcast parse → Verify sig: provides signature · Parsed enclosure metadata is passed to verification.
- Verify sig → Ed25519: verifies with · Modern signatures use bundled Ed25519 support.
- Verify sig → OpenSSL: verifies with · Legacy compatibility and crypto primitives use OpenSSL.
- Controller → Update UI: prompts · Controller hands accepted updates to visible user interaction.
- Update UI → wxWidgets: built on · UI layer is backed by wxWidgets.
- Controller → Background work: runs on · Background execution keeps update work off the host UI thread.
- Background work → Download: executes · Asynchronous work performs payload retrieval.
- Controller → Installer handoff: handoffs to · Controller delegates install transition after release acceptance.
- Installer handoff → Download: uses · Installer handoff depends on download retrieval.
- Signing tool → Ed25519: produces signatures · CLI tool signs update artifacts for runtime verification.
- Signing tool → OpenSSL: legacy support · Tooling also supports older signing workflows.
- PSDK example → Public API: integrates via · Native sample shows host-side API usage.
- Qt example → Public API: integrates via · Qt sample shows host-side API usage.
- Pascal bindings → Public API: binds to · Pascal bindings wrap the public C API.
- VS solution → Public API: builds · Visual Studio solution builds the core library and public surface.
- CMake build → wxWidgets: configures · CMake path wires third-party dependencies into builds.
- CMake build → Expat: configures · CMake path wires XML dependency into builds.
- CMake build → OpenSSL: configures · CMake path wires crypto dependency into builds.
- NuGet package → Public API: packages · NuGet distribution exposes the public library surface.
- Translations → Update UI: localizes · Translation resources feed the user-facing dialogs.