build: the submodule is how libavr arrives; the era already carries it

The pin the whole history now encodes becomes the primary route: the
submodule default replaces FetchContent and the unpinned forge fallback,
LIBAVR_ROOT stays as the tandem-development override, the presets already
take the toolchain file from the submodule, and the Studio projects anchor
their include path there — correct by construction. The version tags and
the one-command historical build are documented beside the version map.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

CMakeLists.txt

@@ -2,21 +2,19 @@ cmake_minimum_required(VERSION 3.28)
 
 project(tsb_libavr LANGUAGES CXX)
 
-# libavr from a local checkout (LIBAVR_ROOT) or the forge; the toolchain file
-# comes from the same checkout via CMakePresets.json.
-include(FetchContent)
+# libavr rides as the pinned submodule; LIBAVR_ROOT (cache or environment)
+# overrides it for tandem development against a working tree. The toolchain
+# file comes from the submodule via CMakePresets.json either way.
 if(NOT LIBAVR_ROOT AND DEFINED ENV{LIBAVR_ROOT})
 	set(LIBAVR_ROOT $ENV{LIBAVR_ROOT})
 endif()
 if(NOT LIBAVR_ROOT)
 	set(LIBAVR_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/libavr)
 endif()
-if(LIBAVR_ROOT)
-	FetchContent_Declare(libavr SOURCE_DIR ${LIBAVR_ROOT})
-else()
-	FetchContent_Declare(libavr GIT_REPOSITORY git@git.blackmark.me:avr/libavr.git GIT_TAG main)
+if(NOT EXISTS ${LIBAVR_ROOT}/CMakeLists.txt)
+	message(FATAL_ERROR "libavr not found at ${LIBAVR_ROOT} — run: git submodule update --init libavr")
 endif()
-FetchContent_MakeAvailable(libavr)
+add_subdirectory(${LIBAVR_ROOT} libavr-build)
 
 if(PROJECT_IS_TOP_LEVEL)
 	add_compile_options(-Werror) # warnings are errors for the port's own code

ide/README.md

@@ -40,14 +40,13 @@ flash, so the optimisation level stays where correctness needs it.
 
 ## What Studio needs from the machine
 
-libavr checked out **beside this repo**, found at
-`$(MSBuildProjectDirectory)\..\..\..\libavr\include` — anchored to the project,
-because a plain relative path resolves against the generated makefile's
-directory (the configuration's output directory), not the project's. There is no
-`LIBAVR_ROOT` escape hatch: a variable exported in a shell is invisible to Studio
-launched from the Start menu, and the failure reads as a missing
-`libavr/libavr.hpp`. Pinning libavr as a submodule is the better answer and is on
-libavr's task list.
+libavr from the **submodule**, found at
+`$(MSBuildProjectDirectory)\..\..\libavr\include` — correct by construction, and
+anchored to the project because a plain relative path resolves against the
+generated makefile's directory (the configuration's output directory), not the
+project's. There is no `LIBAVR_ROOT` escape hatch: a variable exported in a
+shell is invisible to Studio launched from the Start menu, and the failure reads
+as a missing `libavr/libavr.hpp` — which is what the submodule answers.
 
 A GCC 16.1 toolchain registered as flavour `avr-g++-16.1.0`, nothing older
 reaching `-std=c++26`.
