wine-access/AGENTS.md

Repository Guidelines

Project Structure & Module Organization

This standalone Winelib helper forwards Wine accessibility events and NVDA/Tolk requests to Cthulhu’s session D-Bus service. Root sources include main.cpp (RPC, MSAA, event forwarding), list_view.cpp, and native hooks in menu_hook.c and edit_hook.c. Shared contracts live in headers and nvdaController.idl; generated RPC files belong under build/generated/. tests/ holds C/C++ fixtures and the Python integration runner. Arch packaging lives in distro-packages/ArchLinux/wine-access-git/.

Build, Test, and Development Commands

Requirements: CMake 3.20+, Wine development tools, GLib/GIO, pkg-config, and x86_64 MinGW GCC.

cmake -S . -B build -DCMAKE_TOOLCHAIN_FILE=winelib-toolchain.cmake
cmake --build build --parallel
xvfb-run -a ctest --test-dir build --output-on-failure
python3 tests/menu_integration.py --build-dir build

These configure, compile, run the MSAA state check, and exercise menus respectively. Integration tests require PyGObject, dbus-run-session, and a graphical display; use xvfb-run -a for a private display.

./build.sh builds and installs to $HOME/.local; optional arguments specify build directory and installation prefix. For local operation, run build/cthulhu-wine-access.exe with Cthulhu’s D-Bus service active. Keep the executable, .exe.so sidecar, and hook DLL together.

Coding Style & Naming Conventions

Follow existing style: two-space C/C++ indentation, four-space Python indentation, snake_case helper functions, camelCase local variables, and PascalCase structs. Preserve Windows API signatures and LGPL SPDX headers. C++ uses C++20; native hooks compile as C11 with -Wall -Wextra. No formatter is configured. Run shellcheck build.sh when editing that script. Use Wine Unicode APIs rather than Linux libc wide-character routines: Wine’s wchar_t is 16-bit.

Testing Guidelines

CTest runs tests/msaa_states_test.cpp; integration assertions live in tests/menu_integration.py. Follow existing *_fixture.c and *_test.cpp names. Choose --fixture edit, notepad, list, or winforms for affected controls. Exercise editor lifecycle flags and --fixture list --32-bit where relevant; the latter needs i686 MinGW GCC. Run Xvfb checks sequentially. No numeric coverage threshold is configured.

Recorded events do not prove audible speech or physical braille. Follow tests/README.md for live acceptance and regression procedures, including password exclusion and focus restoration.

Commit & Pull Request Guidelines

Recent commits use short imperative subjects describing behavior. Keep changes scoped; describe the problem, fix, commands run, and remaining live checks. Link relevant issues when available. Read the README’s AI-assisted contributions policy, review the diff, and test affected existing workflows before submission. Human review and submission remain the contributor’s responsibility.

Installation Guidance

When someone asks for installation help:

• Confirm their Linux distribution and version, and whether they want a user-local or system-wide installation, unless they have already provided that information.
• Identify any missing dependencies and the correct package names for their distribution.
• Ask the user to install missing system packages. If a command requires sudo, ask the user to run it.
• Provide installation instructions tailored to their distribution and chosen installation scope.