feat: Phase 3 - Better error handling and documentation (#160)

Add better error messages and documentation for cross-distribution compatibility.

**Task 9: System Dependency Checker (scripts/check-system-deps.sh)**
- New script to check system dependencies regardless of distribution
- Detects Python 3.8+, pkg-config, GTK3, PyGObject, PortAudio
- Checks for text injection tools (xdotool, wtype, ydotool)
- Provides distribution-specific installation instructions
- Supports all 10+ distribution families (Ubuntu, Debian, Fedora, Arch, openSUSE, Gentoo, Alpine, Void, Solus, Mageia)

**Task 10: Better Unsupported Distro Message (install.sh)**
- Enhanced error message for unsupported distributions
- References the new dependency checker script
- Provides manual installation options (skip-system-deps, venv install)
- Includes link to project wiki
- Interactive prompt to continue or cancel

**Task 11: Distro Compatibility Documentation (docs/DISTRO_COMPATIBILITY.md)**
- Comprehensive compatibility matrix for supported distros
- Experimental support section with known issues
- Requirements by distribution with exact commands
- Desktop environment compatibility (GNOME, KDE, Xfce, sway, i3, etc.)
- Display server support (X11, Wayland, XWayland)
- Architecture support (x86_64, arm64, armhf, riscv64)
- Testing checklist for new distributions
- Issue reporting guidelines
- Contributing guidelines for compatibility fixes

Part of cross-distribution compatibility improvements (Phase 3 of 5).
Related to #157
This commit is contained in:
Jatin K Malik
2026-02-07 16:50:50 -08:00
committed by GitHub
parent f2e13bbcba
commit 461400b3bc
3 changed files with 457 additions and 8 deletions
+267
View File
@@ -0,0 +1,267 @@
# Linux Distribution Compatibility
## Officially Supported Distributions
These distributions are tested and known to work well with Vocalinux:
| Distribution | Version | Status | Notes |
|--------------|---------|--------|-------|
| Ubuntu | 22.04+ | ✅ Full Support | Primary target, most thoroughly tested |
| Debian | 11+, Testing | ✅ Full Support | Well tested, use Ayatana AppIndicator on Debian 11+ |
| Fedora | 39+ | ✅ Good Support | Uses lib64 paths, fully supported |
| Arch Linux | Rolling | ✅ Good Support | Community tested, rolling release compatible |
| openSUSE | Tumbleweed | ✅ Good Support | Good support with zypper package manager |
## Experimental Support
These distributions may work but have known limitations or are less tested:
| Distribution | Status | Known Issues |
|--------------|--------|--------------|
| Gentoo | ⚠️ Experimental | No package manager support, manual install required. Packages are compiled from source which takes longer. |
| Alpine Linux | ⚠️ Experimental | Uses musl libc (not glibc). Some Python packages may not have pre-built wheels and may need to be compiled. |
| Void Linux | ⚠️ Experimental | Untested, manual install required. Uses xbps package manager. |
| Solus | ⚠️ Experimental | Untested, manual install required. Uses eopkg package manager. |
| Mageia | ⚠️ Experimental | Untested, uses dnf/urpmi package managers. |
| Linux Mint | ✅ Good Support | Based on Ubuntu, inherits Ubuntu compatibility |
| Pop!_OS | ✅ Good Support | Based on Ubuntu, inherits Ubuntu compatibility |
| elementary OS | ✅ Good Support | Based on Ubuntu, inherits Ubuntu compatibility |
| Zorin OS | ✅ Good Support | Based on Ubuntu, inherits Ubuntu compatibility |
| Manjaro | ✅ Good Support | Based on Arch, inherits Arch compatibility |
| EndeavourOS | ✅ Good Support | Based on Arch, inherits Arch compatibility |
## Not Supported
These distributions are known to be incompatible:
| Distribution | Status | Reason |
|--------------|--------|--------|
| NixOS | ❌ Not Supported | Completely different filesystem layout (/nix/store), incompatible with standard installer |
## Requirements by Distribution
### Ubuntu/Debian-based
```bash
sudo apt install -y python3-gi gir1.2-gtk-3.0 gir1.2-gdkpixbuf-2.0 \
portaudio19-dev python3-dev python3-venv pkg-config
```
**Note for Debian 11+:** Use `gir1.2-ayatanaappindicator3-0.1` instead of `gir1.2-appindicator3-0.1`
### Fedora/RHEL-based
```bash
sudo dnf install -y python3-gobject gtk3-devel gobject-introspection-devel \
portaudio-devel python3-devel python3-virtualenv pkg-config
```
### Arch Linux-based
```bash
sudo pacman -S --needed python-gobject gtk3 gobject-introspection \
portaudio python pkg-config
```
### openSUSE
```bash
sudo zypper install -y python3-gobject python3-gobject-cairo gtk3 \
gobject-introspection-devel portaudio-devel python3-devel \
python3-virtualenv pkg-config
```
### Gentoo
```bash
sudo emerge dev-python/pygobject:3 x11-libs/gtk+:3 dev-libs/libappindicator:3 \
media-libs/portaudio dev-lang/python:3.8
```
**Note:** Gentoo compiles packages from source, which will take longer.
### Alpine Linux
```bash
sudo apk add py3-gobject3 py3-pip gtk+3.0 py3-cairo portaudio-dev \
py3-virtualenv pkgconf
```
**Note:** Alpine uses musl libc. Some Python packages may need to be compiled from source.
### Void Linux
```bash
sudo xbps-install -Sy python3-pip python3-gobject gtk+3 libappindicator \
gobject-introspection portaudio-devel python3-devel pkg-config
```
### Solus
```bash
sudo eopkg install python3-pip python3-gobject gtk3 libappindicator \
gobject-introspection-devel portaudio-devel python3-virtualenv pkg-config
```
### Mageia
```bash
sudo dnf install -y python3-gobject gtk3-devel gobject-introspection-devel \
portaudio-devel python3-devel python3-virtualenv pkg-config
# or
sudo urpmi -y python3-gobject gtk3-devel gobject-introspection-devel \
portaudio-devel python3-devel python3-virtualenv pkg-config
```
## Text Injection Tools
Vocalinux requires text injection tools to work with X11 or Wayland:
### For X11
- **xdotool**: Required for X11 sessions
### For Wayland
- **wtype**: Recommended for Wayland native sessions
- **ydotool**: Universal alternative that works with both X11 and Wayland
- **xdotool**: May work via XWayland fallback
### Installation by Distribution
```bash
# Ubuntu/Debian/Fedora/Arch/openSUSE
sudo apt install xdotool wtype # Ubuntu/Debian
sudo dnf install xdotool wtype # Fedora
sudo pacman -S xdotool wtype # Arch
sudo zypper install xdotool wtype # openSUSE
```
## Manual Installation
For unsupported or experimental distributions:
1. **Run the dependency checker:**
```bash
bash scripts/check-system-deps.sh
```
2. **Install missing dependencies** using your package manager based on the checker output
3. **Run the installer with --skip-system-deps:**
```bash
./install.sh --skip-system-deps
```
4. **Or install from source in a virtual environment:**
```bash
python3 -m venv venv
source venv/bin/activate
pip install -e .[whisper]
```
## Desktop Environment Compatibility
| Desktop Environment | Status | Notes |
|---------------------|--------|-------|
| GNOME | ✅ Full Support | Primary target, uses AppIndicator |
| KDE Plasma | ✅ Full Support | Works with AppIndicator |
| Xfce | ✅ Full Support | Works with AppIndicator |
| Cinnamon | ✅ Full Support | Works with AppIndicator |
| MATE | ✅ Full Support | Works with AppIndicator |
| LXQt | ✅ Full Support | Works with AppIndicator |
| sway | ✅ Good Support | Wayland native, uses wtype |
| i3 | ✅ Good Support | X11, uses xdotool |
| Hyprland | ⚠️ Experimental | Wayland, may need wtype configuration |
## Display Server
| Display Server | Status | Notes |
|----------------|--------|-------|
| X11 | ✅ Full Support | Uses xdotool for text injection |
| Wayland | ✅ Full Support | Uses wtype (native) or xdotool (XWayland) |
| XWayland | ✅ Full Support | Automatically detected, falls back to xdotool if needed |
## Architecture Support
| Architecture | Status | Notes |
|--------------|--------|-------|
| x86_64 (AMD64) | ✅ Full Support | Primary target |
| arm64 (AArch64) | ✅ Good Support | Tested on Raspberry Pi, ARM64 servers |
| armhf | ⚠️ Experimental | Limited testing |
| riscv64 | ⚠️ Experimental | Limited testing, may need to compile dependencies |
## Reporting Issues
When reporting issues, please include:
1. **Distribution information:**
```bash
cat /etc/os-release
```
2. **Desktop environment:**
```bash
echo $XDG_CURRENT_DESKTOP
echo $SESSION_TYPE
```
3. **Dependency checker output:**
```bash
bash scripts/check-system-deps.sh
```
4. **Python version:**
```bash
python3 --version
```
5. **Error messages or logs:**
- Any error messages from the installer
- Output from running `vocalinux-gui` from terminal
- Relevant journal logs if applicable
6. **Steps to reproduce:**
- What you were trying to do
- What happened instead
- Expected behavior
## Testing Checklist
Use this checklist when testing on a new distribution:
### Pre-Install
- [ ] Run dependency checker: `bash scripts/check-system-deps.sh`
- [ ] Note missing packages
- [ ] Check desktop environment
- [ ] Check display server (X11/Wayland)
### Installation
- [ ] Run installer: `./install.sh`
- [ ] Check for errors during installation
- [ ] Verify virtual environment was created
- [ ] Check wrapper scripts exist
### Post-Install
- [ ] Launch from terminal: `~/.local/bin/vocalinux-gui`
- [ ] Launch from application menu
- [ ] Verify tray icon appears
- [ ] Test keyboard shortcuts (Ctrl+Alt+M by default)
- [ ] Test audio recording
- [ ] Test text injection in different applications
- [ ] Test Settings dialog opens correctly
- [ ] Test model download if using Whisper
### Known Issues to Watch For
- AppIndicator not showing in tray
- Audio device not detected
- Text injection not working
- Model download failures
- Permission errors with udev/input
## Contributing Compatibility Fixes
If you successfully get Vocalinux working on an unsupported or experimental distribution:
1. Test thoroughly using the checklist above
2. Document any distribution-specific requirements
3. Submit a PR with:
- Distribution detection logic (if needed)
- Package installation commands
- Any patches or workarounds required
- Update to this compatibility document
## See Also
- [Installation Guide](../README.md#installation)
- [Manual Installation](MANUAL_INSTALL.md)
- [Troubleshooting](TROUBLESHOOTING.md)
- [GitHub Issue Tracker](https://github.com/jatinkrmalik/vocalinux/issues)
+25 -8
View File
@@ -779,15 +779,32 @@ install_system_dependencies() {
*)
print_error "Unsupported distribution family: $DISTRO_FAMILY"
print_warning "Please install the following dependencies manually:"
print_warning "- Python 3.8 or newer with pip"
print_warning "- PyGObject (GTK3 bindings for Python)"
print_warning "- GTK3 development libraries"
print_warning "- AppIndicator3 support"
print_warning "- PortAudio development libraries"
print_warning "- Python virtual environment support"
print_info ""
print_info "Your distribution ($DISTRO_NAME) is not officially supported."
print_info "However, you can still install Vocalinux manually:"
print_info ""
print_info "1. Run the dependency checker:"
print_info " bash scripts/check-system-deps.sh"
print_info ""
print_info "2. Install missing dependencies using your package manager"
print_info ""
print_info "3. Run the installer with --skip-system-deps:"
print_info " ./install.sh --skip-system-deps"
print_info ""
print_info "4. Or install from source in a virtual environment:"
print_info " python3 -m venv venv"
print_info " source venv/bin/activate"
print_info " pip install -e .[whisper]"
print_info ""
print_info "For more information, see the project wiki:"
print_info " https://github.com/jatinkrmalik/vocalinux/wiki"
print_info ""
if [[ "$NON_INTERACTIVE" != "yes" ]]; then
read -p "Press Enter to continue once dependencies are installed, or Ctrl+C to cancel..."
read -p "Continue anyway? (y/n) " -n 1 -r
echo
if [[ ! $REPLY =~ ^[Yy]$ ]]; then
exit 1
fi
else
print_info "Non-interactive mode: continuing (dependencies may be missing)..."
fi
+165
View File
@@ -0,0 +1,165 @@
#!/bin/bash
# Check for system dependencies regardless of distro
# Returns helpful error messages with install commands
check_deps() {
MISSING=0
WARNINGS=0
echo "Checking Vocalinux system dependencies..."
echo ""
# Check for Python 3.8+
if command -v python3 >/dev/null 2>&1; then
PY_VERSION=$(python3 -c "import sys; print('.'.join(map(str, sys.version_info[:2])))")
echo "✓ Python $PY_VERSION"
if [ "$(echo "$PY_VERSION" | cut -d. -f1)" -lt 3 ] || \
[ "$(echo "$PY_VERSION" | cut -d. -f2)" -lt 8 ]; then
echo " ✗ Python 3.8+ required, found $PY_VERSION"
MISSING=1
fi
else
echo "✗ Python 3 not found"
MISSING=1
fi
# Check for pip
if command -v pip3 >/dev/null 2>&1; then
echo "✓ pip3"
else
echo "✗ pip3 not found"
MISSING=1
fi
# Check for pkg-config
if command -v pkg-config >/dev/null 2>&1; then
echo "✓ pkg-config"
else
echo "✗ pkg-config not found"
MISSING=1
fi
# Check for GTK3
if command -v pkg-config >/dev/null 2>&1 && pkg-config --exists gtk+-3.0 2>/dev/null; then
GTK_VERSION=$(pkg-config --modversion gtk+-3.0 2>/dev/null)
echo "✓ GTK3 $GTK_VERSION"
else
echo "✗ GTK3 development files not found"
MISSING=1
fi
# Check for PyGObject
if command -v pkg-config >/dev/null 2>&1 && pkg-config --exists gobject-introspection-1.0 2>/dev/null; then
echo "✓ GObject Introspection"
GI_TYPELIB_PATH=$(pkg-config --variable=typelibdir gobject-introspection-1.0 2>/dev/null)
echo " Typelib path: $GI_TYPELIB_PATH"
else
echo "✗ GObject Introspection not found"
MISSING=1
fi
# Check for PortAudio
if command -v pkg-config >/dev/null 2>&1 && pkg-config --exists portaudio-2.0 2>/dev/null; then
PA_VERSION=$(pkg-config --modversion portaudio-2.0 2>/dev/null)
echo "✓ PortAudio $PA_VERSION"
else
echo "⚠ PortAudio development files not found (required for audio)"
MISSING=1
fi
# Check for text injection tools
echo ""
echo "Text injection tools (at least one required):"
if command -v xdotool >/dev/null 2>&1; then
echo "✓ xdotool (X11)"
else
echo " xdotool not found (X11)"
fi
if command -v wtype >/dev/null 2>&1; then
echo "✓ wtype (Wayland)"
else
echo " wtype not found (Wayland)"
fi
if command -v ydotool >/dev/null 2>&1; then
echo "✓ ydotool (Wayland universal)"
else
echo " ydotool not found (Wayland)"
fi
# Detect distribution for install hints
echo ""
DETECTED_DISTRO="unknown"
if [ -f /etc/os-release ]; then
. /etc/os-release
DETECTED_DISTRO="$ID"
DETECTED_DISTRO_LIKE="$ID_LIKE"
fi
# Summary
echo ""
echo "===================================="
if [ $MISSING -eq 0 ]; then
echo "✓ All critical dependencies found!"
return 0
else
echo "✗ Some dependencies are missing"
echo ""
echo "Install based on your distribution:"
echo ""
# Determine distro family for install hints
if [[ "$DETECTED_DISTRO" == "ubuntu" || "$DETECTED_DISTRO_LIKE" == *"ubuntu"* || "$DETECTED_DISTRO" == "pop" || "$DETECTED_DISTRO" == "linuxmint" || "$DETECTED_DISTRO" == "elementary" || "$DETECTED_DISTRO" == "zorin" ]]; then
echo "Ubuntu/Debian-based:"
echo " sudo apt update"
echo " sudo apt install -y python3-gi gir1.2-gtk-3.0 gir1.2-gdkpixbuf-2.0 portaudio19-dev python3-dev python3-venv pkg-config xdotool wtype"
elif [[ "$DETECTED_DISTRO" == "fedora" || "$DETECTED_DISTRO_LIKE" == *"fedora"* || "$DETECTED_DISTRO" == "rhel" || "$DETECTED_DISTRO" == "centos" || "$DETECTED_DISTRO" == "rocky" || "$DETECTED_DISTRO" == "almalinux" ]]; then
echo "Fedora/RHEL-based:"
echo " sudo dnf install -y python3-gobject gtk3-devel gobject-introspection-devel portaudio-devel python3-devel python3-virtualenv pkg-config xdotool wtype"
elif [[ "$DETECTED_DISTRO" == "arch" || "$DETECTED_DISTRO_LIKE" == *"arch"* || "$DETECTED_DISTRO" == "manjaro" || "$DETECTED_DISTRO" == "endeavouros" ]]; then
echo "Arch Linux-based:"
echo " sudo pacman -S --needed python-gobject gtk3 gobject-introspection portaudio python pkg-config xdotool wtype"
elif [[ "$DETECTED_DISTRO" == "opensuse" || "$DETECTED_DISTRO_LIKE" == *"suse"* ]]; then
echo "openSUSE:"
echo " sudo zypper install -y python3-gobject python3-gobject-cairo gtk3 gobject-introspection-devel portaudio-devel python3-devel python3-virtualenv pkg-config xdotool wtype"
elif [[ "$DETECTED_DISTRO" == "gentoo" ]]; then
echo "Gentoo:"
echo " sudo emerge dev-python/pygobject:3 x11-libs/gtk+:3 dev-libs/libappindicator:3 media-libs/portaudio dev-lang/python:3.8 xdotool wtype"
elif [[ "$DETECTED_DISTRO" == "alpine" ]]; then
echo "Alpine Linux:"
echo " sudo apk add py3-gobject3 py3-pip gtk+3.0 py3-cairo portaudio-dev py3-virtualenv pkgconf xdotool wtype"
elif [[ "$DETECTED_DISTRO" == "void" ]]; then
echo "Void Linux:"
echo " sudo xbps-install -Sy python3-pip python3-gobject gtk+3 libappindicator gobject-introspection portaudio-devel python3-devel pkg-config xdotool wtype"
elif [[ "$DETECTED_DISTRO" == "solus" ]]; then
echo "Solus:"
echo " sudo eopkg install python3-pip python3-gobject gtk3 libappindicator gobject-introspection-devel portaudio-devel python3-virtualenv pkg-config xdotool wtype"
elif [[ "$DETECTED_DISTRO" == "mageia" ]]; then
echo "Mageia:"
if command -v dnf >/dev/null 2>&1; then
echo " sudo dnf install -y python3-gobject gtk3-devel gobject-introspection-devel portaudio-devel python3-devel python3-virtualenv pkg-config xdotool wtype"
else
echo " sudo urpmi -y python3-gobject gtk3-devel gobject-introspection-devel portaudio-devel python3-devel python3-virtualenv pkg-config xdotool wtype"
fi
else
echo "Ubuntu/Debian-based:"
echo " sudo apt install -y python3-gi gir1.2-gtk-3.0 portaudio19-dev python3-dev pkg-config xdotool wtype"
echo ""
echo "Fedora/RHEL-based:"
echo " sudo dnf install -y python3-gobject gtk3-devel portaudio-devel python3-devel pkg-config xdotool wtype"
echo ""
echo "Arch Linux:"
echo " sudo pacman -S python-gobject gtk3 portaudio python pkg-config xdotool wtype"
fi
echo ""
echo "After installing system dependencies, run the installer again:"
echo " ./install.sh"
return 1
fi
}
check_deps