stickshid/AGENTS.md

AGENTS.md

Project Overview

stk is a C23 library for reading EdgeTx radio joystick input via HID. Wired for TDD using Unity and CMock.

Build System

• Generator: Ninja
• CMake minimum: 3.21
• C standard: C23

Commands

Configure (default):

cmake -S . -B build -G Ninja

Configure with coverage:

cmake -S . -B build-cov -G Ninja -DENABLE_COVERAGE=ON

Build:

ninja -C build

Run tests (full Unity output, colored):

ninja -C build check

Run tests (CTest summary only):

ninja -C build test

Run tests and generate coverage HTML:

ninja -C build-cov coverage

Run (Linux/macOS):

./build/main

Run (Windows):

./build/main.exe

Dependencies

Dependencies are managed via custom Find*.cmake scripts in deps/. These scripts use FetchContent under the hood to download and build libraries automatically.

To add a new dependency:

1. Add the corresponding Find<name>.cmake to deps/
2. Add find_package(<name> REQUIRED) to CMakeLists.txt
3. Link with <name>::<name> in target_link_libraries()

CMake Module Path

deps/ is added to CMAKE_MODULE_PATH so find_package() resolves to the custom scripts instead of system-installed packages.

Coding Conventions

• Language: C23
• 4-space indentation
• Naming: snake_case for variables, functions, and types
• Naming: SCREAMING_SNAKE_CASE only for macros and constants
• <> includes only for system headers (std, OS, etc.)
• "" includes for project headers
• Include order:
  1. C standard library headers (<stdlib.h>, <string.h>, etc.)
  2. (blank line)
  3. OS-specific headers (Windows API, POSIX, etc.)
  4. (blank line)
  5. Third-party dependencies
  6. (blank line)
  7. Local/project headers

Shell Scripts

• Always use #!/bin/sh shebang for shell scripts
• Scripts must be POSIX compliant (no bashisms)
• When providing commands to users:
  • Windows/PowerShell: use ` for line continuation
  • Unix/Linux/macOS: use \ for line continuation

Commit Messages

• Follow the 50/72 rule:
  • Subject line: max 50 characters
  • Body lines: wrapped at 72 characters
• Use conventional commit prefixes (feat:, fix:, docs:, chore:, etc.)
• Separate subject from body with a blank line
• Do not add yourself as a co-author (Co-Authored-By: trailers are forbidden)

Documentation (Markdown)

• Wrap normal text and lists at max 80 columns (for readability in terminals and editors).
• Exceptions: Tables and code blocks (```) can exceed 80 columns when formatting requires it (e.g. trees, alignment).
• Use standard Markdown: **bold**, `inline code`, ## headings, - or numbered lists, fenced code blocks with language hints.
• Keep examples concise, up-to-date, and self-documenting.
• Do not use em dashes (—). Use a colon or rewrite the sentence.
• Each shell command gets its own fenced code block; do not combine multiple commands into one block. Precede each block with a short plain-text label describing what the command does.
• This file (AGENTS.md) follows its own rules.

Source Layout

stk/
  stk.h / stk_win.c   EdgeTX HID radio reader (stub for now)
src/
  main.c              Entry point (hello world)
tests/
  test_stk.c          Unity tests for stk
deps/
  FindUnity.cmake      Fetches Unity v2.6.1 via ZIP
  FindCMock.cmake      Fetches CMock v2.6.0 via ZIP
  Platform.cmake       Detects OS and compiler
  Flags.cmake          Warning flags per compiler
  Coverage.cmake       gcovr coverage support
  Sanitizers.cmake     AddressSanitizer support
  IDE.cmake            VS/Xcode folder grouping

Platform Support

The project supports Windows, Linux, macOS, Emscripten, and Android via Platform.cmake and Flags.cmake in deps/.