lashman/driftwood
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

Rewrite README with comprehensive feature documentation

Browse Source
This commit is contained in:
lashman
2026-03-01 12:54:55 +02:00
parent 99f60b8529
commit 58d8b44866
1 changed files with 367 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

439
README.md
View File

@@ -1,100 +1,395 @@
# Driftwood
# <img src="https://img.shields.io/badge/CC0-1.0-blue" alt="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.