Build, test and check the libraries on their own

.clang-format

@@ -0,0 +1,51 @@
+---
+Language:        Cpp
+BasedOnStyle:    LLVM
+AccessModifierOffset: -4
+AlignAfterOpenBracket: BlockIndent
+AlignConsecutiveBitFields:
+  Enabled:         true
+  PadOperators:    true
+AlignConsecutiveDeclarations:
+  Enabled:         true
+  PadOperators:    true
+AlignConsecutiveMacros:
+  PadOperators:    true
+AlignEscapedNewlines: Left
+AllowShortBlocksOnASingleLine: Empty
+AllowShortEnumsOnASingleLine: false
+AllowShortFunctionsOnASingleLine: Inline
+AlwaysBreakTemplateDeclarations: Yes
+BreakBeforeTernaryOperators: false
+BreakConstructorInitializers: AfterColon
+BreakInheritanceList: AfterColon
+ColumnLimit:     120
+EmptyLineBeforeAccessModifier: Always
+IncludeCategories:
+  - Regex:           '^<.*>'
+    Priority:        1
+    SortPriority:    1
+  - Regex:           '^".*"'
+    SortPriority:    2
+# No include is treated as the main header, so that sorting preserves the existing
+# grouping instead of promoting the header matching the source file name
+IncludeIsMainRegex: 'NO_MAIN_INCLUDE'
+IndentCaseLabels: true
+IndentExternBlock: NoIndent
+IndentPPDirectives: BeforeHash
+IndentRequiresClause: false
+IndentWidth:     4
+IndentWrappedFunctionNames: true
+InsertNewlineAtEOF: true
+KeepEmptyLinesAtTheStartOfBlocks: false
+LineEnding:      LF
+PackConstructorInitializers: NextLine
+PointerAlignment: Left
+SeparateDefinitionBlocks: Always
+ShortNamespaceLines: 0
+SortIncludes:    CaseSensitive
+SpaceInEmptyBlock: true
+SpacesBeforeTrailingComments: 2
+Standard:        Latest
+TabWidth:        4
+...

.clang-tidy

@@ -0,0 +1,79 @@
+---
+# llvm-include-order enforces LLVM's own ordering, which contradicts the project's
+# .clang-format rules; clang-format is the single authority on include order here.
+#
+# The trailing group disables checks for constructs this project cannot contain. They match
+# nothing, so they only cost time scanning the standard library and the Cube headers:
+#   string_view, coroutines, Objective-C, GoogleTest, the LLVM internal APIs, std::bind,
+#   iostreams, std::auto_ptr and std::random_shuffle (both removed in C++17), and printf.
+# It also drops clang-analyzer-core.FixedAddressDereference, which every memory mapped
+# peripheral access looks like by construction.
+Checks:
+  -*,
+  bugprone-*,
+  -bugprone-easily-swappable-parameters,
+  -bugprone-dynamic-static-initializers,
+  -bugprone-bitwise-pointer-cast,
+  clang-*,
+  cppcoreguidelines-*,
+  -cppcoreguidelines-avoid-magic-numbers,
+  -cppcoreguidelines-avoid-do-while,
+  -cppcoreguidelines-narrowing-conversions,
+  -cppcoreguidelines-pro-type-union-access,
+  google-*,
+  llvm-*,
+  -llvm-header-guard,
+  -llvm-include-order,
+  misc-*,
+  -misc-use-anonymous-namespace,
+  modernize-*,
+  -modernize-use-nodiscard,
+  -modernize-use-trailing-return-type,
+  performance-*,
+  readability-*,
+  -readability-duplicate-include,
+  -readability-magic-numbers,
+  -readability-math-missing-parentheses,
+  -bugprone-stringview-nullptr,
+  -cppcoreguidelines-no-suspend-with-lock,
+  -google-objc-*,
+  -google-upgrade-googletest-case,
+  -llvm-prefer-isa-or-dyn-cast-in-conditionals,
+  -llvm-prefer-register-over-unsigned,
+  -llvm-twine-local,
+  -modernize-avoid-bind,
+  -modernize-deprecated-ios-base-aliases,
+  -modernize-replace-auto-ptr,
+  -modernize-replace-random-shuffle,
+  -modernize-use-std-print,
+  -clang-analyzer-core.FixedAddressDereference,
+HeaderFileExtensions:
+  - ''
+  - h
+  - hh
+  - hpp
+  - hxx
+ImplementationFileExtensions:
+  - c
+  - cc
+  - cpp
+  - cxx
+HeaderFilterRegex: '(include|config)/.*\.(hpp|tpp)$'
+ExcludeHeaderFilterRegex: '(_deps|external)/'
+FormatStyle: file
+CheckOptions:
+  # The vendor HAL module headers are not standalone; they require stm32<family>xx_hal.h to have
+  # pulled in stm32<family>xx_hal_def.h first, so include-cleaner must not suggest or remove them.
+  # This is why micras_hal includes the generated main.h, which reaches the right one for the
+  # family it was generated for, instead of naming a module header of its own. main.h is on the
+  # list for the same reason: every symbol behind it resolves to a header already listed here, so
+  # nothing is credited to main.h and it would otherwise be reported as unused.
+  misc-include-cleaner.IgnoreHeaders: 'stm32.*;core_cm.*;cmsis.*;system_stm32.*;lsm6dsv.*;main\.h'
+  readability-identifier-length.MinimumVariableNameLength: 2
+  readability-identifier-length.IgnoredVariableNames: ^[nxyz]$
+  readability-identifier-length.MinimumParameterNameLength: 2
+  readability-identifier-length.IgnoredParameterNames: ^[nxyz]$
+  misc-non-private-member-variables-in-classes.IgnoreClassesWithAllMemberVariablesBeingPublic: true
+  bugprone-narrowing-conversions.WarnOnIntegerToFloatingPointNarrowingConversion: false
+SystemHeaders: false
+...

