build: libavr rides as the pinned submodule

The submodule replaces FetchContent and the unpinned forge fallback;
LIBAVR_ROOT stays as the tandem-development override, the presets take the
toolchain file from the submodule, and the Studio project's include path
anchors there — correct by construction.

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

.gitmodules

@@ -0,0 +1,3 @@
+[submodule "libavr"]
+	path = libavr
+	url = ../libavr.git

CMakeLists.txt

@@ -2,19 +2,19 @@ cmake_minimum_required(VERSION 3.28)
 
 project(ds3231 LANGUAGES CXX)
 
-# libavr comes from a local checkout (LIBAVR_ROOT cache/env variable) or,
-# failing that, straight from the forge. The toolchain file also lives in
-# that checkout — see 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(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 LIBAVR_ROOT)
+	set(LIBAVR_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/libavr)
 endif()
-FetchContent_MakeAvailable(libavr)
+if(NOT EXISTS ${LIBAVR_ROOT}/CMakeLists.txt)
+	message(FATAL_ERROR "libavr not found at ${LIBAVR_ROOT} — run: git submodule update --init libavr")
+endif()
+add_subdirectory(${LIBAVR_ROOT} libavr-build)
 
 add_library(ds3231 INTERFACE)
 target_include_directories(ds3231 INTERFACE ${CMAKE_CURRENT_SOURCE_DIR}/include)

CMakePresets.json

@@ -6,7 +6,7 @@
 			"hidden": true,
 			"generator": "Ninja",
 			"binaryDir": "${sourceDir}/build/${presetName}",
-			"toolchainFile": "$env{LIBAVR_ROOT}/cmake/avr-toolchain.cmake",
+			"toolchainFile": "${sourceDir}/libavr/cmake/avr-toolchain.cmake",
 			"cacheVariables": {
 				"CMAKE_BUILD_TYPE": "Release",
 				"CMAKE_EXPORT_COMPILE_COMMANDS": "ON",

README.md

@@ -14,10 +14,13 @@ auto now = rtc::read_clock();       // result<date_time>
 (void)rtc::set_alarm1({}, ds3231::alarm1_rate::once_per_second);
 ```
 
-`example/main.cpp` is the full tour. Build with a libavr checkout:
+`example/main.cpp` is the full tour. libavr rides as the `libavr/` submodule,
+pinned to the commit this driver builds against; `LIBAVR_ROOT` (cache or
+environment) overrides it for development against a working tree:
 
 ```sh
-LIBAVR_ROOT=/path/to/libavr cmake --preset attiny85-generated
+git submodule update --init libavr
+cmake --preset attiny85-generated
 cmake --build --preset attiny85-generated
 ```
 
@@ -39,13 +42,14 @@ dir>/<Configuration>` whatever `OutputDirectory` says, so two projects sharing
 one directory would also share one `example/main.o`, and building one after the
 other without a rebuild would link the other part's object.
 
-Studio expects libavr checked out **beside this repo** and finds it at
-`$(MSBuildProjectDirectory)\..\..\libavr\include` — anchored to the project,
-because a plain relative path is resolved 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. It also needs a GCC 16.1 toolchain registered as
-flavour `avr-g++-16.1.0`, nothing older reaching `-std=c++26`.
+Studio finds libavr in the **submodule** at
+`$(MSBuildProjectDirectory)\..\..\libavr\include` — correct by construction,
+and anchored to the project because a plain relative path is resolved 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 — which is what the
+submodule answers. It also needs a GCC 16.1 toolchain registered as flavour
+`avr-g++-16.1.0`, nothing older reaching `-std=c++26`.
 
 One generated file is required before the project will load, and one command
 checks the flags have not drifted (both from libavr's `tools/atmelstudio/`):
@@ -53,9 +57,9 @@ checks the flags have not drifted (both from libavr's `tools/atmelstudio/`):
 ```sh
 for mcu in atmega328p attiny85; do
     case $mcu in atmega328p) device=ATmega328P;; attiny85) device=ATtiny85;; esac
-    python ../libavr/tools/atmelstudio/componentinfo.py \
+    python libavr/tools/atmelstudio/componentinfo.py \
         "ide/$mcu/ds3231-$mcu.componentinfo.xml" --device "$device"
-    python ../libavr/tools/atmelstudio/check-flags.py --solution ide/ds3231.atsln \
+    python libavr/tools/atmelstudio/check-flags.py --solution ide/ds3231.atsln \
         --project "ds3231-$mcu" \
         --compile-commands "build/$mcu-generated/compile_commands.json" \
         --log "build/as-$mcu.log"

ide/atmega328p/ds3231-atmega328p.cppproj

@@ -46,7 +46,7 @@
         <avrgcccpp.compiler.directories.IncludePaths>
           <ListValues>
             <Value>$(MSBuildProjectDirectory)\..\..\include</Value>
-            <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>
@@ -76,7 +76,7 @@
         <avrgcccpp.compiler.directories.IncludePaths>
           <ListValues>
             <Value>$(MSBuildProjectDirectory)\..\..\include</Value>
-            <Value>$(MSBuildProjectDirectory)\..\..\..\libavr\include</Value>
+            <Value>$(MSBuildProjectDirectory)\..\..\libavr\include</Value>
           </ListValues>
         </avrgcccpp.compiler.directories.IncludePaths>
         <avrgcccpp.compiler.optimization.level>Optimize debugging experience (-Og)</avrgcccpp.compiler.optimization.level>

ide/attiny85/ds3231-attiny85.cppproj

@@ -46,7 +46,7 @@
         <avrgcccpp.compiler.directories.IncludePaths>
           <ListValues>
             <Value>$(MSBuildProjectDirectory)\..\..\include</Value>
-            <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>
@@ -76,7 +76,7 @@
         <avrgcccpp.compiler.directories.IncludePaths>
           <ListValues>
             <Value>$(MSBuildProjectDirectory)\..\..\include</Value>
-            <Value>$(MSBuildProjectDirectory)\..\..\..\libavr\include</Value>
+            <Value>$(MSBuildProjectDirectory)\..\..\libavr\include</Value>
           </ListValues>
         </avrgcccpp.compiler.directories.IncludePaths>
         <avrgcccpp.compiler.optimization.level>Optimize debugging experience (-Og)</avrgcccpp.compiler.optimization.level>