# Development

This page covers project layout, local build commands, documentation generation,
and the remaining roadmap.

## Repository Layout

```text
src/include/libvirtualhid/    Public C++ headers
src/core/                     Shared profile, descriptor, and report logic
src/platform/windows/         Windows client backend and UMDF control channel
src/platform/windows/driver/  Windows UMDF2 driver package sources
src/platform/linux/           Linux uhid/uinput backend
src/platform/macos/           macOS CoreGraphics keyboard and mouse backend
examples/                     Minimal consumers and platform smoke tests
tests/                        Unit and integration tests
cmake/                        Package config and helper modules
docs/                         Project documentation
third-party/dockle/           LizardByte documentation toolchain submodule
third-party/googletest/       GoogleTest submodule
```

## Windows Library Build

On Windows, the normal library and tests are built with MSYS2/UCRT64 for MinGW
coverage. Build directories should use the `cmake-build-` prefix.

```bash
cmake -S . -B cmake-build-debug-mingw-ucrt64-ninja -G Ninja \
  -DCMAKE_BUILD_TYPE=Debug
cmake --build cmake-build-debug-mingw-ucrt64-ninja
cmake-build-debug-mingw-ucrt64-ninja/tests/test_libvirtualhid.exe
```

The Windows UMDF driver package is a separate MSVC/WDK build. See
[Windows driver package](windows-driver.md).

## Linux Build

Linux builds use the same CMake target shape. Integration tests that create real
devices require access to `/dev/uhid` and `/dev/uinput`; see
[Platform support](platform-support.md).

```bash
cmake -S . -B cmake-build-debug -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build cmake-build-debug
cmake-build-debug/tests/test_libvirtualhid
```

## macOS Build

macOS builds use the same CMake target shape and link the CoreGraphics backend
against the system ApplicationServices, Carbon, CoreFoundation, and IOKit
frameworks. The CI test coverage exercises translation and lifecycle paths
without posting live synthetic input events.

```bash
cmake -S . -B cmake-build-debug -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build cmake-build-debug
cmake-build-debug/tests/test_libvirtualhid
```

## Documentation

Documentation is generated by Dockle. The authored inputs and project-specific
Doxygen settings are declared in `dockle.toml`; Dockle owns the generated
Doxyfile used by the CMake `docs` target.

```bash
cmake --build cmake-build-debug-mingw-ucrt64-ninja --target docs
```

Keep Markdown pages focused on decisions or workflows that consumers and
maintainers need. Avoid preserving old implementation-plan checklists once the
code and tests provide a better source of truth.

## Validation Targets

- `test_libvirtualhid`: shared GoogleTest binary under the build directory's
  `tests` directory.
- `gamepad_adapter`: example executable for profile and lifecycle diagnostics.
- `run_gamepad_adapter_example`: CMake target that runs `gamepad_adapter` from
  its generator-specific output path when a platform backend is available.
- Windows driver helper scripts under `scripts/windows`.
- Linux consumer tests through SDL2, libinput, `uhid`, and `uinput` where the
  host environment supports real virtual devices.
- Doxygen docs target for README, Markdown pages, and public header rendering.

## Roadmap

- Add native macOS virtual-HID gamepad support beyond the current CoreGraphics
  keyboard and mouse injection backend, including signing, entitlement, and
  installer constraints.
- Add bindings for other languages, such as Python, Rust, and C#. Bindings will
  be considered for any requested language.
- Evaluate an optional FreeBSD CUSE-backed `uhid(4)`-compatible device for
  direct HID consumers. This would supplement uinput; it is not equivalent to
  registering a virtual device with FreeBSD's kernel HID bus.