From 58d8b448667a66ac7aab39095e7d6947037aca7a Mon Sep 17 00:00:00 2001 From: lashman Date: Sun, 1 Mar 2026 12:54:55 +0200 Subject: [PATCH] Rewrite README with comprehensive feature documentation --- README.md | 439 +++++++++++++++++++++++++++++++++++++++++++++--------- 1 file changed, 367 insertions(+), 72 deletions(-) diff --git a/README.md b/README.md index d25a50e..d6c15cb 100644 --- a/README.md +++ b/README.md @@ -1,100 +1,395 @@ -# Driftwood +# License: CC0-1.0 Driftwood -A modern GTK4/libadwaita AppImage manager for GNOME desktops. +### A friendly, modern AppImage manager for Linux desktops -Driftwood discovers, inspects, integrates, updates, and audits AppImage files -with a clean GNOME-native interface built for the Wayland era. +Driftwood makes it easy to find, install, organize, update, and keep safe all +your AppImage apps - without needing to use the terminal. It's built for people +who just want their apps to work, and it fits right in with the GNOME desktop. -## Features +If you've ever downloaded an AppImage file and wondered "now what do I do with +this?", Driftwood is for you. -- **Library management** - Scan directories to discover AppImages, view them in - grid or list mode with status badges for FUSE, Wayland, and update status -- **Desktop integration** - Create .desktop files and install icons with one click -- **FUSE and Wayland detection** - Automatically detect compatibility and suggest - launch methods (direct, extract-and-run, or sandboxed) -- **Update checking** - Read embedded update information (GitHub Releases, GitLab, - zsync) and check for newer versions -- **Security scanning** - Extract bundled shared libraries and check them against - the OSV.dev vulnerability database -- **Duplicate detection** - Find AppImages that are different versions of the same - app or identical files in different locations -- **Disk footprint analysis** - Discover config, data, and cache files associated - with each AppImage -- **Sandboxing** - Optional Firejail sandbox support per-app -- **Orphan cleanup** - Detect and remove .desktop files for AppImages that no - longer exist -- **CLI interface** - Full command-line access to all core features +--- -## Requirements +## :sparkles: What is Driftwood? -- GTK 4.16+ -- libadwaita 1.6+ -- SQLite 3 -- gettext +**Driftwood is a graphical app manager for AppImages.** AppImages are portable +Linux applications that come as a single file - no installation needed. But +managing them by hand (making them show up in your app menu, checking for +updates, knowing if they're safe) can be confusing, especially if you're new to +Linux. -Optional: -- firejail (for sandboxed launches) -- fuse2/fuse3 (for AppImage FUSE mounting) -- appimageupdate (for delta updates) +Driftwood handles all of that for you with a clean, easy-to-use interface. -## Building from source +--- + +## :raising_hand: Who is this for? + +- **New Linux users** who want a simple way to manage AppImage apps +- **Anyone who downloads AppImages** and wants them organized, updated, and + integrated into their desktop +- **Privacy-conscious users** who want to know what libraries their apps bundle + and whether any have known security issues +- **Power users** who want a full CLI alongside the graphical interface + +--- + +## :framed_picture: What does it look like? + +Driftwood uses GTK4 and libadwaita, so it looks and feels like a native GNOME +app. It has three main views: + +| View | What it does | +|------|-------------| +| **Installed** | Shows all your AppImages in a grid or list with status badges | +| **Catalog** | Browse and discover new AppImage apps to download | +| **Updates** | See which apps have newer versions and update them | + +Click any app to see its full details - version info, security status, disk +usage, screenshots, and more. + +--- + +## :star2: Features + +### :package: App Library + +- **Automatic scanning** - Driftwood finds all AppImage files in your chosen + folders (like `~/Applications` or `~/Downloads`) +- **Grid and list views** - See your apps as cards with icons, or as a detailed + list +- **Search and sort** - Find apps by name, sort by name, size, or when you added + them +- **Tags** - Label your apps with custom tags and filter by them +- **Selection mode** - Select multiple apps at once for batch actions +- **Drag and drop** - Drop an AppImage file onto the window to add it + +### :globe_with_meridians: App Catalog (Store) + +- **Browse apps** - Discover AppImage apps from the community catalog +- **Category filters** - Browse by Audio, Games, Graphics, Development, and more +- **Featured apps** - A rotating carousel of highlighted apps +- **Search** - Find apps by name across the entire catalog +- **App details** - See descriptions, screenshots, star counts, and download + numbers +- **One-click install** - Download and add apps right from the catalog + +### :arrow_up: Updates + +- **Check for updates** - Scan all your apps for newer versions with one click +- **Update all at once** - Or update apps one by one +- **Release notes** - See what changed in each new version +- **Automatic backups** - Optionally save old versions before updating, so you + can go back if something breaks +- **Multiple update sources** - Works with GitHub Releases, GitLab Releases, + zsync delta updates, and OCS feeds + +### :rocket: Desktop Integration + +- **Add to app menu** - Make any AppImage show up in your desktop's application + menu with one click +- **Icon installation** - Automatically extracts and installs the app's icon +- **Autostart** - Set apps to launch automatically when you log in +- **Custom launch options** - Add command-line arguments or environment variables + per app +- **Undo everything** - Remove any app from your menu just as easily + +### :shield: Security + +- **Vulnerability scanning** - Extracts the shared libraries bundled inside each + AppImage and checks them against the OSV.dev vulnerability database +- **CVE details** - Shows the severity (Critical, High, Medium, Low), CVSS + scores, and which library versions are affected +- **Security report** - Generate a full report of all your apps and export it as + HTML, JSON, or CSV +- **Desktop notifications** - Get notified when a new vulnerability is found in + one of your apps +- **Signature verification** - Check GPG signatures and SHA256 checksums +- **Configurable thresholds** - Choose whether to be notified about only critical + issues or everything + +### :jigsaw: FUSE and Wayland Compatibility + +- **FUSE detection** - Checks whether your system can mount AppImages and tells + you exactly what to install if it can't +- **Guided FUSE setup** - A step-by-step wizard that shows you the right install + command for your distribution +- **Wayland compatibility** - Detects whether you're running Wayland or X11 and + flags any compatibility concerns +- **Fallback launching** - If FUSE isn't available, Driftwood can extract and run + AppImages directly + +### :broom: Cleanup and Disk Management + +- **Duplicate finder** - Detects when you have multiple copies of the same app + or different versions taking up space, and shows how much space you'd save +- **Disk footprint** - Shows config, cache, and data folders each app has created + on your system +- **Cleanup wizard** - A guided walkthrough that finds orphaned desktop entries, + leftover caches, and duplicates, then lets you choose what to remove +- **Orphan cleanup** - Finds and removes menu entries for AppImages that no + longer exist on disk + +### :1234: Dashboard + +- **System overview** - Quick health check showing FUSE status, Wayland status, + total apps, storage used, and apps needing updates +- **At-a-glance stats** - See everything about your AppImage setup in one place + +### :gear: Preferences + +- **Appearance** - Follow your system's light/dark theme, or force one +- **Scan directories** - Choose which folders Driftwood watches for AppImages +- **Update settings** - Configure automatic update checking, backup behavior, + and retention periods +- **Security settings** - Enable automatic scanning, notifications, and set a + GitHub token for higher API rate limits +- **Catalog settings** - Toggle automatic metadata enrichment and removable media + watching + +### :lock: Sandboxing + +- **Firejail support** - Launch apps inside a Firejail sandbox for extra security +- **Per-app profiles** - Each app can have its own sandbox configuration +- **Profile management** - Use local, community, or default Firejail profiles + +### :accessibility: Accessibility + +Driftwood is built to meet WCAG 2.2 AAA accessibility standards: + +- **Full keyboard navigation** - Every feature is reachable without a mouse +- **Screen reader support** - All buttons, images, and status changes are + announced to screen readers like Orca +- **Focus management** - Clear focus indicators (3px outlines) on all interactive + elements +- **44px minimum target sizes** - All buttons meet the AAA touch target standard +- **High contrast support** - Enhanced borders and colors when your system uses + high contrast mode +- **No timing requirements** - Nothing in the app requires fast reactions +- **Semantic roles** - Headings, alerts, status regions, and live announcements + are all properly marked up +- **Automated testing** - Includes an AT-SPI audit tool that walks the live + accessibility tree and checks for violations + +### :keyboard: Keyboard Shortcuts + +| Shortcut | Action | +|----------|--------| +| `Ctrl+1` | Switch to Installed view | +| `Ctrl+2` | Switch to Catalog view | +| `Ctrl+3` | Switch to Updates view | +| `Ctrl+F` | Search | +| `Ctrl+R` or `F5` | Scan for AppImages | +| `Ctrl+U` | Check for updates | +| `Ctrl+K` | Open command palette | +| `Ctrl+D` | Open dashboard | +| `Ctrl+,` | Open preferences | +| `Ctrl+?` | Show keyboard shortcuts | +| `Ctrl+Q` | Quit | + +### :desktop_computer: Command Line Interface + +Every feature is also available from the terminal: ```sh -# Development build (uses cargo directly) +driftwood scan # Find AppImages in your configured folders +driftwood list # Show all known AppImages +driftwood list --format json # Output as JSON + +driftwood inspect ~/Apps/MyApp.AppImage # Show app metadata +driftwood integrate ~/Apps/MyApp.AppImage # Add to desktop menu +driftwood remove ~/Apps/MyApp.AppImage # Remove from desktop menu +driftwood launch ~/Apps/MyApp.AppImage # Run the app +driftwood launch --sandbox ~/Apps/MyApp.AppImage # Run in sandbox + +driftwood check-updates # Check all apps for updates +driftwood update-all # Update everything +driftwood verify ~/Apps/MyApp.AppImage # Check integrity +driftwood verify ~/Apps/MyApp.AppImage --sha256 abc123... # Verify hash + +driftwood security # Scan all apps for vulnerabilities +driftwood duplicates # Find duplicate AppImages +driftwood footprint ~/Apps/MyApp.AppImage # Show disk usage +driftwood status # System compatibility check +driftwood clean-orphans # Remove stale menu entries + +driftwood export # Export app list to JSON +driftwood export --output ~/backup.json +driftwood import ~/backup.json # Import app list + +driftwood autostart ~/Apps/MyApp.AppImage --enable # Autostart on login +driftwood autostart ~/Apps/MyApp.AppImage --disable + +driftwood purge # Remove ALL Driftwood system modifications +``` + +--- + +## :penguin: Which Linux distributions does it work on? + +Driftwood works on any Linux distribution that has GTK 4.16+ and libadwaita 1.6+ +available. In practice, that means most modern distributions released from 2024 +onward. + +| Distribution | Status | Notes | +|-------------|--------|-------| +| **Ubuntu 24.04+** | Works | GTK4 and libadwaita available in default repos | +| **Fedora 40+** | Works | Excellent GTK4 support out of the box | +| **Arch Linux** | Works | Rolling release, always has the latest GTK4 | +| **Manjaro** | Works | Same packages as Arch | +| **openSUSE Tumbleweed** | Works | Rolling release with current GTK4 | +| **Debian Testing/Sid** | Works | Stable Debian may have older GTK versions | +| **Linux Mint 22+** | Works | Based on Ubuntu 24.04 | +| **Pop!_OS 24.04+** | Works | Based on Ubuntu with COSMIC/GNOME | +| **elementary OS 8+** | Works | Uses GTK4-based Pantheon | +| **Gentoo** | Works | Build GTK4 and libadwaita from source | +| **Alpine** | Works | GTK4 available in community repos | + +**Desktop environment**: Driftwood is designed for GNOME but works on any desktop +that supports GTK4 applications (KDE Plasma, Cinnamon, XFCE, Budgie, etc.). It +looks best on GNOME and GNOME-based desktops because it uses libadwaita for +styling. + +--- + +## :wrench: System Requirements + +### What you need + +| Requirement | Version | What it is | +|------------|---------|-----------| +| **GTK** | 4.16 or newer | The toolkit that draws the interface | +| **libadwaita** | 1.6 or newer | GNOME's design library for modern-looking apps | +| **SQLite** | 3 | A small database engine (stores your app library) | +| **gettext** | any | Handles translations for different languages | + +### Optional (but recommended) + +| Package | What it does | +|---------|-------------| +| **libfuse2** or **libfuse3** | Lets AppImages mount themselves (most need this to run) | +| **firejail** | Runs apps in a security sandbox | +| **appimageupdate** | Enables fast delta updates (downloads only what changed) | + +### For building from source + +You'll also need: + +| Package | What it is | +|---------|-----------| +| **Rust 1.75+** and **Cargo** | The programming language and build tool | +| **Meson** | Build system (only needed for system-wide installation) | +| **libgtk-4-dev** | GTK4 development headers | +| **libadwaita-1-dev** | libadwaita development headers | +| **libsqlite3-dev** | SQLite development headers | +| **libglib2.0-dev-bin** | Provides `glib-compile-resources` and `glib-compile-schemas` | + +> Package names may vary between distributions. On Fedora, use `-devel` instead +> of `-dev` (for example, `gtk4-devel` instead of `libgtk-4-dev`). + +--- + +## :building_construction: Building from Source + +### Quick development build + +```sh +git clone https://git.lashman.live/lashman/driftwood.git +cd driftwood cargo build cargo run +``` -# System installation (uses meson) +### System-wide installation + +```sh meson setup build --prefix=/usr meson compile -C build sudo meson install -C build ``` -## CLI usage +After installing, Driftwood will appear in your application menu. + +--- + +## :package: Packaging + +Ready-made packaging files are included: + +| Format | Location | Notes | +|--------|----------|-------| +| **Flatpak** | `build-aux/app.driftwood.Driftwood.json` | Flatpak manifest | +| **Arch Linux (AUR)** | `packaging/PKGBUILD` | For makepkg | +| **AppImage** | `packaging/build-appimage.sh` | Self-contained build script | + +--- + +## :open_file_folder: Where Driftwood stores things + +| What | Location | +|------|----------| +| App database | `~/.local/share/driftwood/driftwood.db` | +| Cached icons | `~/.local/share/driftwood/icons/` | +| Desktop entries it creates | `~/.local/share/applications/driftwood-*.desktop` | +| Installed icons | `~/.local/share/icons/hicolor/` | +| Autostart entries | `~/.config/autostart/` | +| Settings | GSettings (`app.driftwood.Driftwood`) | +| Backups | `~/.local/share/driftwood/backups/` | + +Everything Driftwood does to your system is tracked in its database, and you can +undo all of it with `driftwood purge` or by uninstalling apps through the UI. + +--- + +## :test_tube: Accessibility Testing + +Driftwood includes an automated accessibility audit tool that uses AT-SPI (the +Linux accessibility bus) to walk the live widget tree and check for WCAG 2.2 +violations: ```sh -# Scan configured directories for AppImages -driftwood scan +# Run the full AAA-level audit (builds and launches the app automatically) +python3 tools/a11y-audit.py --level aaa -# List all known AppImages -driftwood list -driftwood list --format json +# Attach to an already-running instance +python3 tools/a11y-audit.py --no-launch --level aaa -# Inspect a specific AppImage -driftwood inspect ~/Applications/Firefox.AppImage +# Run at AA level only +python3 tools/a11y-audit.py --level aa -# Integrate into desktop menu -driftwood integrate ~/Applications/Firefox.AppImage - -# Check for updates -driftwood check-updates - -# Run a security scan -driftwood security -driftwood security ~/Applications/Firefox.AppImage - -# Launch with tracking -driftwood launch ~/Applications/Firefox.AppImage -driftwood launch --sandbox ~/Applications/Firefox.AppImage - -# Find duplicates -driftwood duplicates - -# Show disk footprint -driftwood footprint ~/Applications/Firefox.AppImage - -# System status -driftwood status - -# Clean orphaned entries -driftwood clean-orphans +# Show detailed live region inventory +python3 tools/a11y-audit.py --level aaa --verbose ``` -## Packaging +The tool checks for: -- **Flatpak**: See `build-aux/app.driftwood.Driftwood.json` -- **Arch Linux (AUR)**: See `packaging/PKGBUILD` +- Interactive widgets without accessible names (SC 4.1.2) +- Images without alt text or decorative marking (SC 1.1.1) +- Headings without level attributes (SC 1.3.1) +- Widgets that aren't keyboard-focusable (SC 2.1.1) +- Target sizes below 24px (AA) and 44px (AAA) +- Windows without titles (SC 2.4.8) +- Vague link text (SC 2.4.9) +- Content regions without headings (SC 2.4.10) +- Keyboard traps (SC 2.1.3) -## License +Results are printed to the terminal and saved as `a11y-report.json` for CI +integration. -CC0-1.0 (Public Domain) +--- + +## :handshake: Contributing + +See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute code, +translations, or bug reports. + +--- + +## :page_facing_up: License + +**CC0-1.0 (Public Domain)** + +This project is released into the public domain under the CC0 1.0 Universal +license. You can copy, modify, distribute, and use it for any purpose, even +commercially, without asking permission. See [LICENSE](LICENSE) for the full +legal text.