147 lines
3.8 KiB
Markdown
147 lines
3.8 KiB
Markdown
# 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):
|
|
```sh
|
|
cmake -S . -B build -G Ninja
|
|
```
|
|
|
|
Configure with coverage:
|
|
```sh
|
|
cmake -S . -B build-cov -G Ninja -DENABLE_COVERAGE=ON
|
|
```
|
|
|
|
Build:
|
|
```sh
|
|
ninja -C build
|
|
```
|
|
|
|
Run tests (full Unity output, colored):
|
|
```sh
|
|
ninja -C build check
|
|
```
|
|
|
|
Run tests (CTest summary only):
|
|
```sh
|
|
ninja -C build test
|
|
```
|
|
|
|
Run tests and generate coverage HTML:
|
|
```sh
|
|
ninja -C build-cov coverage
|
|
```
|
|
|
|
Run (Linux/macOS):
|
|
```sh
|
|
./build/main
|
|
```
|
|
|
|
Run (Windows):
|
|
```sh
|
|
./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
|
|
|
|
```text
|
|
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/`.
|