44 lines
3.4 KiB
Markdown
44 lines
3.4 KiB
Markdown
# 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.
|
||
|
||
```sh
|
||
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.
|