i38lock/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

I38Lock is an accessible C screen-locking utility based on i3lock. Core sources live at the repository root: i3lock.c handles the main program, while xcb.c, randr.c, dpi.c, unlock_indicator.c, and accessibility_feedback.c separate display, UI, and screen-reader concerns. Public project headers are under include/. The PAM service file is pam/i38lock, the manual page is i38lock.1, and packaging or CI support lives in meson/, ci/, and .github/.

Build, Test, and Development Commands

Install the dependencies listed in README.md, then build out of tree:

meson setup build -Dprefix=/usr
ninja -C build

To reproduce CI's stricter compile check, configure a fresh build directory:

CFLAGS="-Wformat -Wformat-security -Wextra -Wno-unused-parameter -Werror" meson setup build-ci
ninja -C build-ci

Run nix develop first if using the provided Nix development shell. Avoid installing from a development build unless installation behavior is the focus of the change.

Coding Style & Naming Conventions

The project uses C11 and the checked-in .clang-format. Use four-space indentation, braces for control statements, and existing snake_case naming patterns. Format C sources and headers with:

clang-format-15 -i $(git ls-files '*.c' 'include/*.h')
clang-format-15 --dry-run --Werror $(git ls-files '*.c' 'include/*.h')

Testing Guidelines

There is no automated runtime test suite. Every change must compile with the strict warning flags above. For behavior changes, run timeout --foreground 30s build/i38lock -n from an X11 session, verify the affected workflow, then unlock by entering your password and pressing Enter. Install pam/i38lock first and keep the watchdog enabled to avoid locking yourself out of an active development session.

Commit & Pull Request Guidelines

Recent commits use short imperative subjects, often scoped when useful, such as meson: use explicit_bzero if it is available. Keep each commit focused. Pull requests should explain the behavior change, include reproduction and verification steps, and link relevant issues. Include i38lock --version and environment details for bug fixes. Do not propose image-manipulation features; preprocess background images with external tools.