linux observer
build: add bootstrap target, doctor gating, and troubleshooting docs
+57
-2
+28
INSTALL.md
+28
INSTALL.md
···
121
121
then restart GNOME Shell — on Wayland, log out and back in; on X11, press Alt+F2 and type `r`. v64 supports GNOME Shell 45–50; check https://extensions.gnome.org/extension/615/appindicator-support/ for a newer build if you're on a later shell.
122
122
123
123
to check if it's working: `gnome-extensions list | grep appindicator` should show it. if the tray icon still doesn't appear, verify it's enabled: `gnome-extensions enable appindicatorsupport@rgcjonas.gmail.com`
124
+
125
+
## Troubleshooting
126
+
127
+
Common install-time errors and their fixes:
128
+
129
+
- **`pkg-config: command not found` or `cairo` pkg-config failure**
130
+
- fedora: `sudo dnf install pkgconf-pkg-config cairo-devel`
131
+
- debian/ubuntu: `sudo apt install pkg-config libcairo2-dev`
132
+
- arch: `sudo pacman -S pkgconf cairo`
133
+
- opensuse: `sudo zypper install pkgconf-pkg-config cairo-devel`
134
+
135
+
- **`girepository-2.0` missing or `pygobject` build failure**
136
+
- fedora: `sudo dnf install gobject-introspection-devel`
137
+
- debian/ubuntu: `sudo apt install libgirepository1.0-dev`
138
+
- arch: `sudo pacman -S gobject-introspection`
139
+
- opensuse: `sudo zypper install gobject-introspection-devel`
140
+
141
+
- **`Python.h: No such file or directory`**
142
+
- fedora: `sudo dnf install python3-devel`
143
+
- debian/ubuntu: `sudo apt install python3-dev`
144
+
- arch: already bundled in `python` package
145
+
- opensuse: `sudo zypper install python3-devel`
146
+
147
+
- **`pipx: command not found`**
148
+
- fedora: `sudo dnf install pipx`
149
+
- debian/ubuntu: `sudo apt install pipx`
150
+
- arch: `sudo pacman -S python-pipx`
151
+
- opensuse: `sudo zypper install python3-pipx`
+29
-2
Makefile
+29
-2
Makefile
···
1
1
# solstone-linux Makefile
2
2
# Standalone Linux desktop observer for solstone
3
3
4
-
.PHONY: install test test-only format ci clean clean-install versions all install-service service-restart service-status service-logs uninstall-service
4
+
.PHONY: install test test-only format ci clean clean-install versions all bootstrap install-service service-restart service-status service-logs uninstall-service
5
5
6
6
# Default target
7
7
all: install
···
13
13
14
14
# Require uv
15
15
UV := $(shell command -v uv 2>/dev/null)
16
+
ifneq ($(filter bootstrap,$(MAKECMDGOALS)),bootstrap)
16
17
ifndef UV
17
-
$(error uv is not installed. Install it: curl -LsSf https://astral.sh/uv/install.sh | sh)
18
+
$(error uv is not installed. Run: make bootstrap)
19
+
endif
18
20
endif
19
21
20
22
APP := solstone-linux
···
32
34
# Install package in editable mode with isolated venv
33
35
install: .installed
34
36
37
+
bootstrap:
38
+
@if command -v uv >/dev/null 2>&1; then \
39
+
echo "uv already installed"; \
40
+
else \
41
+
echo "installing uv..."; \
42
+
curl -LsSf https://astral.sh/uv/install.sh | sh; \
43
+
fi
44
+
@if ! command -v pipx >/dev/null 2>&1; then \
45
+
echo "pipx missing — install instructions:"; \
46
+
echo " fedora: sudo dnf install pipx"; \
47
+
echo " debian: sudo apt install pipx"; \
48
+
echo " arch: sudo pacman -S python-pipx"; \
49
+
echo " opensuse: sudo zypper install python3-pipx"; \
50
+
exit 1; \
51
+
fi
52
+
@python3 -c 'import sys; sys.exit(0 if sys.version_info >= (3,10) else 1)' || { \
53
+
echo "python >=3.10 required"; exit 1; \
54
+
}
55
+
@if [ -f .installed ]; then \
56
+
$(VENV_BIN)/solstone-linux doctor; \
57
+
else \
58
+
echo "now run: make install-service"; \
59
+
fi
60
+
35
61
install-service: .installed
62
+
@$(VENV_BIN)/solstone-linux doctor
36
63
@command -v pipx >/dev/null || { echo "pipx not found — install with: sudo dnf install pipx (or apt/brew equivalent)"; exit 1; }
37
64
@$(PYTHON) -m solstone_linux.install_guard preinstall "$(CURDIR)"; rc=$$?; \
38
65
if [ $$rc -eq 2 ]; then exit 1; \