diff --git a/.clang-tidy b/.clang-tidy new file mode 100644 index 00000000..3f212753 --- /dev/null +++ b/.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' +... + diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..33bd43f8 --- /dev/null +++ b/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 && cd ` + - `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 ` +- On Windows (powershell does not expand globs): + `clang-format -i --style=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 ` + +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