Thales Maciel
dd2813340b
Stop implying that one Ubuntu 3.11 unit lane validates the full Linux support surface Aman documents.\n\nSplit CI into an Ubuntu CPython 3.10/3.11/3.12 unit-package matrix, a portable install plus doctor smoke lane, and a packaging lane gated on both. Add a reproducible ci_portable_smoke.sh helper with fake systemctl coverage, and force the installer onto /usr/bin/python3 so the smoke path uses the distro-provided GI and X11 Python packages it is meant to validate.\n\nUpdate the README, release/distribution docs, and Debian metadata to distinguish the automated Ubuntu CI floor from broader manual GA signoff families, and add the missing AppIndicator introspection package to the Ubuntu/Debian dependency lists.\n\nValidate with python3 -m unittest discover -s tests -p 'test_*.py', python3 -m py_compile src/*.py tests/*.py, and bash -n scripts/ci_portable_smoke.sh. The full xvfb-backed smoke could not be run locally in this sandbox because xvfb-run is unavailable.
163 lines
4.3 KiB
Markdown
163 lines
4.3 KiB
Markdown
# Portable X11 Install Guide
|
|
|
|
This is the canonical end-user install path for Aman on X11.
|
|
|
|
For the shortest first-run path, screenshots, and the expected tray/dictation
|
|
result, start with the quickstart in [`README.md`](../README.md).
|
|
|
|
Download published bundles, checksums, and release notes from
|
|
`https://git.thaloco.com/thaloco/aman/releases`.
|
|
|
|
## Supported environment
|
|
|
|
- X11 desktop session
|
|
- `systemd --user`
|
|
- System CPython `3.10`, `3.11`, or `3.12`
|
|
- Runtime dependencies installed from the distro package manager
|
|
|
|
Current automated validation covers Ubuntu CI on CPython `3.10`, `3.11`, and
|
|
`3.12` for unit/package coverage, plus a portable install and `aman doctor`
|
|
smoke path with Ubuntu system `python3`. The other distro-family instructions
|
|
below remain manual validation targets.
|
|
|
|
## Runtime dependencies
|
|
|
|
Install the runtime dependencies for your distro before running `install.sh`.
|
|
|
|
### Ubuntu/Debian
|
|
|
|
```bash
|
|
sudo apt install -y libportaudio2 python3-gi python3-xlib gir1.2-gtk-3.0 gir1.2-ayatanaappindicator3-0.1 libayatana-appindicator3-1
|
|
```
|
|
|
|
### Arch Linux
|
|
|
|
```bash
|
|
sudo pacman -S --needed portaudio gtk3 libayatana-appindicator python-gobject python-xlib
|
|
```
|
|
|
|
### Fedora
|
|
|
|
```bash
|
|
sudo dnf install -y portaudio gtk3 libayatana-appindicator-gtk3 python3-gobject python3-xlib
|
|
```
|
|
|
|
### openSUSE
|
|
|
|
```bash
|
|
sudo zypper install -y portaudio gtk3 libayatana-appindicator3-1 python3-gobject python3-python-xlib
|
|
```
|
|
|
|
## Fresh install
|
|
|
|
1. Download `aman-x11-linux-<version>.tar.gz` and `aman-x11-linux-<version>.tar.gz.sha256` from the releases page.
|
|
2. Verify the checksum.
|
|
3. Extract the bundle.
|
|
4. Run `install.sh`.
|
|
|
|
```bash
|
|
sha256sum -c aman-x11-linux-<version>.tar.gz.sha256
|
|
tar -xzf aman-x11-linux-<version>.tar.gz
|
|
cd aman-x11-linux-<version>
|
|
./install.sh
|
|
```
|
|
|
|
The installer:
|
|
|
|
- creates `~/.local/share/aman/<version>/`
|
|
- updates `~/.local/share/aman/current`
|
|
- creates `~/.local/bin/aman`
|
|
- installs `~/.config/systemd/user/aman.service`
|
|
- runs `systemctl --user daemon-reload`
|
|
- runs `systemctl --user enable --now aman`
|
|
|
|
If `~/.config/aman/config.json` does not exist yet, the first service start
|
|
opens the graphical settings window automatically.
|
|
|
|
After saving the first-run settings, validate the install with:
|
|
|
|
```bash
|
|
aman self-check --config ~/.config/aman/config.json
|
|
```
|
|
|
|
## Upgrade
|
|
|
|
Extract the new bundle and run the new `install.sh` again.
|
|
|
|
```bash
|
|
tar -xzf aman-x11-linux-<new-version>.tar.gz
|
|
cd aman-x11-linux-<new-version>
|
|
./install.sh
|
|
```
|
|
|
|
Upgrade behavior:
|
|
|
|
- existing config in `~/.config/aman/` is preserved
|
|
- existing cache in `~/.cache/aman/` is preserved
|
|
- the old installed version is removed after the new one passes install and service restart
|
|
- the service is restarted on the new version automatically
|
|
|
|
## Uninstall
|
|
|
|
Run the installed uninstaller from the active install:
|
|
|
|
```bash
|
|
~/.local/share/aman/current/uninstall.sh
|
|
```
|
|
|
|
Default uninstall removes:
|
|
|
|
- `~/.local/share/aman/`
|
|
- `~/.local/bin/aman`
|
|
- `~/.config/systemd/user/aman.service`
|
|
|
|
Default uninstall preserves:
|
|
|
|
- `~/.config/aman/`
|
|
- `~/.cache/aman/`
|
|
|
|
## Purge uninstall
|
|
|
|
To remove config and cache too:
|
|
|
|
```bash
|
|
~/.local/share/aman/current/uninstall.sh --purge
|
|
```
|
|
|
|
## Filesystem layout
|
|
|
|
- Installed payload: `~/.local/share/aman/<version>/`
|
|
- Active symlink: `~/.local/share/aman/current`
|
|
- Command shim: `~/.local/bin/aman`
|
|
- Install state: `~/.local/share/aman/install-state.json`
|
|
- User service: `~/.config/systemd/user/aman.service`
|
|
|
|
## Conflict resolution
|
|
|
|
The portable installer refuses to overwrite:
|
|
|
|
- an unmanaged `~/.local/bin/aman`
|
|
- an unmanaged `~/.config/systemd/user/aman.service`
|
|
- another non-portable `aman` found earlier in `PATH`
|
|
|
|
If you already installed Aman from a distro package:
|
|
|
|
1. uninstall the distro package
|
|
2. remove any leftover `aman` command from `PATH`
|
|
3. remove any leftover user service file
|
|
4. rerun the portable `install.sh`
|
|
|
|
## Recovery path
|
|
|
|
If installation succeeds but runtime behavior is wrong, use the supported recovery order:
|
|
|
|
1. `aman doctor --config ~/.config/aman/config.json`
|
|
2. `aman self-check --config ~/.config/aman/config.json`
|
|
3. `journalctl --user -u aman -f`
|
|
4. `aman run --config ~/.config/aman/config.json --verbose`
|
|
|
|
The failure IDs and example outputs for this flow are documented in
|
|
[`docs/runtime-recovery.md`](./runtime-recovery.md).
|
|
|
|
Public support and issue reporting instructions live in
|
|
[`SUPPORT.md`](../SUPPORT.md).
|