Support linux-wire source-ingestion for Linux HAL builds

Author: CameronBrooks11

CMakeLists.txt

@@ -57,7 +57,17 @@ target_include_directories(crumbs
 # -----------------------------------------------------------------------------
 
 if(CRUMBS_ENABLE_LINUX_HAL)
-    find_package(linux_wire CONFIG REQUIRED)
+    if(NOT TARGET linux_wire::linux_wire)
+        if(TARGET linux_wire)
+            add_library(linux_wire::linux_wire INTERFACE IMPORTED)
+            set_target_properties(linux_wire::linux_wire PROPERTIES
+                INTERFACE_LINK_LIBRARIES linux_wire
+            )
+        else()
+            find_package(linux_wire CONFIG REQUIRED)
+        endif()
+    endif()
+
     target_link_libraries(crumbs PUBLIC linux_wire::linux_wire)
 endif()
 
@@ -211,3 +221,4 @@ install(FILES
     "${CMAKE_CURRENT_BINARY_DIR}/crumbsConfigVersion.cmake"
     DESTINATION ${config_install_dir}
 )
+

README.md

@@ -61,7 +61,7 @@ lib_deps = cameronbrooks11/CRUMBS@^0.11.0
 
 **Linux/Native:** CMake build (see [CONTRIBUTING.md](CONTRIBUTING.md))
 
-No external dependencies.
+Arduino and PlatformIO builds use the CRUMBS core with no extra dependencies. Linux HAL builds require `linux-wire` for I2C bus access.
 
 ## Hardware Requirements
 
@@ -118,3 +118,4 @@ Details: [platform-setup.md](docs/platform-setup.md)
 ## License
 
 GPL-3.0 - see [LICENSE](LICENSE) file for details.
+

docs/platform-setup.md

@@ -292,6 +292,34 @@ cmake -S . -B build -DCRUMBS_ENABLE_LINUX_HAL=ON \
 cmake --build build --parallel
 ```
 
+#### Long-term CMake Integration Pattern
+
+The canonical CMake dependency contract for Linux HAL consumers is the namespaced target `linux_wire::linux_wire`.
+
+Supported integration modes:
+
+- **Installed package**: `find_package(linux_wire CONFIG REQUIRED)` provides `linux_wire::linux_wire` directly.
+- **Sibling source ingestion**: add `linux-wire` before `CRUMBS` in the parent build. If a raw build-tree target named `linux_wire` already exists, `CRUMBS` creates a local bridge target named `linux_wire::linux_wire` and links against that.
+
+This preserves one canonical target name for `CRUMBS` while still supporting active multi-repo development.
+
+Parent-build example:
+
+```cmake
+cmake_minimum_required(VERSION 3.13)
+project(my_linux_stack C CXX)
+
+set(LINUX_WIRE_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
+set(CRUMBS_ENABLE_LINUX_HAL ON CACHE BOOL "" FORCE)
+set(CRUMBS_BUILD_EXAMPLES OFF CACHE BOOL "" FORCE)
+set(CRUMBS_ENABLE_TESTS OFF CACHE BOOL "" FORCE)
+
+add_subdirectory(../linux-wire linux_wire_subbuild)
+add_subdirectory(../CRUMBS crumbs_subbuild)
+```
+
+Avoid linking exported or installable CRUMBS targets directly to a raw `linux_wire` target. That breaks CMake export generation. The bridge or installed-package path is the stable pattern.
+
 ### Install CRUMBS
 
 ```bash
@@ -603,3 +631,4 @@ Once your platform is set up and basic communication is working:
 - [Protocol Specification](protocol.md) — Wire format and versioning
 - [Examples](examples.md) — Working code for all platforms
 - [Architecture](architecture.md) — Design decisions and internals
+