driftwood/CONTRIBUTING.md

Contributing to Driftwood

Building from source

Dependencies

• Rust 1.75+ and Cargo
• GTK 4.16+ development headers (libgtk-4-dev or gtk4-devel)
• libadwaita 1.6+ development headers (libadwaita-1-dev or libadwaita-devel)
• SQLite 3 development headers
• gettext development headers
• glib-compile-resources and glib-compile-schemas (from libglib2.0-dev-bin)

Quick start

git clone https://github.com/driftwood-app/driftwood
cd driftwood
cargo build
cargo run

Running tests

cargo test

Project structure

driftwood/
  Cargo.toml               # Rust package manifest
  build.rs                  # GResource and GSettings compilation
  meson.build               # Meson build system for installation

  src/
    main.rs                 # Entry point, GResource init, CLI dispatch
    application.rs          # GtkApplication subclass, CSS loading, app actions
    window.rs               # Main window, navigation, scanning orchestration
    config.rs               # App ID and version constants
    cli.rs                  # Command-line interface (clap)
    i18n.rs                 # Internationalization (gettext wrappers)

    core/                   # Backend logic (no GTK dependencies)
      database.rs           # SQLite database (rusqlite), all queries
      discovery.rs          # Filesystem scanning, AppImage detection, SHA256
      inspector.rs          # AppImage metadata extraction (icon, desktop entry)
      integrator.rs         # Desktop integration (.desktop files, icons)
      launcher.rs           # AppImage launching with FUSE/sandbox support
      updater.rs            # Update checking and applying (GitHub, zsync)
      fuse.rs               # FUSE status detection
      wayland.rs            # Wayland compatibility analysis
      security.rs           # CVE scanning via OSV.dev API
      duplicates.rs         # Duplicate and multi-version detection
      footprint.rs          # Disk footprint analysis (config/data/cache)
      orphan.rs             # Orphaned desktop entry detection and cleanup

    ui/                     # GTK4/libadwaita UI components
      library_view.rs       # Main grid/list view of AppImages
      app_card.rs           # Individual AppImage card widget
      detail_view.rs        # Full detail page for a single AppImage
      dashboard.rs          # System health dashboard
      preferences.rs        # Preferences dialog
      update_dialog.rs      # Update check and apply dialog
      duplicate_dialog.rs   # Duplicate resolution dialog
      cleanup_wizard.rs     # Disk space reclamation wizard
      security_report.rs    # Security scan results view
      integration_dialog.rs # Desktop integration confirmation
      widgets.rs            # Shared utility widgets (badges, sections)

  data/
    app.driftwood.Driftwood.gschema.xml   # GSettings schema
    app.driftwood.Driftwood.desktop       # Desktop entry for Driftwood itself
    app.driftwood.Driftwood.metainfo.xml  # AppStream metadata
    resources.gresource.xml               # GResource manifest
    resources/style.css                   # Application CSS

  po/                       # Translation files
    POTFILES.in             # Files with translatable strings
    LINGUAS                 # Available translations

  build-aux/                # Build helpers
    app.driftwood.Driftwood.json  # Flatpak manifest
    build-appimage.sh             # AppImage build script

  packaging/
    PKGBUILD                # Arch Linux AUR package

Architecture

The codebase is split into three layers:

1. core/ - Pure Rust business logic. No GTK dependencies. Can be tested independently. Each module handles one concern.

2. ui/ - GTK4/libadwaita widgets. Each view is a function that builds a widget tree. Uses Rc<Database> for shared database access.

3. window.rs / application.rs - Orchestration layer. Connects UI to core, handles navigation, spawns background threads for scanning.

Background work (scanning, update checks, security scans) runs on gio::spawn_blocking threads. Results are sent back to the main thread via glib::spawn_future_local.

Coding conventions

• Follow standard Rust formatting (cargo fmt)
• All new code must compile with zero warnings
• Add tests for core/ modules (81+ tests currently)
• Use log::info!, log::warn!, log::error! for diagnostics
• User-facing strings should be wrapped in i18n() for translation
• Use adw:: widgets over raw gtk:: when an Adwaita equivalent exists
• Status badges use CSS classes: badge-success, badge-warning, badge-error

Database

SQLite database stored at ~/.local/share/driftwood/driftwood.db. Schema migrates automatically (v1 through v4). All queries are in core/database.rs.

Testing

# Run all tests
cargo test

# Run tests for a specific module
cargo test core::database
cargo test core::updater

# Run with output
cargo test -- --nocapture

Tests use Database::open_in_memory() for isolation.