地图应用示例壳工程，支持 macOS 和 Windows（MSYS2 MinGW64）主机仿真环境。
- FreeRTOS 仿真端口运行应用任务
- 链接预编译静态库完成地图渲染
- 可选 QuickJS（
scripts/demo.js）
默认地图区域 466×466。
依赖：Homebrew、SDL2、CMake、Ninja（scripts/setup_deps.sh 通过 Homebrew 安装）。
# 首次初始化依赖
./scripts/setup_deps.sh
# 构建并运行（使用仓库内置 libs/libmapsdk_posix.a）
./scripts/run_demo.sh -lib
# Debug 模式
./scripts/run_demo.sh -lib -debug产物：build/mapapp_demo。日志：logs/run_<timestamp>_<mode>.log。
依赖：MSYS2 MinGW64 环境。在 MSYS2 MinGW64 shell 中执行：
# 首次初始化依赖
./scripts/setup_deps_windows.sh
# 构建并运行（使用 libs/libmapsdk_posix_windows.a）
./scripts/run_demo.sh -lib
# Debug 模式
./scripts/run_demo.sh -lib -debug产物：build/mapapp_demo.exe。日志：logs/run_<timestamp>_<mode>.log。
AK 配置：在
src/app_config.h中填入MAPSDK_AK/MAPSDK_PACKAGE_NAME， 或通过编译选项传入：cmake … -DMAPSDK_AK="your_ak" -DMAPSDK_PACKAGE_NAME="your.package"
| 工程 | 职责 |
|---|---|
mapAPP |
SDL 主循环、适配层、SDK 对接 |
libs/libmapsdk_posix.a |
SDK 预编译静态库（macOS） |
libs/libmapsdk_posix_windows.a |
SDK 预编译静态库（Windows MinGW64） |
libs/freertos/ |
FreeRTOS Kernel 源码子集（内嵌，仓库自包含） |
FreeRTOS 源码位于 libs/freertos/，从 FreeRTOS 完整仓库 的 FreeRTOS/Source/ 目录提取。若该目录缺失，CMake 配置阶段会报错提示。
| 模块 | 说明 |
|---|---|
src/main.cpp |
SDL 主线程、窗口事件、渲染 Present |
src/freertos_app.cpp |
FreeRTOS 任务、地图渲染事件派发 |
src/map_runtime.cpp |
MapComponentApi 封装、Demo 入口 |
src/map_canvas_impl.cpp |
Canvas → SDL 绘制 |
src/mapsdk_network_stub.cpp |
libcurl；回调经 EnqueueMainThreadMapWork 在主线程串行 |
src/api_test.cpp / src/api_test/ |
Headless SDK API 回归测试入口 |
src/command/ |
Unix domain socket 命令控制模拟器（仅非 Windows 构建） |
平台适配：
- macOS：
src/adapter_impl/posix/ - Windows（MinGW64）：
src/adapter_impl/windows/
网络 TLS：
- macOS：libcurl + 系统证书
- Windows MinGW：libcurl +
build/certs/ca-bundle.crt（run_demo.sh 自动从 MinGW 环境同步）
地图资源： includes/v_config.h 中 ROOT_DIR → app/bd_map。
- Canvas 适配：
MapCanvasImpl继承CanvasContextCommonInterface，setCanvas注入SDL_Renderer*，setCanvasSize注入画布宽高（需与mapApi.SetSize保持一致）。 - AK 与包名：在
src/app_config.h中配置MAPSDK_AK/MAPSDK_PACKAGE_NAME，或通过编译选项-DMAPSDK_AK="..."覆盖。 - SDK 公开 API 参考：
docs/MAPAPP_DEMO.md
./scripts/tmux_demo.sh左侧运行 run_demo.sh -lib -debug，右上保留空终端，右下运行 control_demo_repl.sh；在右下输入 ping 会自动执行 scripts/control_demo.sh ping。
| 目标 | 文档 / 代码 |
|---|---|
| 跑通模拟器 | 本文 README |
| mapAPP 内置 Demo、扩展面板 | docs/MAPAPP_DEMO.md |
| 数据引擎线程安全（并发） | docs/data-engine-thread-safety.md |
构建会额外生成 mapapp_command，并在 mapapp_demo 启动时监听 /tmp/mapapp_demo_control.sock。可用脚本向运行中的模拟器发送命令，适合自动化冒烟测试、截图和导航进度等待。
./scripts/run_demo.sh -lib
# 另一个终端
./scripts/control_demo.sh ping
./scripts/control_demo.sh demo 7
./scripts/control_demo.sh set-center 116.397463 39.908736
./scripts/control_demo.sh set-zoom 16
./scripts/control_demo.sh set-rotation 30
./scripts/control_demo.sh screenshot logs/current.png
./scripts/control_demo.sh navi status
./scripts/control_demo.sh navi wait-progress 0.5 30000
./scripts/control_demo.sh quit支持命令：
- 通用：
ping、status、help、quit、screenshot [PATH] - 地图操作：
tap X Y、drag X1 Y1 X2 Y2 DURATION_MS、zoom-in、zoom-out、set-zoom ZOOM、set-center LNG LAT、set-rotation ANGLE、rotate-by DEGREES - Demo：
demo ID、demo list - 导航：
navi status、navi wait-progress TARGET [TIMEOUT_MS]、navi pause、navi resume、navi pause-toggle、navi stop - 离线包：
offline refresh、offline download CITY_NAME、offline delete CITY_NAME、offline list、offline status、offline list-cities - 路线瓦片：
route-tile download、route-tile cancel、route-tile delete、route-tile status、route-tile logs - 逆地理：
reverse-geocode LAT LON、reverse-geocode status、reverse-geocode body - POI：
poi-search nearby KEYWORD CENTER_LAT,CENTER_LNG RADIUS、poi-search select INDEX、poi-search status、poi-search results
右侧列表选 Demo → Confirm 执行。详见 docs/MAPAPP_DEMO.md。
| 问题 | 解决 |
|---|---|
| 找不到 libmapsdk_posix.a（macOS） | 确认 libs/libmapsdk_posix.a 存在（随仓库发布） |
| 找不到 libmapsdk_posix_windows.a（Windows） | 确认 libs/libmapsdk_posix_windows.a 存在（随仓库发布） |
| FreeRTOS not found（CMake 报错） | 确认 libs/freertos/tasks.c 存在；从 https://github.com/FreeRTOS/FreeRTOS.git 克隆后将 FreeRTOS/Source/ 内容复制到 libs/freertos/ |
| 地图不渲染 | 检查 includes/v_config.h 的 ROOT_DIR 与 app/bd_map |
| SIGALRM 崩溃 | main 已屏蔽主线程 SIGALRM，如仍复现请提 issue |
| AK 鉴权失败 | 检查 src/app_config.h 中 MAPSDK_AK / MAPSDK_PACKAGE_NAME 是否已填入有效值 |