.docker/Dockerfile

@@ -0,0 +1,103 @@
+# syntax=docker/dockerfile:1.27
+
+# >>> host stage >>>
+###############################################################################
+# Host tools: shared byte for byte by micras-lib, micras-simulation and       #
+# MicrasFirmware, whose CI compares the lines between the two markers         #
+###############################################################################
+FROM ubuntu:26.04 AS host
+
+# The compilers and the clang tooling are pinned to a major version, so that a distribution update
+# can move neither the generated code nor the formatting rules and the enabled check set
+ARG HOST_GCC_VERSION=15
+ARG HOST_CLANG_VERSION=22
+
+# The apt caches are kept in BuildKit cache mounts instead of the image layers, so the hook that
+# deletes the downloaded packages after every install has to go
+RUN rm -f /etc/apt/apt.conf.d/docker-clean
+
+RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    apt-get update && \
+    apt-get install -y --no-install-recommends \
+        ca-certificates \
+        cmake \
+        doxygen \
+        git \
+        graphviz \
+        ninja-build \
+        python3 \
+        python3-matplotlib \
+        python3-numpy \
+        "gcc-${HOST_GCC_VERSION}" \
+        "g++-${HOST_GCC_VERSION}" \
+        "clang-${HOST_CLANG_VERSION}" \
+        "clang-format-${HOST_CLANG_VERSION}" \
+        "clang-tidy-${HOST_CLANG_VERSION}"
+
+WORKDIR /project
+# <<< host stage <<<
+
+#############################################################
+# Reference projects' Cube files, generated by STM32CubeMX #
+#############################################################
+FROM thunderatz/stm32cubemx:6.18.1-h7 AS generator-h7
+
+WORKDIR /project
+COPY reference/h7/reference.ioc reference/h7/
+
+# Without network, CubeMX skips its online update check, which can hang the project generation. The
+# CMakeLists.txt and CMakePresets.json CubeMX writes next to the .ioc are its own suggestion of a
+# project, which the reference replaces, so they are left out of the generated tree.
+RUN --network=none <<EOT
+    set -e
+    printf 'config load /project/reference/h7/reference.ioc\nproject generate\nexit\n' > /tmp/cube_script
+    xvfb-run --auto-servernum "${CUBE_PATH}/STM32CubeMX" -q /tmp/cube_script
+    rm /tmp/cube_script
+    test -f reference/h7/cmake/stm32cubemx/CMakeLists.txt || { echo "STM32CubeMX failed to generate the project" >&2; exit 1; }
+    rm -f reference/h7/CMakeLists.txt reference/h7/CMakePresets.json reference/h7/reference.ioc
+EOT
+
+# Only the generated files, can be replaced by already generated ones with --build-context generated-h7=<dir>
+FROM scratch AS generated-h7
+
+COPY --from=generator-h7 /project/reference/h7 /
+
+FROM thunderatz/stm32cubemx:6.18.1-g4 AS generator-g4
+
+WORKDIR /project
+COPY reference/g4/reference.ioc reference/g4/
+
+# The same generation as the H7 reference's, with the STM32CubeMX image that carries the G4 package
+RUN --network=none <<EOT
+    set -e
+    printf 'config load /project/reference/g4/reference.ioc\nproject generate\nexit\n' > /tmp/cube_script
+    xvfb-run --auto-servernum "${CUBE_PATH}/STM32CubeMX" -q /tmp/cube_script
+    rm /tmp/cube_script
+    test -f reference/g4/cmake/stm32cubemx/CMakeLists.txt || { echo "STM32CubeMX failed to generate the project" >&2; exit 1; }
+    rm -f reference/g4/CMakeLists.txt reference/g4/CMakePresets.json reference/g4/reference.ioc
+EOT
+
+# Only the generated files, can be replaced by already generated ones with --build-context generated-g4=<dir>
+FROM scratch AS generated-g4
+
+COPY --from=generator-g4 /project/reference/g4 /
+
+##########################################################
+# ARM toolchain for the reference projects and benches   #
+##########################################################
+FROM host AS stm32
+
+# The ARM libraries come prebuilt for every ARM core, only the Cortex-M4F and Cortex-M7 double
+# precision ones are kept
+RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \
+    --mount=type=cache,target=/var/lib/apt,sharing=locked \
+    apt-get update && \
+    apt-get install -y --no-install-recommends \
+        gcc-arm-none-eabi \
+        libnewlib-arm-none-eabi \
+        libstdc++-arm-none-eabi-newlib \
+        make && \
+    find /usr/lib/arm-none-eabi/lib/thumb /usr/lib/gcc/arm-none-eabi/*/thumb -mindepth 1 -maxdepth 1 \
+        -not -name "v7e-m+fp" -not -name "v7e-m+dp" -exec rm -rf {} + && \
+    rm -rf /usr/lib/arm-none-eabi/lib/arm /usr/lib/gcc/arm-none-eabi/*/arm

