From 09ef0f48e0e42c3caa7af01163243c56717422bd Mon Sep 17 00:00:00 2001 From: lashman Date: Sun, 1 Mar 2026 13:12:45 +0200 Subject: [PATCH] Rewrite README with better header and project framing --- README.md | 218 ++++++++++++++++++++++++++++++++---------------------- 1 file changed, 130 insertions(+), 88 deletions(-) diff --git a/README.md b/README.md index d6c15cb..a7222d0 100644 --- a/README.md +++ b/README.md @@ -1,36 +1,56 @@ -# License: CC0-1.0 Driftwood +
-### A friendly, modern AppImage manager for Linux desktops +# :evergreen_tree: Driftwood -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. +**Your apps. Your computer. No middleman.** -If you've ever downloaded an AppImage file and wondered "now what do I do with -this?", Driftwood is for you. +A friendly, modern AppImage manager for Linux desktops - +built by the community, owned by no one. + +
+ +![License: CC0-1.0](https://img.shields.io/badge/license-CC0--1.0-bb4444?style=flat-square) +![Built with Rust](https://img.shields.io/badge/built%20with-Rust-d4652a?style=flat-square) +![GTK4 + libadwaita](https://img.shields.io/badge/GTK4-libadwaita-4a86cf?style=flat-square) +![WCAG 2.2 AAA](https://img.shields.io/badge/WCAG%202.2-AAA-228833?style=flat-square) +![No Telemetry](https://img.shields.io/badge/telemetry-none-778899?style=flat-square) + +
+ +*No accounts. No tracking. No data harvested. No profit motive.* +*Just a tool that helps you manage your apps, and gets out of the way.* + +
--- ## :sparkles: What is Driftwood? **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. +Linux applications that come as a single file - no installation needed, no +package manager required, no root access, no corporate app store standing between +you and the software you want to run. -Driftwood handles all of that for you with a clean, easy-to-use interface. +But managing AppImages by hand can be confusing. Making them show up in your app +menu, checking for updates, knowing if they're safe - that's a lot of work, +especially if you're new to Linux. + +Driftwood handles all of that for you with a clean, easy-to-use interface. It +runs entirely on your machine - nothing is sent anywhere, nothing is collected, +nothing is monetized. --- ## :raising_hand: Who is this for? -- **New Linux users** who want a simple way to manage AppImage apps +- **People new to Linux** who want a simple, welcoming way to manage their 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 + integrated into their desktop without friction +- **People who care about privacy** and want to know exactly what their apps + contain and whether any bundled libraries have known security issues +- **People who believe software should be accessible to everyone** - Driftwood + meets WCAG 2.2 AAA accessibility standards +- **Power users** who want a full command-line interface alongside the GUI --- @@ -42,7 +62,7 @@ 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 | +| **Catalog** | Browse and discover new AppImage apps from the community | | **Updates** | See which apps have newer versions and update them | Click any app to see its full details - version info, security status, disk @@ -57,30 +77,31 @@ usage, screenshots, and more. - **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 + list - whichever you prefer - **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) +### :globe_with_meridians: App Catalog -- **Browse apps** - Discover AppImage apps from the community catalog +- **Browse community apps** - Discover AppImage apps shared by developers and + communities - no walled garden, no curation fees, no gatekeeping - **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 +- **One-click install** - Download and add apps directly 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 +- **Update all at once** - Or update apps individually, your choice +- **Release notes** - See what changed in each new version before you decide - **Automatic backups** - Optionally save old versions before updating, so you - can go back if something breaks + can roll back if something breaks - **Multiple update sources** - Works with GitHub Releases, GitLab Releases, zsync delta updates, and OCS feeds @@ -92,10 +113,14 @@ usage, screenshots, and more. - **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 +- **Fully reversible** - Remove any app from your menu just as easily as you + added it. Every change Driftwood makes to your system is tracked and can be + undone ### :shield: Security +Your apps shouldn't be a black box. Driftwood helps you see what's inside. + - **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 @@ -113,35 +138,35 @@ usage, screenshots, and more. - **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 + command for your distribution - no searching forums, no guesswork - **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 + AppImages directly - you're never locked out of your own software ### :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 + or different versions taking up space, and shows how much you'd save - **Disk footprint** - Shows config, cache, and data folders each app has created - on your system + on your system - no hidden clutter - **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 +### :bar_chart: Dashboard -- **System overview** - Quick health check showing FUSE status, Wayland status, +- **System overview** - A 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 +- **At-a-glance stats** - Everything about your AppImage setup in one place ### :gear: Preferences -- **Appearance** - Follow your system's light/dark theme, or force one +- **Appearance** - Follow your system's light/dark theme, or pick one - **Scan directories** - Choose which folders Driftwood watches for AppImages - **Update settings** - Configure automatic update checking, backup behavior, - and retention periods + and how long to keep old versions - **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 @@ -149,26 +174,31 @@ usage, screenshots, and more. ### :lock: Sandboxing -- **Firejail support** - Launch apps inside a Firejail sandbox for extra security +- **Firejail support** - Launch apps inside a Firejail sandbox for extra + isolation - **Per-app profiles** - Each app can have its own sandbox configuration - **Profile management** - Use local, community, or default Firejail profiles -### :accessibility: Accessibility +### :wheelchair: Accessibility -Driftwood is built to meet WCAG 2.2 AAA accessibility standards: +Software that only works for some people doesn't really work. Driftwood is built +to meet WCAG 2.2 AAA accessibility standards: -- **Full keyboard navigation** - Every feature is reachable without a mouse +- **Full keyboard navigation** - Every single 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 +- **Focus management** - Clear, visible focus indicators (3px outlines) on all + interactive elements +- **44px minimum target sizes** - All buttons meet the AAA touch/click 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 +- **No timing requirements** - Nothing in the app requires fast reactions or + races against a clock - **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 + are all properly marked up for assistive technology +- **Automated testing** - Ships with an AT-SPI audit tool that walks the live accessibility tree and checks for violations ### :keyboard: Keyboard Shortcuts @@ -189,7 +219,8 @@ Driftwood is built to meet WCAG 2.2 AAA accessibility standards: ### :desktop_computer: Command Line Interface -Every feature is also available from the terminal: +Every feature is also available from the terminal. The GUI and CLI share the same +database, so they always stay in sync. ```sh driftwood scan # Find AppImages in your configured folders @@ -227,27 +258,27 @@ 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. +Driftwood works on any Linux distribution that has GTK 4.16+ and libadwaita 1.6+. +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 | +| **Ubuntu 24.04+** | :white_check_mark: Works | GTK4 and libadwaita in default repos | +| **Fedora 40+** | :white_check_mark: Works | Excellent GTK4 support out of the box | +| **Arch Linux** | :white_check_mark: Works | Rolling release, always has the latest | +| **Manjaro** | :white_check_mark: Works | Same packages as Arch | +| **openSUSE Tumbleweed** | :white_check_mark: Works | Rolling release with current GTK4 | +| **Debian Testing/Sid** | :white_check_mark: Works | Stable may have older GTK versions | +| **Linux Mint 22+** | :white_check_mark: Works | Based on Ubuntu 24.04 | +| **Pop!_OS 24.04+** | :white_check_mark: Works | Based on Ubuntu | +| **elementary OS 8+** | :white_check_mark: Works | GTK4-based Pantheon desktop | +| **Gentoo** | :white_check_mark: Works | Build from source | +| **Alpine** | :white_check_mark: Works | GTK4 in community repos | +| **NixOS** | :white_check_mark: Works | Package GTK4 + libadwaita via Nix | **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 +that supports GTK4 applications (KDE Plasma, Cinnamon, XFCE, Budgie, Sway, etc.). +It looks best on GNOME and GNOME-based desktops because it uses libadwaita for styling. --- @@ -260,32 +291,31 @@ styling. |------------|---------|-----------| | **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) | +| **SQLite** | 3 | A small, local 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) | +| **libfuse2** or **libfuse3** | Lets AppImages mount themselves (most AppImages need this to run) | +| **firejail** | Runs apps in a security sandbox for extra isolation | +| **appimageupdate** | Enables fast delta updates (downloads only what changed, not the whole file) | ### 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) | +| **Meson** | Build system (only 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`). +> Package names vary between distributions. On Fedora, use `-devel` instead +> of `-dev` (for example, `gtk4-devel` instead of `libgtk-4-dev`). On Arch, +> the packages are `gtk4`, `libadwaita`, and `sqlite`. --- @@ -314,50 +344,56 @@ After installing, Driftwood will appear in your application menu. ## :package: Packaging -Ready-made packaging files are included: +Packaging files are included so anyone can build packages for their distribution: | 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 | +| **AppImage** | `packaging/build-appimage.sh` | Build script | + +If you package Driftwood for a distribution not listed here, let us know - we'd +love to include it. --- -## :open_file_folder: Where Driftwood stores things +## :open_file_folder: Where Driftwood Stores Things + +Driftwood keeps everything local. Nothing leaves your machine. | What | Location | |------|----------| | App database | `~/.local/share/driftwood/driftwood.db` | | Cached icons | `~/.local/share/driftwood/icons/` | -| Desktop entries it creates | `~/.local/share/applications/driftwood-*.desktop` | +| Desktop entries | `~/.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. +Every modification Driftwood makes to your system is recorded in its database. +You can undo all of it at any time with `driftwood purge` or through the UI. +Your system, your rules. --- ## :test_tube: Accessibility Testing -Driftwood includes an automated accessibility audit tool that uses AT-SPI (the +Driftwood ships with 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 -# Run the full AAA-level audit (builds and launches the app automatically) +# Full AAA-level audit (builds and launches automatically) python3 tools/a11y-audit.py --level aaa # Attach to an already-running instance python3 tools/a11y-audit.py --no-launch --level aaa -# Run at AA level only +# AA level only python3 tools/a11y-audit.py --level aa -# Show detailed live region inventory +# Verbose output with live region inventory python3 tools/a11y-audit.py --level aaa --verbose ``` @@ -378,18 +414,24 @@ integration. --- -## :handshake: Contributing +## :raised_hands: Contributing + +Driftwood is a community project. There's no company behind it, no investors, +no roadmap driven by profit - just people building something useful together. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines on how to contribute code, -translations, or bug reports. +translations, bug reports, or ideas. Every contribution matters, and everyone +who helps is a co-owner of this project. --- ## :page_facing_up: License -**CC0-1.0 (Public Domain)** +**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. +Driftwood belongs to everyone. It is released into the public domain under the +[CC0 1.0 Universal](LICENSE) license. You can copy, modify, distribute, and use +it for any purpose - personal, educational, commercial, anything - without +asking permission, without paying anyone, without restrictions. + +Knowledge and tools should be shared freely. This is ours, and it's yours.