trail-mate/docs/engineering/tmap-dependency.md

Released TMAP dependency

Trail Mate consumes the independent TMAP SDK as a third-party dependency. The application owns filesystem/storage adapters, UI policy and task scheduling. SDK readers and algorithms are not maintained as a second copy under modules/core_tmap.

Locked release

• Version: v0.1.1 (experimental pre-release).
• Commit: d8fc21550859bce1c242e6330b0e9ae2ddf9eecc.
• Source archive SHA-256: d8377999b30703e870f9e5dab09f7de89eb6474cc01930fc3d330de6e85acb77.
• License/provenance: upstream AGPL-3.0-only, LICENSE, COPYRIGHT and NOTICE.

PlatformIO declares the immutable Git dependency in platformio.ini and the consuming ui_map_runtime/library.json. This uses PlatformIO's normal package manager; no script copies headers into modules or relies on a sibling checkout.

CMake uses cmake/TrailMateTmap.cmake, which downloads the published source archive through FetchContent and verifies its SHA-256. Consumers link tmap::tmap; include directories and compile definitions propagate through the target. ESP-IDF links it after component registration, outside early dependency expansion. Linux common targets and native TMAP tests use the same helper.

Host producer tools, SDK test suites/examples and the SDK stdio adapter are disabled for application builds. Existing Trail Mate storage adapters remain the file-I/O owner. The upstream bounded-stack/no-exception configuration is enabled. The initial configure/install needs network access; subsequent builds reuse normal package-manager/FetchContent caches. CMake's documented FETCHCONTENT_SOURCE_DIR_TRAILMATE_TMAP override can use an explicitly supplied offline source tree; verify it matches the locked release before use.

Scope and compatibility

Existing map display/search still uses the v1 Reader API. Reader/search source content is preserved upstream; the SDK header's administrative adapter friend does not change Reader layout. The larger SDK is now available for subsequent outdoor feature requirements. Merely linking it does not add a routing UI or make existing firmware select outdoor-v2 files. MCU buffers, stacks and PSRAM allocation policy remain application integration responsibilities.

Native validation uses the released archive, tests administrative paths and links the profile/routing/admin interfaces, including external-memory failure. The dependency contract also checks that PlatformIO and CMake pins agree and that no old reader/search implementation is compiled. These three tests run without map datasets in the dedicated Released TMAP dependency CI workflow. Optional real world/China probes validate exact pixels, annotations, search, Busy, session changes, CRC, capacity, cancellation and storage ownership. The catalog test accounts separately for the reader workspace and metadata holding three annotation continuation slots; it drains incremental annotation snapshots.

On the tested 32-bit host ABI, the real-map probe retains a 14,024 B v1 Workspace and a 120 B Reader. The two-package catalog retains 25,368 B in two allocations, including existing annotation continuation metadata; it is not whole-device RAM. World/China pixels, annotations, indexed search and page counts match the recorded upstream baseline. The normalized reader/search source SHA-256 values match the original module as well. The optional real-map configuration passes six tests.

cmake -S tests/tmap -B .codex-build/tmap-dependency -DCMAKE_BUILD_TYPE=Release
cmake --build .codex-build/tmap-dependency
ctest --test-dir .codex-build/tmap-dependency --output-on-failure

Set TRAILMATE_TMAP_WORLD_MAP and TRAILMATE_TMAP_CHINA_MAP to local matching real files to enable the additional three data-dependent tests. These large datasets are not vendored or downloaded by the dependency helper.

For upgrades, verify a published release and CI, update both PlatformIO pins and the CMake version/commit/archive hash together, then rerun native contracts and the target firmware build. Never substitute a moving branch or edit files in .pio/libdeps / _deps as the integration source of truth.

Target build evidence

The tlora_pager_sx1262 PlatformIO build completed successfully on 2026-10-15 using the installed PlatformIO 6.2.0 environment. The dependency graph reports tmap @ 0.1.1+sha.d8fc215 and its checkout resolves to the locked full commit. Compiler dependencies resolve tmap/reader.h from the managed SDK package. The final firmware map contains only reader.cpp.o and search.cpp.o from libtmap.a, with no libcore_tmap.a. Unused outdoor/routing archive objects are not pulled into the current application by this dependency migration.

The successful build reports 97,356 B static RAM and 4,662,485 B Flash. These are whole-build linker figures for this working branch, not an isolated TMAP delta, dynamic heap/PSRAM peak or hardware measurement. No device was flashed. The earlier attempt with a different local PlatformIO 6.1.19 installation failed on a SCons tool-module import before compilation; it is not counted as success. Native CMake validation includes all six optional real-map tests. Full Linux application and ESP-IDF firmware builds remain separate target checks; their build entrypoints now link the same pinned dependency through CMake.