chore(dev): inform AI agents about dev workflows

.clang-tidy

@@ -0,0 +1,153 @@
+---
+Checks:          'clang-diagnostic-*,clang-analyzer-*,bugprone-*,-bugprone-easily-swappable-parameters,clang-diagnostics-*,clang-analyzer-*'
+WarningsAsErrors: ''
+HeaderFilterRegex: ''
+AnalyzeTemporaryDtors: false
+FormatStyle:     file
+CheckOptions:
+  - key:             bugprone-string-constructor.LargeLengthThreshold
+    value:           '8388608'
+  - key:             modernize-replace-auto-ptr.IncludeStyle
+    value:           llvm
+  - key:             bugprone-reserved-identifier.Invert
+    value:           'false'
+  - key:             bugprone-implicit-widening-of-multiplication-result.UseCXXStaticCastsInCppSources
+    value:           'true'
+  - key:             cert-oop54-cpp.WarnOnlyIfThisHasSuspiciousField
+    value:           'false'
+  - key:             bugprone-unused-return-value.CheckedFunctions
+    value:           '::std::async;::std::launder;::std::remove;::std::remove_if;::std::unique;::std::unique_ptr::release;::std::basic_string::empty;::std::vector::empty;::std::back_inserter;::std::distance;::std::find;::std::find_if;::std::inserter;::std::lower_bound;::std::make_pair;::std::map::count;::std::map::find;::std::map::lower_bound;::std::multimap::equal_range;::std::multimap::upper_bound;::std::set::count;::std::set::find;::std::setfill;::std::setprecision;::std::setw;::std::upper_bound;::std::vector::at;::bsearch;::ferror;::feof;::isalnum;::isalpha;::isblank;::iscntrl;::isdigit;::isgraph;::islower;::isprint;::ispunct;::isspace;::isupper;::iswalnum;::iswprint;::iswspace;::isxdigit;::memchr;::memcmp;::strcmp;::strcoll;::strncmp;::strpbrk;::strrchr;::strspn;::strstr;::wcscmp;::access;::bind;::connect;::difftime;::dlsym;::fnmatch;::getaddrinfo;::getopt;::htonl;::htons;::iconv_open;::inet_addr;::isascii;::isatty;::mmap;::newlocale;::openat;::pathconf;::pthread_equal;::pthread_getspecific;::pthread_mutex_trylock;::readdir;::readlink;::recvmsg;::regexec;::scandir;::semget;::setjmp;::shm_open;::shmget;::sigismember;::strcasecmp;::strsignal;::ttyname'
+  - key:             cert-dcl16-c.NewSuffixes
+    value:           'L;LL;LU;LLU'
+  - key:             bugprone-exception-escape.FunctionsThatShouldNotThrow
+    value:           ''
+  - key:             modernize-loop-convert.MaxCopySize
+    value:           '16'
+  - key:             bugprone-narrowing-conversions.WarnOnFloatingPointNarrowingConversion
+    value:           'true'
+  - key:             bugprone-signed-char-misuse.CharTypdefsToIgnore
+    value:           ''
+  - key:             bugprone-argument-comment.CommentStringLiterals
+    value:           '0'
+  - key:             bugprone-narrowing-conversions.PedanticMode
+    value:           'false'
+  - key:             bugprone-sizeof-expression.WarnOnSizeOfConstant
+    value:           'true'
+  - key:             bugprone-assert-side-effect.IgnoredFunctions
+    value:           __builtin_expect
+  - key:             bugprone-argument-comment.CommentBoolLiterals
+    value:           '0'
+  - key:             bugprone-argument-comment.CommentUserDefinedLiterals
+    value:           '0'
+  - key:             cert-str34-c.DiagnoseSignedUnsignedCharComparisons
+    value:           'false'
+  - key:             bugprone-narrowing-conversions.WarnWithinTemplateInstantiation
+    value:           'false'
+  - key:             cert-err33-c.CheckedFunctions
+    value:           '::aligned_alloc;::asctime_s;::at_quick_exit;::atexit;::bsearch;::bsearch_s;::btowc;::c16rtomb;::c32rtomb;::calloc;::clock;::cnd_broadcast;::cnd_init;::cnd_signal;::cnd_timedwait;::cnd_wait;::ctime_s;::fclose;::fflush;::fgetc;::fgetpos;::fgets;::fgetwc;::fopen;::fopen_s;::fprintf;::fprintf_s;::fputc;::fputs;::fputwc;::fputws;::fread;::freopen;::freopen_s;::fscanf;::fscanf_s;::fseek;::fsetpos;::ftell;::fwprintf;::fwprintf_s;::fwrite;::fwscanf;::fwscanf_s;::getc;::getchar;::getenv;::getenv_s;::gets_s;::getwc;::getwchar;::gmtime;::gmtime_s;::localtime;::localtime_s;::malloc;::mbrtoc16;::mbrtoc32;::mbsrtowcs;::mbsrtowcs_s;::mbstowcs;::mbstowcs_s;::memchr;::mktime;::mtx_init;::mtx_lock;::mtx_timedlock;::mtx_trylock;::mtx_unlock;::printf_s;::putc;::putwc;::raise;::realloc;::remove;::rename;::scanf;::scanf_s;::setlocale;::setvbuf;::signal;::snprintf;::snprintf_s;::sprintf;::sprintf_s;::sscanf;::sscanf_s;::strchr;::strerror_s;::strftime;::strpbrk;::strrchr;::strstr;::strtod;::strtof;::strtoimax;::strtok;::strtok_s;::strtol;::strtold;::strtoll;::strtoul;::strtoull;::strtoumax;::strxfrm;::swprintf;::swprintf_s;::swscanf;::swscanf_s;::thrd_create;::thrd_detach;::thrd_join;::thrd_sleep;::time;::timespec_get;::tmpfile;::tmpfile_s;::tmpnam;::tmpnam_s;::tss_create;::tss_get;::tss_set;::ungetc;::ungetwc;::vfprintf;::vfprintf_s;::vfscanf;::vfscanf_s;::vfwprintf;::vfwprintf_s;::vfwscanf;::vfwscanf_s;::vprintf_s;::vscanf;::vscanf_s;::vsnprintf;::vsnprintf_s;::vsprintf;::vsprintf_s;::vsscanf;::vsscanf_s;::vswprintf;::vswprintf_s;::vswscanf;::vswscanf_s;::vwprintf_s;::vwscanf;::vwscanf_s;::wcrtomb;::wcschr;::wcsftime;::wcspbrk;::wcsrchr;::wcsrtombs;::wcsrtombs_s;::wcsstr;::wcstod;::wcstof;::wcstoimax;::wcstok;::wcstok_s;::wcstol;::wcstold;::wcstoll;::wcstombs;::wcstombs_s;::wcstoul;::wcstoull;::wcstoumax;::wcsxfrm;::wctob;::wctrans;::wctype;::wmemchr;::wprintf_s;::wscanf;::wscanf_s;'
+  - key:             bugprone-suspicious-string-compare.WarnOnLogicalNotComparison
+    value:           'false'
+  - key:             google-readability-braces-around-statements.ShortStatementLines
+    value:           '1'
+  - key:             bugprone-reserved-identifier.AllowedIdentifiers
+    value:           ''
+  - key:             bugprone-signal-handler.AsyncSafeFunctionSet
+    value:           POSIX
+  - key:             bugprone-suspicious-string-compare.WarnOnImplicitComparison
+    value:           'true'
+  - key:             bugprone-argument-comment.CommentNullPtrs
+    value:           '0'
+  - key:             bugprone-narrowing-conversions.WarnOnIntegerToFloatingPointNarrowingConversion
+    value:           'true'
+  - key:             bugprone-argument-comment.StrictMode
+    value:           '0'
+  - key:             bugprone-misplaced-widening-cast.CheckImplicitCasts
+    value:           'false'
+  - key:             bugprone-suspicious-missing-comma.RatioThreshold
+    value:           '0.200000'
+  - key:             modernize-loop-convert.MinConfidence
+    value:           reasonable
+  - key:             bugprone-unhandled-self-assignment.WarnOnlyIfThisHasSuspiciousField
+    value:           'true'
+  - key:             google-readability-namespace-comments.ShortNamespaceLines
+    value:           '10'
+  - key:             google-readability-namespace-comments.SpacesBeforeComments
+    value:           '2'
+  - key:             cppcoreguidelines-non-private-member-variables-in-classes.IgnoreClassesWithAllMemberVariablesBeingPublic
+    value:           'true'
+  - key:             bugprone-argument-comment.IgnoreSingleArgument
+    value:           '0'
+  - key:             bugprone-suspicious-string-compare.StringCompareLikeFunctions
+    value:           ''
+  - key:             bugprone-narrowing-conversions.WarnOnEquivalentBitWidth
+    value:           'true'
+  - key:             bugprone-sizeof-expression.WarnOnSizeOfIntegerExpression
+    value:           'false'
+  - key:             bugprone-assert-side-effect.CheckFunctionCalls
+    value:           'false'
+  - key:             bugprone-narrowing-conversions.IgnoreConversionFromTypes
+    value:           ''
+  - key:             bugprone-string-constructor.StringNames
+    value:           '::std::basic_string;::std::basic_string_view'
+  - key:             bugprone-assert-side-effect.AssertMacros
+    value:           assert,NSAssert,NSCAssert
+  - key:             bugprone-exception-escape.IgnoredExceptions
+    value:           ''
+  - key:             bugprone-signed-char-misuse.DiagnoseSignedUnsignedCharComparisons
+    value:           'true'
+  - key:             llvm-qualified-auto.AddConstToQualified
+    value:           'false'
+  - key:             bugprone-narrowing-conversions.WarnOnIntegerNarrowingConversion
+    value:           'true'
+  - key:             modernize-loop-convert.NamingStyle
+    value:           CamelCase
+  - key:             bugprone-suspicious-include.ImplementationFileExtensions
+    value:           'c;cc;cpp;cxx'
+  - key:             bugprone-suspicious-missing-comma.SizeThreshold
+    value:           '5'
+  - key:             bugprone-suspicious-include.HeaderFileExtensions
+    value:           ';h;hh;hpp;hxx'
+  - key:             google-readability-function-size.StatementThreshold
+    value:           '800'
+  - key:             llvm-else-after-return.WarnOnConditionVariables
+    value:           'false'
+  - key:             bugprone-argument-comment.CommentCharacterLiterals
+    value:           '0'
+  - key:             bugprone-argument-comment.CommentIntegerLiterals
+    value:           '0'
+  - key:             bugprone-stringview-nullptr.IncludeStyle
+    value:           llvm
+  - key:             bugprone-sizeof-expression.WarnOnSizeOfCompareToConstant
+    value:           'true'
+  - key:             modernize-pass-by-value.IncludeStyle
+    value:           llvm
+  - key:             bugprone-reserved-identifier.AggressiveDependentMemberLookup
+    value:           'false'
+  - key:             bugprone-sizeof-expression.WarnOnSizeOfThis
+    value:           'true'
+  - key:             bugprone-string-constructor.WarnOnLargeLength
+    value:           'true'
+  - key:             bugprone-too-small-loop-variable.MagnitudeBitsUpperLimit
+    value:           '16'
+  - key:             bugprone-argument-comment.CommentFloatLiterals
+    value:           '0'
+  - key:             modernize-use-nullptr.NullMacros
+    value:           'NULL'
+  - key:             bugprone-dangling-handle.HandleClasses
+    value:           'std::basic_string_view;std::experimental::basic_string_view'
+  - key:             bugprone-dynamic-static-initializers.HeaderFileExtensions
+    value:           ';h;hh;hpp;hxx'
+  - key:             bugprone-suspicious-enum-usage.StrictMode
+    value:           'false'
+  - key:             bugprone-implicit-widening-of-multiplication-result.IncludeStyle
+    value:           llvm
+  - key:             bugprone-suspicious-missing-comma.MaxConcatenatedTokens
+    value:           '5'
+  - key:             bugprone-implicit-widening-of-multiplication-result.UseCXXHeadersInCppSources
+    value:           'true'
+  - key:             llvm-else-after-return.WarnOnUnfixable
+    value:           'false'
+  - key:             bugprone-not-null-terminated-result.WantToUseSafeFunctions
+    value:           'true'
+...
+

