Development

Development

How to build and run ScreenGuard from source.

---

Prerequisites

Tool	Why
Flutter 3.x (Dart ≥ 3.0, < 4.0)	The GUI
A C compiler	The three native C helpers in src/ (the X11 fallback is Python in bin/)
pkg-config, libsqlite3-dev, libgtk-3-dev	sqlite3 FFI and the Linux desktop target
xdotool, xorg-xprop, xprintidle	X11 tracking and enforcement

sudo apt install build-essential pkg-config libsqlite3-dev libgtk-3-dev \
                 xdotool xorg-xprop xprintidle

---

Build and run

git clone https://github.com/adityakrishnan005-a11y/ScreenGuard.git
cd ScreenGuard

flutter pub get
flutter build linux --release

# Compile the background daemon next to the GUI bundle
dart compile exe bin/daemon.dart -o build/linux/x64/release/bundle/screenguard-daemon

# Run it
./build/linux/x64/release/bundle/screenguard

For a debug build with hot reload:

flutter run -d linux

The daemon can be run separately for debugging:

dart run bin/daemon.dart

The daemon is currently written in Dart. The v1.5 roadmap targets a C port that preserves the current behavior; until then, the Dart daemon is the implementation to build and debug.

---

Install your own build

./tools/build-and-install.sh --yes

The script builds the GUI, compiles the daemon and the native helpers, then hands off to install.sh, which installs into ~/.local, links the binaries into ~/.local/bin and refreshes the systemd user unit. Use --system for /usr/local, and --prefix DIR for anything else.

---

Layout

ScreenGuard/
├── lib/
│   ├── main.dart              ← entry point, error handling, CLI arguments
│   ├── screens/               ← dashboard, focus, settings, lockout screens
│   ├── services/              ← database, tracker, daemon, updater, notifications
│   └── widgets/               ← reusable pieces
├── bin/daemon.dart            ← the background daemon (Dart)
├── bin/active_window_helper.py ← X11 fallback probe
├── extension/                 ← GNOME Shell extension (GJS)
├── src/                       ← three native helpers in C
├── packaging/                 ← nfpm, RPM spec, PKGBUILD, AppStream metadata
├── tools/                     ← build, install and maintenance scripts
├── docs/assets/               ← screenshots used by the README; wiki images live in the wiki repo
└── test/                      ← unit tests

---

The daemon and the GUI share one database

Both processes open ~/.local/share/screenguard/usage.db in WAL mode and coordinate through the settings table. When you change something in the GUI, it writes a key; the daemon picks it up on its next poll. There is no IPC socket and no message bus to debug.

This has one consequence worth knowing: changes made by hand in the database while the daemon is running may be overwritten by the daemon's cached settings, because the daemon caches the settings table for a short period. Stop the daemon before hand-editing.

---

Running the tests

flutter test

The suite covers the parts that are pure logic and easy to get wrong: the telemetry queue/retry and dev-build exclusion logic, and the feedback-request parsing and version gating.

---

Commit conventions

feat(scope): short description
fix(scope): short description
docs(scope): short description
chore(scope): short description

Scopes in use: update, feedback, focus, daemon, installer, telemetry, packaging, docs.

---

Reporting and fixing issues

When you fix a bug, please include the symptom you saw, the environment, and how you verified the fix. If your change touches X11 behaviour, attach a screenshot or recording — see Troubleshooting for the details that make a report actionable.

---

Related: Architecture · Packaging and Releases · Contributing