mirror of
https://github.com/vicliu624/trail-mate.git
synced 2026-11-04 11:17:31 +00:00
92 lines
5.2 KiB
Markdown
92 lines
5.2 KiB
Markdown
# Released TMAP dependency
|
|
|
|
Trail Mate consumes the independent [TMAP SDK](https://github.com/vicliu624/tmap)
|
|
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.
|
|
|
|
```sh
|
|
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.
|