AGENTS.md

@@ -0,0 +1,108 @@
+# AGENTS
+
+Project type: Arduino library that can be compiled for Linux and the Pico SDK.
+
+## Building docs
+
+requires: [doxygen]
+
+steps:
+
+- `cd docs`
+- `doxygen`
+- optional: open `docs/html/index.html`
+
+## Build/Install library
+
+requires: `cmake`, build tools (and `sudo` for install)
+
+steps:
+
+- `cmake -B build -S . [...cmake options]`
+- `cmake --build build`
+- `sudo cmake --install build` (required to build Linux examples)
+
+### Build environment & dependency ordering
+
+- Dependency ordering (use git HEAD of `master` unless specified):
+  1. [RF24] (build & install)
+  2. `RF24Network` (build)
+- Example commands to install dependencies from source (repeat for each
+  dependency):
+  - `git clone <repo> && cd <repo>`
+  - `cmake -B build -S .`
+  - `cmake --build build`
+  - `sudo cmake --install build`
+
+## Examples (RPi/Linux)
+
+requires: `cmake`, build tools
+
+steps:
+
+- `cmake -B examples_RPi/build examples_RPi [...cmake options]`
+- `cmake --build examples_RPi/build`
+
+## Pico SDK examples
+
+requires: `cmake`, [PicoSDK] (Windows: `ninja` may be required)
+
+steps:
+
+- `cmake -B examples_pico/build examples_pico [...cmake opts]`
+- `cmake --build examples_pico/build`
+
+### About [RF24] dependency
+
+The `examples_pico/CMakeLists.txt` expects [RF24] repo checked out adjacent to
+this repo's root folder. Unless otherwise noted, [RF24] master branch tip is
+used.
+
+## Install Python wrapper
+
+requires:
+
+- `python`, `pip`, and Python C API headers
+- `boost.python` (typically provided via `apt-get install`)
+
+steps:
+
+- Create a venv (can be done with various tools). Need only be done once.
+- Activate the venv (depends on method used in previous step), if not already in
+  active venv.
+- `pip install -v ./RPi/pyRF24Network`
+
+Notes about dependencies:
+
+- Most dependencies can be installed via
+  `apt-get install python3-dev libboost-python-dev`.
+- The [RF24] (C++ lib) is required to be installed beforehand too.
+
+## Format sources
+
+requires: `clang-format` v14.x
+
+steps:
+
+- `clang-format-14 -i --style=file <file>`
+- On Windows (powershell does not expand globs):
+  `clang-format -i --style=file <file>`
+
+## Clang-tidy / static analysis
+
+Note: clang-tidy can only be used when targeting Linux builds. Prefer WSL when
+building on a Windows host machine.
+
+- To generate a compilation database required by `clang-tidy`:
+  - `cmake -B build -S . -DCMAKE_EXPORT_COMPILE_COMMANDS=ON`
+- Run `clang-tidy` with the `-p` option pointing to the build directory:
+  - `clang-tidy -p build <files>`
+
+Notes about [RF24] dependency:
+
+- By default the CMakeLists will `find_library(RF24 rf24 REQUIRED)`
+- To build RF24Network, [RF24] needs to be installed.
+
+[RF24]: https://github.com/nRF24/RF24
+[PicoSDK]: https://github.com/raspberrypi/pico-sdk
+[doxygen]: https://github.com/doxygen/doxygen