xavierk/voculinux
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 3 Wiki Activity

refactor(installer): generate distro package map (#872)

Browse Source 
* refactor(installer): generate distro package map

* fix(installer): handle Debian derivative package maps

* docs(installer): document generated package map

* fix(installer): validate package map and refresh derivative probes

* fix(installer): name openSUSE package roles
This commit is contained in:
Sergey Silaev
2026-09-29 21:16:03 -07:00
committed by GitHub
parent fb9166ed9e
commit c0217a8aec
19 changed files with 1057 additions and 465 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/DISTRO_COMPATIBILITY.md
+22 -11
View File
@@ -36,9 +36,10 @@ The `.desktop` entry is automatically configured with the detected `GI_TYPELIB_P
## Officially Supported Distributions
These distributions are tested and known to work well with Vocalinux. A
derivative is judged by the Python it ships rather than by its own version
number, which rarely tracks the base release, and `install.sh` checks the
interpreter rather than the release label.
derivative is judged by the Python and package repositories it ships rather
than by its own version number, which rarely tracks the base release. In
particular, `install.sh` does not interpret a Debian-based derivative's product
version as a Debian release number.
| Distribution | Version | Status | Notes |
|--------------|---------|--------|-------|
@@ -72,13 +73,20 @@ These distributions are known to be incompatible:
| Distribution | Status | Reason |
|--------------|--------|--------|
| Debian 11 and earlier | ❌ Not Supported | EOL and below the Python 3.11 floor; the installer requires Debian 12+ |
| NixOS | ❌ Not Supported | Completely different filesystem layout (/nix/store), incompatible with standard installer |
## Requirements by Distribution
These are baseline commands for manual installations. The exact inventory used
by `install.sh`, including package alternatives and conditional dependencies,
lives in [`scripts/distro-package-map.yaml`](../scripts/distro-package-map.yaml).
For the complete manual setup sequence, including native build prerequisites,
use [INSTALL_MANUAL.md](INSTALL_MANUAL.md#system-packages-by-distribution).
### Ubuntu/Debian-based
```bash
sudo apt install -y python3-gi gir1.2-gtk-3.0 gir1.2-gdkpixbuf-2.0 \
sudo apt install -y python3-gi gir1.2-gtk-3.0 gir1.2-ibus-1.0 gir1.2-gdkpixbuf-2.0 \
portaudio19-dev python3-dev python3-venv pkg-config
```
@@ -134,13 +142,13 @@ the VOSK engine (`--engine=vosk`) as a fully-packaged alternative.
### Fedora/RHEL-based
```bash
sudo dnf install -y python3-gobject gtk3-devel gobject-introspection-devel \
sudo dnf install -y python3-gobject gtk3-devel ibus-devel cairo-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 \
sudo pacman -S --needed python-gobject gtk3 ibus gobject-introspection \
portaudio python pkg-config
```
@@ -151,9 +159,11 @@ PYVER=$(python3 -c 'import sys; print(f"python{sys.version_info.major}{sys.versi
sudo zypper install -y \
"${PYVER}-pip" "${PYVER}-gobject" "${PYVER}-gobject-cairo" \
"${PYVER}-devel" "${PYVER}-virtualenv" \
gtk3 typelib-1_0-AyatanaAppIndicator3-0_1 libayatana-appindicator3-1 \
gtk3 ibus typelib-1_0-IBus-1_0 \
typelib-1_0-AyatanaAppIndicator3-0_1 libayatana-appindicator3-1 \
typelib-1_0-Notify-0_7 libnotify4 \
gobject-introspection-devel portaudio-devel pkg-config cmake wget curl unzip \
gcc gcc-c++ make patchelf \
xdotool wtype
# Optional: only needed for whisper.cpp Vulkan GPU builds
@@ -224,7 +234,7 @@ Before running `pip install vocalinux`, `pip install "vocalinux[vosk]"`, or
#### Ubuntu/Debian
```bash
sudo apt install python3-gi gir1.2-gtk-3.0 gir1.2-ayatanaappindicator3-0.1 \
sudo apt install python3-gi gir1.2-gtk-3.0 gir1.2-ibus-1.0 gir1.2-ayatanaappindicator3-0.1 \
libgirepository1.0-dev libcairo2-dev portaudio19-dev python3-dev \
python3-venv pkg-config xdotool wtype wl-clipboard xclip xsel
```
@@ -234,14 +244,14 @@ On Ubuntu 24.04+ or Pop!_OS, install `libgirepository-2.0-dev` if
#### Fedora
```bash
sudo dnf install python3-gobject gtk3 gtk3-devel libayatana-appindicator-gtk3 \
sudo dnf install python3-gobject gtk3 gtk3-devel ibus-devel cairo-devel libayatana-appindicator-gtk3 \
gobject-introspection-devel portaudio-devel python3-devel \
python3-virtualenv pkg-config xdotool wtype wl-clipboard xclip xsel
```
#### Arch Linux
```bash
sudo pacman -S python-gobject gtk3 libayatana-appindicator gobject-introspection \
sudo pacman -S python-gobject gtk3 ibus libayatana-appindicator gobject-introspection \
python-cairo portaudio python-virtualenv pkg-config xdotool wtype wl-clipboard xclip xsel
```
@@ -249,7 +259,8 @@ sudo pacman -S python-gobject gtk3 libayatana-appindicator gobject-introspection
```bash
PYVER=$(python3 -c 'import sys; print(f"python{sys.version_info.major}{sys.version_info.minor}")')
sudo zypper install "${PYVER}-gobject" "${PYVER}-gobject-cairo" gtk3 \
sudo zypper install "${PYVER}-gobject" "${PYVER}-gobject-cairo" gtk3 ibus typelib-1_0-IBus-1_0 \
gcc gcc-c++ make patchelf \
typelib-1_0-AyatanaAppIndicator3-0_1 libayatana-appindicator3-1 \
typelib-1_0-Notify-0_7 libnotify4 \
portaudio-devel "${PYVER}-devel" "${PYVER}-virtualenv" pkg-config xdotool wtype wl-clipboard xclip xsel
docs/INSTALL.md
+1 -1
View File
@@ -87,7 +87,7 @@ chmod +x Vocalinux-*-x86_64.AppImage # or aarch64
./Vocalinux-*-x86_64.AppImage
```
Built against glibc 2.35, so it starts on Debian 12+, Ubuntu 22.04+, Fedora 36+, Arch, and Tumbleweed. Older bases (RHEL 9, Debian 11, Ubuntu 20.04) are below that floor; use the installer or PyPI there.
Built against glibc 2.35, so it starts on Debian 12+, Ubuntu 22.04+, Fedora 36+, Arch, and Tumbleweed. Older bases (RHEL 9, Debian 11, Ubuntu 20.04) are below that AppImage floor. The installer and PyPI package still require a distro that ships Python 3.11+, so they are not a workaround for Debian 11 or Ubuntu 20.04.
Still needs host text-injection tools (`xdotool` on X11; `wtype` / `ydotool` / clipboard tools on Wayland). Current AppImages rebuild whisper.cpp with Vulkan and use the host GPU driver (`vulkaninfo --summary`). Prefer the installer when you want system deps, a CUDA build, and models set up automatically.
docs/INSTALL_MANUAL.md
+24 -8
View File
@@ -2,12 +2,21 @@
Use this when the [recommended installer](INSTALL.md) is not a fit, or you want an explicit package list. Prefer `./install.sh` for a normal desktop install.
The commands below are human-readable baselines for manual installs. The
installer's authoritative package inventory, including build helpers and
fallbacks, is [`scripts/distro-package-map.yaml`](../scripts/distro-package-map.yaml).
Its generated shell module is committed so installations do not need a YAML
parser.
Related: [DISTRO_COMPATIBILITY.md](DISTRO_COMPATIBILITY.md), [TROUBLESHOOTING.md](TROUBLESHOOTING.md).
## System packages by distribution
Install desktop/system dependencies **before** creating a venv or running `pip install vocalinux`. Pip cannot install GTK typelibs, AppIndicator, PortAudio, or text-injection tools.
Debian 11 and earlier are unsupported; the Debian instructions start at Debian
12, which is the oldest release with the required Python 3.11.
### Ubuntu
```bash
@@ -15,8 +24,9 @@ sudo apt update
sudo apt install -y \
python3-pip python3-venv python3-dev \
python3-gi python3-gi-cairo \
gir1.2-gtk-3.0 \
libgirepository1.0-dev portaudio19-dev \
gir1.2-gtk-3.0 gir1.2-ibus-1.0 \
libgirepository1.0-dev libcairo2-dev portaudio19-dev \
build-essential pkg-config cmake libssl-dev autoconf automake libtool patchelf \
wget curl unzip
# Tray: older Ubuntu → gir1.2-appindicator3-0.1
@@ -36,8 +46,9 @@ sudo apt update
sudo apt install -y \
python3-pip python3-venv python3-dev \
python3-gi python3-gi-cairo \
gir1.2-gtk-3.0 \
gir1.2-gtk-3.0 gir1.2-ibus-1.0 \
libgirepository1.0-dev libcairo2-dev portaudio19-dev \
build-essential pkg-config cmake libssl-dev autoconf automake libtool patchelf \
wget curl unzip \
gir1.2-ayatanaappindicator3-0.1 \
xdotool wtype wl-clipboard xclip xsel
@@ -50,8 +61,9 @@ sudo apt update
sudo apt install -y \
python3-pip python3-venv python3-dev \
python3-gi python3-gi-cairo \
gir1.2-gtk-3.0 \
gir1.2-gtk-3.0 gir1.2-ibus-1.0 \
libgirepository-2.0-dev libcairo2-dev portaudio19-dev \
build-essential pkg-config cmake libssl-dev autoconf automake libtool patchelf \
wget curl unzip \
gir1.2-ayatanaappindicator3-0.1 \
xdotool wtype wl-clipboard xclip xsel
@@ -64,8 +76,9 @@ Debian notes (OpenSSL build deps, ydotool, etc.): [DISTRO_COMPATIBILITY.md](DIST
```bash
sudo dnf install -y \
python3-pip python3-devel python3-virtualenv \
python3-gobject gtk3 libayatana-appindicator-gtk3 \
gobject-introspection-devel portaudio-devel \
python3-gobject gtk3 ibus-devel libayatana-appindicator-gtk3 \
gobject-introspection-devel portaudio-devel cairo-devel \
gcc gcc-c++ make pkg-config cmake patchelf \
wget curl unzip xdotool wtype wl-clipboard xclip xsel
```
@@ -75,9 +88,10 @@ Prefer the AUR package (`yay -S vocalinux`). Manual packages:
```bash
sudo pacman -S --needed \
python-pip python-gobject gtk3 \
python-pip python-gobject gtk3 ibus \
libayatana-appindicator gobject-introspection \
python-cairo portaudio python-virtualenv \
base-devel pkg-config cmake patchelf \
wget curl unzip xdotool wtype wl-clipboard xclip xsel
```
@@ -89,9 +103,11 @@ PYVER=$(python3 -c 'import sys; print(f"python{sys.version_info.major}{sys.versi
sudo zypper install -y \
"${PYVER}-pip" "${PYVER}-gobject" "${PYVER}-gobject-cairo" \
"${PYVER}-devel" "${PYVER}-virtualenv" \
gtk3 typelib-1_0-AyatanaAppIndicator3-0_1 libayatana-appindicator3-1 \
gtk3 ibus typelib-1_0-IBus-1_0 \
typelib-1_0-AyatanaAppIndicator3-0_1 libayatana-appindicator3-1 \
typelib-1_0-Notify-0_7 libnotify4 \
gobject-introspection-devel portaudio-devel pkg-config cmake \
gcc gcc-c++ make patchelf \
wget curl unzip xdotool wtype wl-clipboard xclip xsel
# Optional: whisper.cpp Vulkan builds