.docker/Dockerfile.dockerignore

@@ -0,0 +1,6 @@
+# The images need no source: the CI mounts the checkout into the containers it runs
+.git/
+build/
+docs/
+reference/*/*
+!reference/*/reference.ioc

.gitattributes

@@ -0,0 +1,17 @@
+# Every text file is stored with LF in the repository and checked out with LF, whatever platform
+# wrote it.
+#
+# The files this exists for are reference/*/reference.ioc. STM32CubeMX writes its project file with
+# the line endings of the platform it runs on, CRLF from a Windows install and LF from the Linux
+# container the CI uses, so without normalization the same regeneration shows up as a whole file
+# rewrite depending on who ran it, burying the handful of settings that actually changed.
+* text=auto eol=lf
+
+# Binary types, so that git never rewrites them
+*.png binary
+*.jpg binary
+*.pdf binary
+*.ico binary
+*.bin binary
+*.elf binary
+*.hex binary

.github/workflows/ci.yaml

@@ -0,0 +1,128 @@
+name: Build test lint and check formatting
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: true
+
+# A push to a branch of this repository is checked once by its push run, so a pull request only runs
+# here when it comes from a fork
+jobs:
+  host:
+    name: 🧪 Host build, tests, format, lint and docs
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository
+    timeout-minutes: 45
+    steps:
+      - name: 🔀 Checkout
+        uses: actions/checkout@v7
+
+      - name: 🐋 Build the host image
+        run: docker build --file .docker/Dockerfile --target host --tag micras-lib:host .
+
+      - name: 🗃️ Restore the fetched dependencies
+        uses: actions/cache@v6
+        with:
+          path: |
+            build/host/_deps
+            build/host/CMakeFiles/fc-stamp
+          key: deps-host-${{ hashFiles('micras_proxy/CMakeLists.txt', 'tests/CMakeLists.txt', 'cmake/micras_docs.cmake') }}
+
+      # One long lived container runs every step below, as the user that owns the checkout
+      - name: 📦 Start the host container
+        run: >
+          docker run --detach --name host --user "$(id -u):$(id -g)" --env HOME=/tmp
+          --volume "$PWD:/project" --workdir /project micras-lib:host sleep infinity
+
+      - name: ⚙️ Configure
+        run: docker exec host cmake --preset host -DMICRAS_LIB_WERROR=ON
+
+      - name: 🔨 Build
+        run: docker exec host cmake --build --preset host
+
+      - name: 🧪 Run the tests
+        run: docker exec host ctest --preset host
+
+      - name: 🎨 Check the formatting
+        run: docker exec host cmake --build --preset host --target format_check
+
+      - name: 🚨 Lint
+        run: docker exec host cmake --build --preset host --target lint
+
+      - name: 📝 Build the documentation
+        run: docker exec host cmake --build --preset host --target docs
+
+      - name: 🔍 Check the shared code for chip macros
+        run: docker exec host scripts/check_no_chip_macros.sh
+
+      - name: 🧹 Stop the host container
+        if: always()
+        run: docker rm --force host
+
+  stm32:
+    name: 🔩 ${{ matrix.name }} reference and bench
+    runs-on: ubuntu-latest
+    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name != github.repository
+    timeout-minutes: 45
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - family: h7
+            name: STM32H7
+          - family: g4
+            name: STM32G4
+    steps:
+      - name: 🔀 Checkout
+        uses: actions/checkout@v7
+
+      - name: 🗃️ Restore the generated Cube files
+        id: cube
+        uses: actions/cache/restore@v6
+        with:
+          path: build/generated-${{ matrix.family }}
+          key: cube-${{ matrix.family }}-${{ hashFiles(format('reference/{0}/reference.ioc', matrix.family), '.docker/Dockerfile') }}
+
+      - name: ⚙️ Generate the Cube files
+        if: steps.cube.outputs.cache-hit != 'true'
+        run: >
+          docker build --file .docker/Dockerfile --target generated-${{ matrix.family }}
+          --output type=local,dest=build/generated-${{ matrix.family }} .
+
+      - name: 🗃️ Save the generated Cube files
+        if: steps.cube.outputs.cache-hit != 'true'
+        uses: actions/cache/save@v6
+        with:
+          path: build/generated-${{ matrix.family }}
+          key: ${{ steps.cube.outputs.cache-primary-key }}
+
+      - name: 📂 Place the Cube files in the reference project
+        run: cp -r build/generated-${{ matrix.family }}/. reference/${{ matrix.family }}/
+
+      - name: 🐋 Build the ARM image
+        run: docker build --file .docker/Dockerfile --target stm32 --tag micras-lib:stm32 .
+
+      - name: 📦 Start the ARM container
+        run: >
+          docker run --detach --name stm32 --user "$(id -u):$(id -g)" --env HOME=/tmp
+          --volume "$PWD:/project" --workdir /project micras-lib:stm32 sleep infinity
+
+      - name: ⚙️ Configure the reference project
+        run: docker exec stm32 cmake --preset reference-${{ matrix.family }}
+
+      - name: 🔨 Build the reference and its bench
+        run: docker exec stm32 cmake --build --preset reference-${{ matrix.family }} --parallel
+
+      - name: 🚨 Lint the stm32 backend and the bench
+        run: docker exec stm32 cmake --build --preset reference-${{ matrix.family }} --target lint
+
+      - name: 🧹 Stop the ARM container
+        if: always()
+        run: docker rm --force stm32

.gitignore

@@ -0,0 +1,2 @@
+build/
+docs/