diff --git a/.github/workflows/distro-test-matrix.yml b/.github/workflows/distro-test-matrix.yml new file mode 100644 index 0000000..044fa60 --- /dev/null +++ b/.github/workflows/distro-test-matrix.yml @@ -0,0 +1,71 @@ +name: Distro Test Matrix + +on: + push: + branches: [ main, master ] + pull_request: + branches: [ main, master ] + workflow_dispatch: + +jobs: + test: + name: Test on ${{ matrix.container }} + runs-on: ubuntu-latest + continue-on-error: true + strategy: + fail-fast: false + matrix: + container: + - ubuntu:22.04 + - ubuntu:24.04 + - debian:12 + - fedora:39 + container: + image: ${{ matrix.container }} + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Install basic dependencies + run: | + set -e + # Install bash and basic tools + if command -v apt-get >/dev/null 2>&1; then + apt-get update + apt-get install -y bash curl python3 + elif command -v dnf >/dev/null 2>&1; then + dnf install -y bash curl python3 + fi + + - name: Run dependency checker + run: | + bash scripts/check-system-deps.sh || true + continue-on-error: true + + - name: Test Python import + run: | + python3 -c "import sys; sys.path.insert(0, 'src'); print('Testing imports...')" + # Test basic Python availability + python3 --version + + - name: Check install.sh syntax + run: | + bash -n install.sh + echo "install.sh: Syntax OK" + + - name: Check checker script syntax + run: | + bash -n scripts/check-system-deps.sh + echo "check-system-deps.sh: Syntax OK" + + summary: + name: Test Summary + runs-on: ubuntu-latest + needs: test + if: always() + steps: + - name: Check test results + run: | + echo "Distro test matrix completed" + echo "Some tests may have failed - this is expected for experimental distro support" diff --git a/README.md b/README.md index 775e39f..a37b805 100644 --- a/README.md +++ b/README.md @@ -209,11 +209,13 @@ For a complete list of changes, see the release notes. ## 📋 Requirements -- **OS**: Ubuntu 22.04+ (other Linux distros may work) +- **OS**: Linux (tested on Ubuntu 22.04+, Debian 11+, Fedora 39+, Arch Linux, openSUSE Tumbleweed) - **Python**: 3.8 or newer - **Display**: X11 or Wayland - **Hardware**: Microphone for voice input +**Note:** See [Distribution Compatibility](docs/DISTRO_COMPATIBILITY.md) for distribution-specific information and experimental support for Gentoo, Alpine, Void, Solus, and more. + ## 🎙️ Usage ### Voice Dictation diff --git a/install.sh b/install.sh index 7e2e59c..df34110 100755 --- a/install.sh +++ b/install.sh @@ -508,22 +508,37 @@ pacman_package_installed() { install_system_dependencies() { print_info "Installing system dependencies..." + # Check for pkg-config first (required for library detection) + if ! command_exists pkg-config; then + print_error "pkg-config is not installed but is required for library detection" + print_info "Please install pkg-config using your package manager:" + print_info " Ubuntu/Debian: sudo apt install pkg-config" + print_info " Fedora/RHEL: sudo dnf install pkg-config" + print_info " Arch: sudo pacman -S pkgconf" + print_info " openSUSE: sudo zypper install pkg-config" + print_info " Gentoo: sudo emerge pkgconf" + print_info " Alpine: sudo apk add pkgconf" + print_info " Void: sudo xbps-install -Sy pkg-config" + print_info " Solus: sudo eopkg install pkg-config" + exit 1 + fi + # Define package names for different distributions - local APT_PACKAGES_UBUNTU="python3-pip python3-gi python3-gi-cairo gir1.2-gtk-3.0 gir1.2-appindicator3-0.1 libgirepository1.0-dev python3-dev portaudio19-dev python3-venv wget curl unzip" - local APT_PACKAGES_DEBIAN_BASE="python3-pip python3-gi python3-gi-cairo gir1.2-gtk-3.0 libcairo2-dev python3-dev portaudio19-dev python3-venv wget curl unzip" + local APT_PACKAGES_UBUNTU="python3-pip python3-gi python3-gi-cairo gir1.2-gtk-3.0 gir1.2-appindicator3-0.1 libgirepository1.0-dev python3-dev portaudio19-dev python3-venv pkg-config wget curl unzip" + local APT_PACKAGES_DEBIAN_BASE="python3-pip python3-gi python3-gi-cairo gir1.2-gtk-3.0 libcairo2-dev python3-dev portaudio19-dev python3-venv pkg-config wget curl unzip" local APT_PACKAGES_DEBIAN_11_12="$APT_PACKAGES_DEBIAN_BASE libgirepository1.0-dev gir1.2-ayatanaappindicator3-0.1" local APT_PACKAGES_DEBIAN_13_PLUS="$APT_PACKAGES_DEBIAN_BASE libgirepository-2.0-dev gir1.2-ayatanaappindicator3-0.1" - local DNF_PACKAGES="python3-pip python3-gobject gtk3 libappindicator-gtk3 gobject-introspection-devel python3-devel portaudio-devel python3-virtualenv wget curl unzip" - local PACMAN_PACKAGES="python-pip python-gobject gtk3 libappindicator-gtk3 gobject-introspection python-cairo portaudio python-virtualenv wget curl unzip" - local ZYPPER_PACKAGES="python3-pip python3-gobject python3-gobject-cairo gtk3 libappindicator-gtk3 gobject-introspection-devel python3-devel portaudio-devel python3-virtualenv wget curl unzip" + local DNF_PACKAGES="python3-pip python3-gobject gtk3 libappindicator-gtk3 gobject-introspection-devel python3-devel portaudio-devel python3-virtualenv pkg-config wget curl unzip" + local PACMAN_PACKAGES="python-pip python-gobject gtk3 libappindicator-gtk3 gobject-introspection python-cairo portaudio python-virtualenv pkg-config wget curl unzip" + local ZYPPER_PACKAGES="python3-pip python3-gobject python3-gobject-cairo gtk3 libappindicator-gtk3 gobject-introspection-devel python3-devel portaudio-devel python3-virtualenv pkg-config wget curl unzip" # Gentoo uses Portage and different package naming convention - local EMERGE_PACKAGES="dev-python/pygobject:3 x11-libs/gtk+:3 dev-libs/libappindicator:3 media-libs/portaudio dev-lang/python:3.8" + local EMERGE_PACKAGES="dev-python/pygobject:3 x11-libs/gtk+:3 dev-libs/libappindicator:3 media-libs/portaudio dev-lang/python:3.8 pkgconf" # Alpine Linux uses apk and has musl libc - local APK_PACKAGES="py3-gobject3 py3-pip gtk+3.0 py3-cairo portaudio-dev py3-virtualenv wget curl unzip" + local APK_PACKAGES="py3-gobject3 py3-pip gtk+3.0 py3-cairo portaudio-dev py3-virtualenv pkgconf wget curl unzip" # Void Linux uses xbps - local XBPS_PACKAGES="python3-pip python3-gobject gtk+3 libappindicator gobject-introspection portaudio-devel python3-devel wget curl unzip" + local XBPS_PACKAGES="python3-pip python3-gobject gtk+3 libappindicator gobject-introspection portaudio-devel python3-devel pkg-config wget curl unzip" # Solus uses eopkg - local EOPKG_PACKAGES="python3-pip python3-gobject gtk3 libappindicator gobject-introspection-devel portaudio-devel python3-virtualenv wget curl unzip" + local EOPKG_PACKAGES="python3-pip python3-gobject gtk3 libappindicator gobject-introspection-devel portaudio-devel python3-virtualenv pkg-config wget curl unzip" local MISSING_PACKAGES="" local INSTALL_CMD="" diff --git a/tests/distro-testing-checklist.md b/tests/distro-testing-checklist.md new file mode 100644 index 0000000..c39af3d --- /dev/null +++ b/tests/distro-testing-checklist.md @@ -0,0 +1,314 @@ +# Distribution Testing Checklist + +Use this checklist when testing Vocalinux on a new Linux distribution. + +## Pre-Installation + +### System Information +- [ ] Record distribution name and version + ```bash + cat /etc/os-release + ``` + +- [ ] Record desktop environment + ```bash + echo $XDG_CURRENT_DESKTOP + ``` + +- [ ] Record display server + ```bash + echo $XDG_SESSION_TYPE + echo $WAYLAND_DISPLAY # For Wayland + echo $DISPLAY # For X11 + ``` + +- [ ] Record architecture + ```bash + uname -m + ``` + +- [ ] Run the dependency checker + ```bash + bash scripts/check-system-deps.sh + ``` + +- [ ] Note missing packages +- [ ] Note any special requirements (musl libc, specific library versions, etc.) + +## Installation + +### Standard Installation +- [ ] Download installer + ```bash + curl -fsSL https://raw.githubusercontent.com/jatinkrmalik/vocalinux/main/install.sh -o /tmp/vl.sh + ``` + +- [ ] Run installer + ```bash + bash /tmp/vl.sh + ``` + +- [ ] Check for errors during installation +- [ ] Verify virtual environment was created + ```bash + ls -la ~/.local/share/vocalinux/venv/ + ``` + +- [ ] Check wrapper scripts exist + ```bash + ls -la ~/.local/bin/vocalinux* + ``` + +- [ ] Check desktop entry was created + ```bash + ls -la ~/.local/share/applications/vocalinux.desktop + ``` + +- [ ] Check icons were installed + ```bash + ls -la ~/.local/share/icons/hicolor/scalable/apps/vocalinux* + ``` + +## Post-Installation + +### Launch from Terminal +- [ ] Launch from terminal + ```bash + ~/.local/bin/vocalinux-gui + ``` + +- [ ] Check for startup errors +- [ ] Verify the application starts +- [ ] Check that tray icon appears +- [ ] Verify keyboard shortcut works (Ctrl+Alt+M by default) + +### Launch from Application Menu +- [ ] Launch from desktop environment's application menu +- [ ] Verify the application starts +- [ ] Check that tray icon appears + +### Core Functionality Tests + +#### Tray Icon and Menu +- [ ] Left-click tray icon opens menu +- [ ] Right-click tray icon opens settings menu +- [ ] "Start Recording" menu item works +- [ ] "Stop Recording" menu item works +- [ ] "Settings" menu item opens settings dialog +- [ ] "Quit" menu item exits the application + +#### Keyboard Shortcuts +- [ ] Default shortcut (Ctrl+Alt+M) toggles recording +- [ ] Custom shortcuts can be configured in Settings +- [ ] Shortcut works in different applications (terminal, text editor, browser) + +#### Audio Recording +- [ ] Recording starts without errors +- [ ] Default audio device is detected + ```bash + # Check audio devices + pactl list sources short # PulseAudio + # or + arecord -l # ALSA + ``` + +- [ ] Audio levels are adequate +- [ ] Start sound plays (ascending tone) +- [ ] Stop sound plays (descending tone) + +#### Speech Recognition +- [ ] Speech is transcribed accurately +- [ ] Transcription appears in target application +- [ ] Punctuation works +- [ ] Capitalization works +- [ ] No backslash escapes in output (no \\', \\", etc.) + +#### Text Injection + +##### X11 (if applicable) +- [ ] Text injection works with xdotool +- [ ] Works in different applications: + - [ ] Terminal (gnome-terminal, konsole, etc.) + - [ ] Text editor (gedit, kate, mousepad, etc.) + - [ ] Browser (Firefox, Chromium, etc.) + - [ ] LibreOffice Writer + - [ ] Chat applications (Discord, Telegram, etc.) + +##### Wayland (if applicable) +- [ ] Text injection works with wtype +- [ ] Works in Wayland-native applications +- [ ] XWayland fallback works if needed +- [ ] Works in same applications as X11 test list + +##### Universal (ydotool if available) +- [ ] Text injection works with ydotool +- [ ] Works across both X11 and Wayland + +### Settings Dialog +- [ ] Settings dialog opens from tray menu +- [ ] Can configure audio input device +- [ ] Can configure keyboard shortcuts +- [ ] Can enable/disable sounds +- [ ] Can configure recognition engine (VOSK/Whisper) +- [ ] Can configure language +- [ ] Settings persist after restart +- [ ] Config file is created correctly + ```bash + cat ~/.config/vocalinux/config.json + ``` + +### Model Download (if using Whisper) +- [ ] Model download works +- [ ] Download progress is shown +- [ ] Model is saved to correct location + ```bash + ls -la ~/.local/share/vocalinux/models/ + ``` + +### Error Handling +- [ ] Graceful handling when no microphone is available +- [ ] Graceful handling when text injection fails +- [ ] Error messages are helpful +- [ ] Application doesn't crash on errors + +## Performance + +- [ ] Application starts within reasonable time (< 5 seconds) +- [ ] Recording starts/stops responsively +- [ ] Transcription appears without significant lag +- [ ] Memory usage is reasonable + ```bash + # Check memory usage + ps aux | grep vocalinux + ``` + +- [ ] CPU usage is reasonable during idle +- [ ] CPU usage is reasonable during recording + +## Cleanup and Uninstallation + +- [ ] Application can be quit cleanly +- [ ] No processes left running + ```bash + ps aux | grep vocalinux + ``` + +- [ ] Uninstallation works + ```bash + bash ~/.local/share/vocalinux/uninstall.sh # if exists + # or manual cleanup + rm -rf ~/.local/share/vocalinux + rm -rf ~/.config/vocalinux + rm ~/.local/share/applications/vocalinux.desktop + rm ~/.local/bin/vocalinux* + ``` + +## Known Issues + +Record any issues found during testing: + +### Distribution-Specific Issues + +| Issue | Severity | Workaround | Notes | +|-------|----------|------------|-------| +| | | | | + +### Desktop Environment Issues + +| DE | Issue | Severity | Workaround | Notes | +|----|-------|----------|------------|-------| +| GNOME | | | | | +| KDE Plasma | | | | | +| Xfce | | | | | +| sway | | | | | +| i3 | | | | | + +### Application-Specific Issues + +| Application | Issue | Severity | Workaround | Notes | +|-------------|-------|----------|------------|-------| +| Firefox | | | | | +| Chromium | | | | | +| LibreOffice | | | | | +| Terminal | | | | | + +## Sign-Off + +**Tester:** ____________________ + +**Date:** ____________________ + +**Distribution:** ____________________ ____________________ + +**Desktop Environment:** ____________________ + +**Display Server:** ____________________ + +**Overall Status:** ☐ Pass / ☐ Pass with Issues / ☐ Fail + +**Additional Comments:** + +--- + +## Submitting Results + +After completing the checklist: + +1. **Create a GitHub issue** with the title: + `Distro Test Results: [Distribution Name] [Version]` + +2. **Include the checklist** (either filled out or as a summary) + +3. **Attach logs** if there were errors: + - Installer output + - Application output from terminal + - Journal logs: `journalctl --user -u vocalinux -b` + +4. **Mention any workarounds** you found + +5. **Suggest improvements** to the documentation or installer + +## Testing Tips + +1. **Test early, test often** - Don't wait until everything is installed to test +2. **Keep notes** - Document everything, even things that seem minor +3. **Be thorough** - Test with multiple applications if possible +4. **Be patient** - Some distributions may require workarounds +5. **Share your findings** - Even negative results are valuable + +## Quick Reference Commands + +```bash +# Check distribution +cat /etc/os-release + +# Check desktop environment +echo $XDG_CURRENT_DESKTOP + +# Check display server +echo $XDG_SESSION_TYPE + +# Check audio devices +pactl list sources short # PulseAudio +arecord -l # ALSA + +# Check for running processes +ps aux | grep vocalinux + +# Check memory usage +ps aux | grep vocalinux | awk '{print $6}' + +# Check logs +journalctl --user -b | grep vocalinux + +# Run dependency checker +bash scripts/check-system-deps.sh + +# Test installation +bash -n install.sh + +# Verify installation +ls -la ~/.local/bin/vocalinux* +ls -la ~/.local/share/vocalinux/ +ls -la ~/.config/vocalinux/ +```