Development Guide

This page is for developers working on mag-usb.

Repository layout

  • src/: C sources and headers

  • tests/: Unit tests (CTest)

  • install/: Deployment assets (e.g., udev rules)

  • docs/: User and developer documentation

  • assets/: Reference logs, notes, and images (keep large binaries here when necessary)

Build matrix

  • CMake 3.22+

  • C11

  • GCC or Clang

  • Recommended warning flags are enabled by default: -Wall -Wextra -Wpedantic

  • Optional: -DENABLE_WERROR=ON to treat warnings as errors (should be clean)

Common targets

  • mag-usb (main CLI)

  • i2c-pololu-tests (unit tests for the Pololu adapter logic)

Local builds

  • Debug profile: faster iteration, symbols

  • Release profile: optimized binary

CLion profiles are preconfigured (cmake-build-debug/release). From CLI:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug
cmake --build build --target mag-usb

Running tests

cmake -S . -B build -DBUILD_TESTING=ON
cmake --build build --target i2c-pololu-tests
(cd build && ctest --output-on-failure)

Coding patterns

  • Keep internal helper functions static and out of public headers.

  • Avoid global state where possible; prefer passing pList* explicitly.

  • Be strict on error handling: check return codes of system calls and I/O.

  • Use explicit (void)param casts to silence intentional unused-parameter warnings.

  • Cast to const uint8_t* when interacting with byte APIs to avoid signedness warnings.

Style and tools

  • No enforced formatter; follow existing code style.

  • You may use clang-format/clang-tidy locally; do not submit sweeping reformat PRs.

  • Consider enabling -DENABLE_WERROR=ON locally to catch regressions early.

Release process (suggested)

  • Update CHANGES.txt or a future CHANGELOG.md.

  • Tag versions using SemVer (suggest starting at v0.1.0 when ready).

  • Build Debug and Release; run CTest in both configurations.

Roadmap ideas (for discussion)

  • Expand unit tests to cover error cases and edge conditions in i2c-pololu.c.

  • Add a mock adapter for offline testing.

  • Introduce a simple CI workflow to build and run tests on push/PR.

  • Split device-specific docs and usage examples into separate pages.