57 lines
2.1 KiB
Markdown
57 lines
2.1 KiB
Markdown
# GEMINI.md
|
|
|
|
## Project Overview
|
|
|
|
This project is a `gtklock` module named `ahfail`, written in Rust (using `gtk-rs`) with a Meson build system.
|
|
|
|
The module listens for failed unlock attempts (`PW_FAILURE`) in `gtklock`. Upon failure, it:
|
|
1. Spawns a looping "Nedry" sprite animation at a random screen location.
|
|
2. Plays an audio clip ("ah ah ah, you didn't say the magic word").
|
|
3. Avoids placing sprites in a user-configurable "deadzone".
|
|
|
|
All assets (images and audio) are compiled into the module binary as GResources.
|
|
|
|
## Build Architecture
|
|
|
|
* **Meson:** The primary build system. It handles:
|
|
* Compiling GResources (`assets/ahfail.gresource.xml`).
|
|
* Invoking Cargo to build the Rust code as a static library (`libahfail_module.a`).
|
|
* Linking the Rust static library, GResources, and C dependencies into the final shared object (`ahfail-module.so`).
|
|
* **Cargo:** Handles the Rust source code, dependencies (`gtk`, `gdk`, `gstreamer`), and tests.
|
|
|
|
## Key Files
|
|
|
|
* `src/lib.rs`: FFI entry points (`on_activation`, `on_window_create`, etc.) exported to C.
|
|
* `src/handler.rs`: Main logic for sprite placement and audio playback.
|
|
* `src/config.rs`: Argument parsing logic.
|
|
* `tests/ahfail_tests.rs`: Comprehensive integration tests mocking `gtklock` behavior.
|
|
* `meson.build`: Build definition bridging C and Rust.
|
|
|
|
## Building and Running
|
|
|
|
### Prerequisites
|
|
* Meson, Ninja, Rust (Cargo)
|
|
* `gtk3` development headers
|
|
* `gstreamer` + `gst-plugins-base` + `gst-plugins-good` (runtime)
|
|
|
|
### Commands
|
|
```bash
|
|
# Setup
|
|
meson setup builddir
|
|
|
|
# Build
|
|
meson compile -C builddir
|
|
|
|
# Test (Rust logic)
|
|
cargo test
|
|
|
|
# Run (Manual test)
|
|
gtklock -d -m builddir/ahfail-module.so -- --deadzone=X,Y,W,H
|
|
```
|
|
|
|
## Development Conventions
|
|
|
|
* **Safety:** Use `WindowContext` wrappers in `src/context.rs` to handle unsafe `Window` pointers.
|
|
* **State:** `MODULE_STATE` (thread-local) holds global config/assets. `WindowData` (heap-allocated) holds per-window sprites and players.
|
|
* **Tests:** `tests/ahfail_tests.rs` contains integration tests that mock `gtklock` structures. Run with `cargo test`.
|