Agus Maps Flutter - v0.1.23

Offline vector maps for Flutter powered by the CoMaps engine.

📖 Full Installation Guide

📦 Unified SDK (Recommended)

Download: agus-maps-sdk-v0.1.23.zip

Installation:

1. Download and extract agus-maps-sdk-v0.1.23.zip
2. Set environment variable:

   export AGUS_MAPS_HOME=/path/to/agus-maps-sdk-v0.1.23

3. Copy assets to your Flutter app:

   cp -r $AGUS_MAPS_HOME/assets/* your_app/assets/

4. Build your app

This SDK contains all platform binaries:

• android/prebuilt/{arm64-v8a,armeabi-v7a,x86_64}/
• ios/Frameworks/CoMaps.xcframework/
• macos/Frameworks/CoMaps.xcframework/
• windows/prebuilt/x64/
• linux/prebuilt/x64/
• assets/ (CoMaps data files - copy to your app)
• headers/ (C++ headers, for building from source)

Note: Headers are included for developers who need to build from source.
Typical plugin consumers using pre-built binaries do NOT need headers.

Downloads

📦 SDK Package (All Platforms)

📱 Example Apps

Build Info

• Build Number: 152
• Flutter: 3.38.7
• CoMaps: v2026.01.08-11

Android Build & Tooling

• Gradle/AGP updates: Added Gradle wrapper 8.14, updated Gradle/Android plugin versions, and aligned Kotlin/Flutter compatibility.
• Packaging tweak: Refactored Android mwm noCompress configuration and updated the application plugin version.

Android Testing

• AGP test suite: Added Android Gradle Plugin test suite support with a new Favorite’s Journey test case.

Release Metadata

• Version bump: Updated plugin version to 0.1.23 across podspecs, Podfile.lock, and pubspec.lock.

Agus Maps v0.1.23

Compare

Choose a tag to compare

macOS/iOS Rendering

• Fixed Stalled Rendering: Resolved a critical issue where the map would freeze during pan/zoom operations after the first few seconds of interaction. The fix ensures that Flutter is notified immediately whenever a new frame is presented by the Metal engine, bypassing a previous optimization that was causing missed frames during interactive gestures. This restores smooth, continuous map updates on both macOS and iOS.
• Documentation: Updated implementation documentation for macOS and iOS to reflect the improved frame notification logic.

Agus Maps Flutter - v0.1.21

Offline vector maps for Flutter powered by the CoMaps engine.

📖 Full Installation Guide

📦 Unified SDK (Recommended)

Download: agus-maps-sdk-v0.1.21.zip

Installation:

1. Download and extract agus-maps-sdk-v0.1.21.zip
2. Set environment variable:

   export AGUS_MAPS_HOME=/path/to/agus-maps-sdk-v0.1.21

3. Copy assets to your Flutter app:

   cp -r $AGUS_MAPS_HOME/assets/* your_app/assets/

4. Build your app

This SDK contains all platform binaries:

• android/prebuilt/{arm64-v8a,armeabi-v7a,x86_64}/
• ios/Frameworks/CoMaps.xcframework/
• macos/Frameworks/CoMaps.xcframework/
• windows/prebuilt/x64/
• linux/prebuilt/x64/
• assets/ (CoMaps data files - copy to your app)
• headers/ (C++ headers, for building from source)

Note: Headers are included for developers who need to build from source.
Typical plugin consumers using pre-built binaries do NOT need headers.

Downloads

📦 SDK Package (All Platforms)

📱 Example Apps

Build Info

• Build Number: 148
• Flutter: 3.38.7
• CoMaps: v2026.01.08-11

Map View

• Initial viewport ordering: Restored v0.1.17 behavior by applying the initial setView before onMapReady to avoid delayed/blank initial renders for consumers.

macOS

• Metal context build fix: Restored missing DrawMetalContext members and removed stale legacy-branch references to unblock macOS builds.

Agus Maps v0.1.21

Compare

Choose a tag to compare

Agus Maps Flutter - v0.1.20

Offline vector maps for Flutter powered by the CoMaps engine.

📖 Full Installation Guide

📦 Unified SDK (Recommended)

Download: agus-maps-sdk-v0.1.20.zip

Installation:

1. Download and extract agus-maps-sdk-v0.1.20.zip
2. Set environment variable:

   export AGUS_MAPS_HOME=/path/to/agus-maps-sdk-v0.1.20

3. Copy assets to your Flutter app:

   cp -r $AGUS_MAPS_HOME/assets/* your_app/assets/

4. Build your app

This SDK contains all platform binaries:

• android/prebuilt/{arm64-v8a,armeabi-v7a,x86_64}/
• ios/Frameworks/CoMaps.xcframework/
• macos/Frameworks/CoMaps.xcframework/
• windows/prebuilt/x64/
• linux/prebuilt/x64/
• assets/ (CoMaps data files - copy to your app)
• headers/ (C++ headers, for building from source)

Note: Headers are included for developers who need to build from source.
Typical plugin consumers using pre-built binaries do NOT need headers.

Downloads

📦 SDK Package (All Platforms)

📱 Example Apps

Build Info

• Build Number: 145
• Flutter: 3.38.7
• CoMaps: v2026.01.08-11

macOS/iOS Rendering

• SDK shader validation: CI now fails if shaders_metal.metallib is missing, preventing release of iOS/macOS SDK artifacts that would render blank.

Agus Maps v0.1.20

Compare

Choose a tag to compare

Agus Maps Flutter - v0.1.19

Offline vector maps for Flutter powered by the CoMaps engine.

📖 Full Installation Guide

📦 Unified SDK (Recommended)

Download: agus-maps-sdk-v0.1.19.zip

Installation:

1. Download and extract agus-maps-sdk-v0.1.19.zip
2. Set environment variable:

   export AGUS_MAPS_HOME=/path/to/agus-maps-sdk-v0.1.19

3. Copy assets to your Flutter app:

   cp -r $AGUS_MAPS_HOME/assets/* your_app/assets/

4. Build your app

This SDK contains all platform binaries:

• android/prebuilt/{arm64-v8a,armeabi-v7a,x86_64}/
• ios/Frameworks/CoMaps.xcframework/
• macos/Frameworks/CoMaps.xcframework/
• windows/prebuilt/x64/
• linux/prebuilt/x64/
• assets/ (CoMaps data files - copy to your app)
• headers/ (C++ headers, for building from source)

Note: Headers are included for developers who need to build from source.
Typical plugin consumers using pre-built binaries do NOT need headers.

Downloads

📦 SDK Package (All Platforms)

📱 Example Apps

Build Info

• Build Number: 139
• Flutter: 3.38.7
• CoMaps: v2026.01.08-11

macOS/iOS Rendering

• Regression isolation toggle: Added a legacy Metal Present() path toggle to help diagnose broken initial rendering on macOS/iOS SDK consumers introduced after v0.1.14.
• Documentation note: Documented the regression investigation and the diagnostic toggle location in macOS implementation notes.

Agus Maps v0.1.19

Compare

Choose a tag to compare

Agus Maps Flutter - v0.1.18

Offline vector maps for Flutter powered by the CoMaps engine.

📖 Full Installation Guide

📦 Unified SDK (Recommended)

Download: agus-maps-sdk-v0.1.18.zip

Installation:

1. Download and extract agus-maps-sdk-v0.1.18.zip
2. Set environment variable:

   export AGUS_MAPS_HOME=/path/to/agus-maps-sdk-v0.1.18

3. Copy assets to your Flutter app:

   cp -r $AGUS_MAPS_HOME/assets/* your_app/assets/

4. Build your app

This SDK contains all platform binaries:

• android/prebuilt/{arm64-v8a,armeabi-v7a,x86_64}/
• ios/Frameworks/CoMaps.xcframework/
• macos/Frameworks/CoMaps.xcframework/
• windows/prebuilt/x64/
• linux/prebuilt/x64/
• assets/ (CoMaps data files - copy to your app)
• headers/ (C++ headers, for building from source)

Note: Headers are included for developers who need to build from source.
Typical plugin consumers using pre-built binaries do NOT need headers.

Downloads

📦 SDK Package (All Platforms)

📱 Example Apps

Build Info

• Build Number: 138
• Flutter: 3.38.7
• CoMaps: v2026.01.08-11

Map View

• Initial Viewport Fix: Delayed initial map view setup to ensure onMapReady is called first and map registration completes, preventing race conditions during startup.

Documentation

• Cached headers troubleshooting: Updated README and RELEASE.md with instructions for clearing cached headers on iOS/macOS to resolve potential build issues.

• Project management guides: Added doc/ARCHIVING.md and doc/COPYING.md to provide standardized guidelines for archiving and copying the project directory.

Agus Maps v0.1.18

Compare

Choose a tag to compare

Agus Maps Flutter - v0.1.17

Offline vector maps for Flutter powered by the CoMaps engine.

📖 Full Installation Guide

📦 Unified SDK (Recommended)

Download: agus-maps-sdk-v0.1.17.zip

Installation:

1. Download and extract agus-maps-sdk-v0.1.17.zip
2. Set environment variable:

   export AGUS_MAPS_HOME=/path/to/agus-maps-sdk-v0.1.17

3. Copy assets to your Flutter app:

   cp -r $AGUS_MAPS_HOME/assets/* your_app/assets/

4. Build your app

This SDK contains all platform binaries:

• android/prebuilt/{arm64-v8a,armeabi-v7a,x86_64}/
• ios/Frameworks/CoMaps.xcframework/
• macos/Frameworks/CoMaps.xcframework/
• windows/prebuilt/x64/
• linux/prebuilt/x64/
• assets/ (CoMaps data files - copy to your app)
• headers/ (C++ headers, for building from source)

Note: Headers are included for developers who need to build from source.
Typical plugin consumers using pre-built binaries do NOT need headers.

Downloads

📦 SDK Package (All Platforms)

📱 Example Apps

Build Info

• Build Number: 135
• Flutter: 3.38.7
• CoMaps: v2026.01.08-11

Map Rendering & UX

• Dynamic visual scaling: Added a density parameter to createMapSurface and resizeMapSurface, enabling DPI-aware visual scaling without surface recreation. AgusMap now combines device pixel ratio with a user scale, and the example app includes a persistent map label scale slider.

• Windows pixel conversion: Rounded physical pixel dimensions on Windows and improved diagnostics/texture filtering for clearer rendering.

Platform Fixes

• macOS shutdown stability: Fixed quit hangs and Cmd+Q aborts by making Metal context cleanup non-blocking and safer during teardown.

Build System & Tooling

• Windows data generation compatibility: Desktop data generation now uses Git Bash on Windows and avoids multiprocessing in libkomwm.py via a dedicated patch.

• Map downloader enhancements: Added force re-download and cache handling flags to tool/map_downloader.dart.

• Data tooling cleanup: Removed symbol texture download logic from the data generation pipeline.

• Script cleanup: Retired legacy bootstrap/patch validation scripts in favor of Dart hooks and build_all scripts.

CI/CD

• Windows-focused builds: CI now enables CoMaps builds on Windows only and streamlines Python setup/submodule LFS handling.

• LFS reliability: Added git lfs pull for nested submodules and improved logging during initialization.

Dependencies

• Tooling updates: archive 4.0.7, ffigen 20.1.1, flutter_lints 6.0.0; CI Flutter updated to 3.38.9.

Documentation

• Windows assets guidance: Documented extracted asset locations on Windows.

• CoMaps tag refresh: Updated docs and scripts to COMAPS_TAG v2026.01.08-11.

• Docs cleanup: Updated documentation to replace removed shell/PowerShell script references with tool/build.dart usage.

Maintenance

• Example lockfiles: Removed path_provider_foundation from iOS/macOS example Podfile locks.

Agus Maps v0.1.17

Compare

Choose a tag to compare

Agus Maps Flutter - v0.1.16

Offline vector maps for Flutter powered by the CoMaps engine.

📖 Full Installation Guide

📦 Unified SDK (Recommended)

Download: agus-maps-sdk-v0.1.16.zip

Installation:

1. Download and extract agus-maps-sdk-v0.1.16.zip
2. Set environment variable:

   export AGUS_MAPS_HOME=/path/to/agus-maps-sdk-v0.1.16

3. Copy assets to your Flutter app:

   cp -r $AGUS_MAPS_HOME/assets/* your_app/assets/

4. Build your app

This SDK contains all platform binaries:

• android/prebuilt/{arm64-v8a,armeabi-v7a,x86_64}/
• ios/Frameworks/CoMaps.xcframework/
• macos/Frameworks/CoMaps.xcframework/
• windows/prebuilt/x64/
• linux/prebuilt/x64/
• assets/ (CoMaps data files - copy to your app)
• headers/ (C++ headers, for building from source)

Note: Headers are included for developers who need to build from source.
Typical plugin consumers using pre-built binaries do NOT need headers.

Downloads

📦 SDK Package (All Platforms)

📱 Example Apps

Build Info

• Build Number: 104
• Flutter: 3.38.5
• CoMaps: v2025.12.28-2

Windows Rendering

• Zero-copy pipeline: Implemented WGL_NV_DX_interop with DXGI shared handles for GPU-only frame transfer (CPU fallback retained). Includes adapter matching, interop FBO setup, renderbuffer fallback, draw/read buffer setup, and RGBA→BGRA swizzle in the CPU path.

• Diagnostics overlay: Added native OpenGL overlay for runtime visibility of renderer/transfer path and keyed mutex state, with environment toggle and custom lines API.

• Active frame notifications: CoMaps render loop now calls the active-frame callback when a frame is rendered, ensuring Flutter is notified of live frames.

Build System

• Windows runtime dependencies: Build tooling now copies zlib1.dll from vcpkg into the output directory and improves vcpkg manifest path handling.

• Clean build helper: Added clean-build.ps1 to simplify Windows clean builds.

Documentation

• Windows architecture updates: Added/expanded Windows implementation docs for zero-copy rendering, overlay diagnostics, and render loop behavior.

Agus Maps v0.1.16

Compare

Choose a tag to compare

Agus Maps Flutter - v0.1.15

Offline vector maps for Flutter powered by the CoMaps engine.

📖 Full Installation Guide

📦 Unified SDK (Recommended)

Download: agus-maps-sdk-v0.1.15.zip

Installation:

1. Download and extract agus-maps-sdk-v0.1.15.zip
2. Set environment variable:

   export AGUS_MAPS_HOME=/path/to/agus-maps-sdk-v0.1.15

3. Copy assets to your Flutter app:

   cp -r $AGUS_MAPS_HOME/assets/* your_app/assets/

4. Build your app

This SDK contains all platform binaries:

• android/prebuilt/{arm64-v8a,armeabi-v7a,x86_64}/
• ios/Frameworks/CoMaps.xcframework/
• macos/Frameworks/CoMaps.xcframework/
• windows/prebuilt/x64/
• linux/prebuilt/x64/
• assets/ (CoMaps data files - copy to your app)
• headers/ (C++ headers, for building from source)

Note: Headers are included for developers who need to build from source.
Typical plugin consumers using pre-built binaries do NOT need headers.

Downloads

📦 SDK Package (All Platforms)

📱 Example Apps

Build Info

• Build Number: 96
• Flutter: 3.38.5
• CoMaps: v2025.12.28-2

Map Mirrors & Downloads

• CoMaps CDN discovery: MirrorService now targets CoMaps CDN servers and probes snapshots via countries.txt (no directory listings), with a new discoverMirrors() that reports availability and latency.

• Shared mirror utilities: Added lib/src/mirror_utils.dart to parse countries.txt JSON, model regions/snapshots, and share mirror discovery logic between runtime and tools.

• Map downloader tooling: New tool/map_downloader.dart (mirror discovery, snapshot probing, JSON reports, list modes) and tool/check_mirrors.dart diagnostics for metaserver and CDN health checks.

Example App

• Mirror selector UI: Downloads tab now surfaces mirror status/latency, allows switching mirrors, and refreshes mirror discovery in the background.

• Download paths & cleanup: Downloads now store maps under Documents/agus_maps_flutter/maps; cache validation probes countries.txt, and startup cleanup checks both root and maps directories for partial downloads.

• Map deletion flow: Added per-map delete actions for non-bundled downloads, backed by new MwmStorage.deleteMap() APIs and UI confirmation.

Build System & CI

• Thirdparty caching: Build runner can cache thirdparty/ into .thirdparty-<tag>.tar.gz and restore it on bootstrap; tar.gz create/extract support added to the archive manager.

• Boost headers handling: Build tooling now prefers Boost modular headers and falls back to b2 headers when needed; CI verifies flat headers for plugin compilation.

• CI asset downloads: CI and build scripts now use the Dart map downloader for consistent asset retrieval (with optional JSON reports) and validate/copy ICU data.

• iOS/macOS source hiding: CI temporarily hides CoMaps source during iOS/macOS example builds and extracts bundled headers for plugin compilation, then restores sources post-build.

• Windows vcpkg baseline: Added builtin-baseline to vcpkg.json and CI ensures the baseline commit is available in the cached vcpkg clone.

Build Tooling

• CMake/NDK detection: CMake discovery now prefers SDK-installed CMake on Windows; Android NDK detection honors ANDROID_NDK_HOME and falls back to the newest installed version with clearer errors.

• Process diagnostics: Process runner adds verbose command logging and prints captured stdout/stderr on failures.

Documentation

• CoMaps CDN guidance: README and mirror service docs now describe CoMaps CDN servers, metaserver discovery, and updated download examples.

Agus Maps v0.1.15

Compare

Choose a tag to compare

Agus Maps Flutter - v0.1.14

Offline vector maps for Flutter powered by the CoMaps engine.

📖 Full Installation Guide

📦 Unified SDK (Recommended)

Download: agus-maps-sdk-v0.1.14.zip

Installation:

1. Download and extract agus-maps-sdk-v0.1.14.zip
2. Set environment variable:

   export AGUS_MAPS_HOME=/path/to/agus-maps-sdk-v0.1.14

3. Copy assets to your Flutter app:

   cp -r $AGUS_MAPS_HOME/assets/* your_app/assets/

4. Build your app

This SDK contains all platform binaries:

• android/prebuilt/{arm64-v8a,armeabi-v7a,x86_64}/
• ios/Frameworks/CoMaps.xcframework/
• macos/Frameworks/CoMaps.xcframework/
• windows/prebuilt/x64/
• linux/prebuilt/x64/
• assets/ (CoMaps data files - copy to your app)
• headers/ (C++ headers, for building from source)

Note: Headers are included for developers who need to build from source.
Typical plugin consumers using pre-built binaries do NOT need headers.

Downloads

📦 SDK Package (All Platforms)

📱 Example Apps

Build Info

• Build Number: 84
• Flutter: 3.38.5
• CoMaps: v2025.12.28-2

Build System Overhaul

• Dart Build Tool Migration: Replaced shell scripts (.sh, .ps1) with a unified Dart build tool (tool/build.dart) for all platforms. This provides better cross-platform compatibility, easier maintenance, and consistent behavior across macOS, Linux, and Windows.

• Dart Hooks Infrastructure: Implemented Dart hooks system (hook/build.dart) to automatically download and install the SDK during flutter pub get for plugin consumers. This eliminates the manual download step for typical consumers.

  • Consumer Workflow: The hook automatically downloads the SDK from GitHub Releases during flutter pub get
  • Contributor Workflow: Contributors use dart run tool/build.dart --build-binaries to build from source
  • Fallback Support: The AGUS_MAPS_HOME environment variable remains supported as a fallback

• Modular Build System: Created tool/src/ with modular Dart components:

  • build_runner.dart - Main build orchestration
  • cmake_build.dart - CMake build logic for all platforms
  • sdk_downloader.dart - SDK download and installation
  • platform_detector.dart - OS and platform detection
  • file_operations.dart - Cross-platform file operations
  • process_runner.dart - External process execution
  • git_operations.dart - Git operations (clone, checkout, submodules)
  • patch_applicator.dart - CoMaps patch application
  • archive_manager.dart - Archive operations
  • config.dart - Build configuration and constants

Bug Fixes

• iOS XCFramework Generation: Fixed a critical issue where iOS XCFramework creation failed due to naming conflicts when merging static libraries from device and simulator builds. Both builds were creating libcomaps.a in the same directory, causing overwrites. The fix creates separate temporary directories (temp/iphoneos/ and temp/iphonesimulator/) for each architecture's merged library.

• Windows Visual Studio Generator: On Windows, the build tool now uses Visual Studio 17 2022 generator instead of Ninja to avoid GCC/MinGW-w64 compatibility issues with ICU compilation. ICU has known issues with newer GCC versions (e.g., 15.2.0), so using MSVC via Visual Studio generator is more reliable.

• Windows Multi-Config Builds: Fixed handling of Visual Studio multi-configuration builds where CMAKE_BUILD_TYPE is ignored during configure and output DLLs are placed in buildDir/Release/ or buildDir/Debug/ subdirectories. The build tool now correctly uses the --config flag and searches appropriate output directories.

• Windows Path Handling: Improved path handling in the copyPath function with proper normalization using path.absolute() and path.normalize(). Added error handling to skip files that can't be copied (symlinks, missing files) instead of failing the entire copy operation.

• Windows Data Generation: The Dart build tool now only runs generate_desktop_ui_strings.py directly on Windows and skips bash scripts (generate_drules.sh, generate_categories.sh), matching the behavior of the original PowerShell implementation.

• Windows zlib1.dll Runtime Dependency: Added CI step to copy zlib1.dll runtime dependency for Windows builds, ensuring the DLL is available at runtime.

• CoMaps Data Generation Environment: Added OMIM_PATH and DATA_PATH environment variables to data generation scripts (generate_drules.sh, generate_categories.sh), which are required by CoMaps tools to locate sources and output directories correctly.

CI/CD Improvements

• Workflow Modernization: Updated .github/workflows/devops.yml to use dart run tool/build.dart instead of shell scripts for:

  • CoMaps bootstrap (dart run tool/build.dart --no-cache)
  • Platform-specific native builds (dart run tool/build.dart --build-binaries --platform <platform>)

• MWM Download Steps: Added explicit MWM file download steps to CI workflow for iOS, macOS, and Android example app builds. Downloads World.mwm, WorldCoasts.mwm, and Gibraltar.mwm from CoMaps CDN servers (with Organic Maps mirrors as fallback) to ensure map assets are available for example apps.

• Symbol Texture Downloading: Implemented automatic download of symbol textures from Organic Maps for various resolutions and themes (.sdf and .png files).

• CocoaPods Automation: Improved Metal shader compilation handling for macOS/iOS builds, ensuring shaders are correctly processed and linked. Added CocoaPods setup automation after building native binaries.

Documentation

• Early-Stage Notice: Added early-stage development notice to README to set appropriate expectations for users.

• Dart Hooks Documentation: Added comprehensive doc/DART-HOOKS.md documenting the new build system architecture, migration from shell scripts, build mode detection, and troubleshooting.

Dependencies

• New Build Dependencies: Added the following packages to support the Dart build system:
  • hooks: ^1.0.0 - Dart hooks API for build automation
  • archive: ^3.4.0 - Archive operations (ZIP extraction/creation)
  • yaml: ^3.1.2 - YAML parsing for pubspec.yaml
  • path: ^1.9.1 - Cross-platform path operations

Migration

No action required for consumers upgrading from 0.1.13. The Dart hooks system provides a smoother experience:

• First-time setup: Simply run flutter pub get - the SDK will be downloaded automatically
• Existing AGUS_MAPS_HOME users: Your existing setup continues to work; the environment variable takes precedence over auto-download
• Contributors: Use dart run tool/build.dart --build-binaries instead of shell scripts

Agus Maps v0.1.14

Compare

Choose a tag to compare

Documentation

• Comprehensive API Reference: Added doc/API.md with complete documentation of all existing APIs and a roadmap for future API additions. Includes detailed implementation patterns for FFI and MethodChannel APIs, code review checklists, and CoMaps framework reference.

• Enhanced README: Significantly improved setup instructions with detailed platform-specific configuration for iOS, macOS, and Android minimum versions. Added a new "Quick Test" section with a compact example app to verify plugin setup.

• API Reference Links: Updated README and CONTRIBUTING.md to include links to the new API reference documentation. Moved Features section to the example app README for better organization.

Linux Build System

• Simplified Binary Distribution: Removed the separate libagus.so dependency from Linux builds. All CoMaps functionality is now statically linked into libagus_maps_flutter.so, reducing deployment complexity and eliminating potential library loading issues.

• Streamlined CMakeLists.txt: Updated linux/CMakeLists.txt to check only for libagus_maps_flutter.so during prebuilt detection, reflecting the consolidated library architecture.

Migration

No action required for consumers upgrading from 0.1.12. The Linux build changes are fully backward compatible—existing AGUS_MAPS_HOME setups will continue to work with the new single-library architecture.

Bug Fixes

• Missing Metal Shaders in Release Binaries: Fixed a critical packaging issue where shaders_metal.metallib was omitted from the agus-binaries-ios.zip and agus-binaries-macos.zip release artifacts. This caused runtime crashes on iOS and macOS (specifically CHECK(libPath != nil) shaders_metal.metallib not found in any bundle!). The CI/CD workflow and local build scripts now correctly package the Resources directory containing the compiled shaders.

• Development Pod Resource Copying: Updated the podspec development helper script (used when the plugin is a local path dependency) to copy Resources (shaders) from AGUS_MAPS_HOME in addition to headers. This ensures that local example apps and development workflows correctly include the necessary Metal shaders.

Bug Fixes

• iOS Release build failure (critical): Fixed missing GCC_PREPROCESSOR_DEFINITIONS configuration overrides for Debug/Release builds in the iOS podspec. Without these, CoMaps' base/base.hpp triggers a static assertion: Either Debug or Release should be defined, but not both. This affected pub.dev consumers building for iOS in Release mode. The fix adds DEBUG=1 for Debug builds and RELEASE=1 NDEBUG=1 for Release/Profile builds, matching the macOS podspec.

Documentation

• New Build Configuration Guide: Added doc/BUILD-CONFIGURATION.md to comprehensively document build configurations (Debug/Release/Profile), preprocessor definitions, and platform-specific build details.
• Release Guide Update: Updated doc/RELEASE.md to reflect the deprecation of individual binary downloads. It now focuses on the Unified Binary Package and provides detailed instructions for installing pre-built Example Apps on all platforms.

Release & Distribution

• Deprecated Individual Binary Downloads: The release workflow now only distributes the unified agus-maps-sdk. Individual platform zip files (e.g., agus-binaries-ios.zip) are no longer generated to streamline distribution.
• Release Artifacts Cleanup: The devops.yml workflow was updated to stop uploading deprecated artifacts.

iOS and macOS Build System Improvements

• Development Pod header support: Added automatic header copying at pod install time for Development Pods (path dependency) on both iOS and macOS. When using the plugin as a development dependency (e.g., path: ../agus_maps_flutter), headers are now copied from AGUS_MAPS_HOME during pod installation, fixing "file not found" errors for CoMaps headers like boost/regex.hpp.

• SDK source tracking: Introduced a marker file (.sdk_source) in the ios/Headers/ and macos/Headers/ directories to track which SDK the headers were copied from. The build system now detects when AGUS_MAPS_HOME changes and automatically refreshes headers, ensuring consumers always have the correct headers for their configured SDK version.

• Header copying in prepare_command: Both iOS and macOS podspec prepare_command blocks now copy headers from AGUS_MAPS_HOME/headers to Headers/comaps/ alongside the XCFramework. This ensures pub.dev consumers have all necessary headers for compilation.

• Prioritized header search paths (macOS): Reordered HEADER_SEARCH_PATHS in the macOS podspec to prioritize downloaded headers (Headers/comaps/) over in-repo thirdparty paths. This ensures consumers using the SDK binaries get consistent header resolution without interference from missing in-repo sources.

Repository Maintenance

• Updated .gitignore: Added macos/Headers/ and ios/Headers/ to ignore downloaded headers, keeping the repository clean when using SDK binaries.

Technical Details

• Development Pod vs. Published Pod behavior:

  • Published pods (from pub.dev): prepare_command runs during pod install, copying frameworks and headers
  • Development pods (path dependency): prepare_command is skipped; new Ruby code at the top of the podspec handles header copying

• Header refresh triggers:

  1. Headers/comaps/ directory missing
  2. .sdk_source marker file missing
  3. .sdk_source contains a different path than current AGUS_MAPS_HOME

Migration

No breaking changes. Consumers using AGUS_MAPS_HOME will benefit from automatic header management on both iOS and macOS. If you encounter stale headers after changing SDK versions, delete ios/Headers/ or macos/Headers/ and run pod install again.

Build System Improvements

• Streamlined Android prebuilt binary integration: Refactored android/build.gradle to provide a cleaner separation between in-repo development mode and external consumer mode. External consumers now exclusively use pre-built binaries via jniLibs.srcDirs, while in-repo contributors continue to build from source via CMake.

• Enhanced AGUS_MAPS_HOME detection: When AGUS_MAPS_HOME environment variable is set and points to a valid directory, the build system now explicitly forces external consumer mode. This prevents accidental source builds when consumers have the SDK properly configured.

• Disabled CMake for external consumers: The externalNativeBuild block in android/build.gradle is now conditionally applied only for in-repo builds. External consumers no longer trigger CMake configuration, eliminating unnecessary build overhead and potential configuration errors.

• Simplified prebuilt library lookup: Removed complex multi-tier fallback logic in favor of a straightforward approach:

  1. Check AGUS_MAPS_HOME environment variable
  2. Use jniLibs.srcDirs to point to the prebuilt libraries
  3. Provide clear error messages if binaries are not found

  This eliminates the plugin-local prebuilt/ directory fallback for non-CI builds, making the consumer workflow more explicit and predictable.

Bug Fixes

• Asset extraction verification: Enhanced the asset extraction check in AgusMapsFlutterPlugin.java to verify that essential files (e.g., unicode_blocks.txt) exist before skipping re-extraction. This prevents runtime errors caused by incomplete or corrupted asset extractions.

  The plugin now checks:

  • Marker file (.comaps_data_extracted) indicating prior extraction
  • Essential asset file (fonts/unicode_blocks.txt) to confirm completeness

  If either check fails, assets are re-extracted automatically.

Error Message Improvements

• Clearer setup instructions: Error messages when AGUS_MAPS_HOME is missing or invalid now provide more actionable guidance:
  • For consumers: Step-by-step instructions to download, extract, configure, and use the SDK
  • For contributors: Direct reference to build scripts (build_all.sh / build_all.ps1)
  • Distinguished between AGUS_MAPS_HOME path issues vs. missing binaries entirely

Technical Details

• Build mode detection logic: The build system now evaluates build mode in this order:

  1. AGUS_MAPS_HOME override: If set and valid, force external consumer mode
  2. In-repo check: If .git and thirdparty/comaps exist AND AGUS_MAPS_HOME is not set, use in-repo development mode
  3. External consumer: Otherwise, require AGUS_MAPS_HOME with valid prebuilt binaries

• jniLibs.srcDirs approach: Instead of using CMake arguments to configure prebuilt paths, the Gradle build now directly adds the prebuilt directory to sourceSets.main.jniLibs.srcDirs. This is the standard Android approach for including pre-compiled native libraries and avoids CMake entirely for consumers.

Migration

No breaking changes. Consumers using AGUS_MAPS_HOME correctly will see improved build performance (no CMake overhead) and clearer error messages. Ensure your AGUS_MAPS_HOME points to a valid SDK directory with the following structure:

agus-maps-sdk-v0.1.9/
├── android/prebuilt/{arm64-v8a,armeabi-v7a,x86_64}/
├── ios/Frameworks/CoMaps.xcframework/
├── macos/Frameworks/CoMaps.xcframework/
├── windows/prebuilt/x64/
├── linux/prebuilt/x64/
└── assets/
    ├── comaps_data/
    └── ...

Cross-Platform Impact

• Android only: All changes are scoped to Android Gradle configuration and Java plugin code
• No changes to iOS/macOS/Linux/Windows: Build systems for other platforms remain unchanged

Bug Fixes

• Android Gradle syntax error: Fixed a missing closing brace in android/build.gradle inside the external CMake configuration block. The malformed else { ... } caused Gradle to report Unexpected input: '{' at the android { line during CI. The block is now correctly closed and parses under AGP 8.x.

• NDK handling aligned with v0.1.6: Retained ndkVersion = android.ndkVersion to match prior successful builds. No changes to NDK behavior versus 0.1.6; the consuming app continues to define the NDK version used.

CI Stability

• GitHub Actions (Android): With the Gradle file corrected, CI can evaluate the project and proceed to build native libraries and example artifacts without early failure. NDK behavior remains unchanged from 0.1.6. No workflow changes are required.

Cross‑platform Impact

• No changes to iOS/macOS/Linux/Windows: The fix is scoped to Android Gradle configuration only. Other platforms and their build systems (CocoaPods/CMake) remain unchanged and continue to work as in 0.1.7.

Migration

No action required for consumers upgrading from 0.1.7. NDK behavior is unchanged compared to 0.1.6.

Breaking Changes

• Mandatory AGUS_MAPS_HOME for consumers: Plugin consumers must now set the AGUS_MAPS_HOME environment variable pointing to the extracted SDK directory. The fallback to extracting binaries into the app root directory has been removed.

• SDK Package Renamed: The release artifact is now named agus-maps-sdk-vX.Y.Z.zip (previously agus-maps-binaries-vX.Y.Z.zip) to better reflect that it contains the complete SDK with binaries, assets, and optional headers.

New Features

• CI Environment Detection: All build systems (Gradle, CMake, CocoaPods) now detect CI environments via the CI environment variable. This allows CI workflows to use plugin-local prebuilt/ directories without requiring AGUS_MAPS_HOME.

• Standardized Error Messages: All platforms now display consistent, actionable error messages when binaries are not found, clearly distinguishing between consumer and contributor workflows.

Build System Improvements

• Android build.gradle: Fixed a bug with orphaned if-block in prebuilt detection logic. Added CI detection to allow plugin-local prebuilt directories only in CI or when binaries actually exist.

• iOS/macOS podspecs: Enhanced prepare_command with CI detection. CI builds now proceed with a placeholder, allowing the workflow to copy frameworks before the actual build step.

• Linux/Windows CMakeLists: Added IS_CI detection alongside IS_IN_REPO for cleaner workflow separation.

Documentation

• Rewrote GUIDE.md: Replaced historical architecture document with current implementation details. Now covers the three workflow types (contributor, CI, consumer) and actual platform implementations.

• Updated README.md: Refined consumer installation instructions with platform-specific commands for setting AGUS_MAPS_HOME. Added Windows CMD example alongside PowerShell.

• Updated CONTRIBUTING.md: Added explicit warning that contributors should NOT set AGUS_MAPS_HOME - the build scripts handle everything automatically.

Migration Guide

If upgrading from v0.1.6:

1. Download agus-maps-sdk-v0.1.7.zip from GitHub Releases
2. Extract to a permanent location (e.g., ~/agus-sdk/agus-maps-sdk-v0.1.7)
3. Set AGUS_MAPS_HOME environment variable:

   # macOS/Linux (add to ~/.bashrc or ~/.zshrc)
   export AGUS_MAPS_HOME=/path/to/agus-maps-sdk-v0.1.7
   
   # Windows PowerShell (add to profile or set system env var)
   $env:AGUS_MAPS_HOME = "C:\path\to\agus-maps-sdk-v0.1.7"
   

4. Copy assets from SDK to your Flutter app's assets/ folder
5. Rebuild with flutter clean && flutter build

Bug Fixes

• Fixed Windows CI archive creation step: Resolved a CI failure where the "Create Windows Binaries Archive" step was using bash-style commands (rm -f, zip) but running in PowerShell by default. PowerShell interpreted rm -f as Remove-Item with an ambiguous -f parameter. Changed to native PowerShell commands (Remove-Item, Compress-Archive) with explicit shell: pwsh for consistency with other Windows steps.

Bug Fixes

• Fixed Android CI build failure: Resolved an issue where in-repo builds (CI, local development) incorrectly used pre-built binary mode instead of building from source. This caused compilation failures with "file not found" errors for CoMaps headers (base/task_loop.hpp, platform/platform.hpp, etc.) because the headers directory was not set.

Build System Changes

• Prioritize source builds for in-repo development: Changed Android Gradle build logic to always build from source when running in-repo (when .git and thirdparty/comaps exist), regardless of whether android/prebuilt/ contains binaries. This ensures CI builds and local development always use the source code.
• Clearer error for external consumers: External consumers (Flutter apps using this plugin as a dependency) now receive a clear GradleException with download instructions if pre-built binaries are missing, instead of a generic warning.

Release Packaging Improvements

• Unified binary package: Introduced agus-maps-binaries-vX.Y.Z.zip containing all platform binaries, assets, and headers in a single download.
• Versioned artifact filenames: All release artifacts now include the version tag (e.g., agus-maps-android-vX.Y.Z.apk).
• Streamlined release artifacts: Removed individual platform binary zips from releases - they are now consolidated in the unified package.
• Headers included: C++ headers are now bundled in the unified package for developers who need to build from source.

Documentation

• Updated doc/RELEASE.md with comprehensive installation guide for the unified binary package.

• CI/CD improvements for multi-platform builds.
• Azure Blob Storage caching for CoMaps source.
• Build workflow optimizations.

• Initial release of Agus Maps Flutter.
• Zero-copy rendering architecture.
• Offline maps support via CoMaps engine.
• Experimental support for linux, macos, windows, ios and android targets.
• This is an experimental release, do not use on production apps.