@@ -60,9 +59,9 @@ per project checks the flags have not drifted (both from libavr's
 
 ```sh
 for name in pureboot tsb_asm; do
-    python ../libavr/tools/atmelstudio/componentinfo.py \
+    python libavr/tools/atmelstudio/componentinfo.py \
         "ide/$name/$name.componentinfo.xml" --device ATmega328P
-    python ../libavr/tools/atmelstudio/check-flags.py \
+    python libavr/tools/atmelstudio/check-flags.py \
         --solution ide/bootloader.atsln --project "$name" --target "$name" \
         --compile-commands build/atmega328p-generated/compile_commands.json \
         --log "build/as-$name.log"

ide/pureboot/pureboot.cppproj

@@ -60,7 +60,7 @@
         </avrgcccpp.compiler.symbols.DefSymbols>
         <avrgcccpp.compiler.directories.IncludePaths>
           <ListValues>
-            <Value>$(MSBuildProjectDirectory)\..\..\..\libavr\include</Value>
+            <Value>$(MSBuildProjectDirectory)\..\..\libavr\include</Value>
           </ListValues>
         </avrgcccpp.compiler.directories.IncludePaths>
         <avrgcccpp.compiler.optimization.level>Optimize for size (-Os)</avrgcccpp.compiler.optimization.level>
@@ -92,7 +92,7 @@
         </avrgcccpp.compiler.symbols.DefSymbols>
         <avrgcccpp.compiler.directories.IncludePaths>
           <ListValues>
-            <Value>$(MSBuildProjectDirectory)\..\..\..\libavr\include</Value>
+            <Value>$(MSBuildProjectDirectory)\..\..\libavr\include</Value>
           </ListValues>
         </avrgcccpp.compiler.directories.IncludePaths>
         <avrgcccpp.compiler.optimization.level>Optimize for size (-Os)</avrgcccpp.compiler.optimization.level>

ide/tsb_asm/tsb_asm.cppproj

@@ -57,7 +57,7 @@
         </avrgcccpp.compiler.symbols.DefSymbols>
         <avrgcccpp.compiler.directories.IncludePaths>
           <ListValues>
-            <Value>$(MSBuildProjectDirectory)\..\..\..\libavr\include</Value>
+            <Value>$(MSBuildProjectDirectory)\..\..\libavr\include</Value>
           </ListValues>
         </avrgcccpp.compiler.directories.IncludePaths>
         <avrgcccpp.compiler.optimization.level>Optimize for size (-Os)</avrgcccpp.compiler.optimization.level>
@@ -86,7 +86,7 @@
         </avrgcccpp.compiler.symbols.DefSymbols>
         <avrgcccpp.compiler.directories.IncludePaths>
           <ListValues>
-            <Value>$(MSBuildProjectDirectory)\..\..\..\libavr\include</Value>
+            <Value>$(MSBuildProjectDirectory)\..\..\libavr\include</Value>
           </ListValues>
         </avrgcccpp.compiler.directories.IncludePaths>
         <avrgcccpp.compiler.optimization.level>Optimize for size (-Os)</avrgcccpp.compiler.optimization.level>

pureboot/README.md

@@ -287,6 +287,14 @@ from `b`, and a command per memory (`R`/`W` flash, `r`/`w` EEPROM, `F` fuses).
 above; the shipped tool speaks both, choosing on the version it reads, so a
 deployed pureboot 4 stays drivable and self-updatable to 5.
 
+Every closed generation is tagged in this repo at its era's last commit — the
+commit just before the next version bump, so a tag holds everything its
+version ever gained — and each tag carries the `libavr/` submodule pinned to
+the libavr that loader was built against, as the whole libavr era does commit
+by commit. `git checkout v3 && git submodule update --init libavr` followed by
+the usual preset build therefore reproduces the v3 loader exactly; the open
+generation is `main`.
+
 Collapsing four command bodies into one transfer loop is what paid for the
 version: the data space, the host-issued SPM operations and the fuses now share
 the loop, the cursor and the argument decode that `R`/`r`/`w` each carried a
@@ -452,8 +460,11 @@ counts, the programming plan, update state handling and per-phase page counts.
 
 ## Tests
 
-`tools/check.sh` runs every chip's workflow (`--full` adds the reflect-mode
-builds of libavr's spot set; `tools/make_presets.py` regenerates the presets).
+libavr rides as the `libavr/` submodule (`git submodule update --init libavr`);
+`LIBAVR_ROOT` (cache or environment) overrides it for tandem development
+against a working tree. `tools/check.sh` runs every chip's workflow (`--full`
+adds the reflect-mode builds of libavr's spot set; `tools/make_presets.py`
+regenerates the presets).
 Per chip preset, `ctest` runs:
 
 - `pureboot.size` — the 510-byte (patched-vector) / 512-byte budget;

tools/check.sh

@@ -3,8 +3,8 @@
 # the simulator-driven protocol suites. --full adds the reflect-spot builds
 # (libavr's rule: reflect compiles are bounded to its spot set, never the
 # full matrix) and swaps the compact size matrix for the exhaustive
-# clock × baud × backend cross product. LIBAVR_ROOT must point at the libavr
-# checkout.
+# clock × baud × backend cross product. libavr resolves from the `libavr/`
+# submodule; LIBAVR_ROOT overrides it for a working tree.
 set -e
 cd "$(dirname "$0")/.."