Skip to main content
This guide explains how to build the Open Mobile Maps SDK from source for both Android and iOS platforms.

​
Prerequisites

Before building from source, ensure you have the required tools installed:

​
Common Requirements

  • Git with submodule support
  • Make
  • C++ compiler with C++17 support

​
Android Requirements

  • Android Studio (latest version recommended)
  • Gradle
  • Android SDK 8.0+ (API level 26+)
  • NDK for C++ compilation

​
iOS Requirements

  • macOS
  • Xcode 16 or later
  • Swift Package Manager (included with Xcode)
  • Command Line Tools for Xcode

​
Initial Setup

First, clone the repository and initialize all submodules: 
git clone https://github.com/openmobilemaps/maps-core.git
cd maps-core
git submodule init
git submodule update
The SDK uses git submodules for dependencies. Always ensure submodules are initialized and updated before building.

​
Architecture Overview

Open Mobile Maps uses a shared C++ core with platform-specific bindings:
  • C++ Core: Most of the codebase is written in C++ and shared between platforms
  • Djinni: Interface bindings are generated using a fork of the Djinni library
  • Platform Bindings: Kotlin bindings for Android, Swift bindings for iOS
The project is split into two main modules:
  • graphics-core: Generic structure for rendering basic graphic primitives
  • maps-core: Collection of classes providing the basics for creating a digital map

​
Graphics Rendering

  • Android: OpenGL code kept in C++
  • iOS: Metal implementations written in Swift

​
Updating Djinni Bridging Files

If you modify the Djinni interface files under the djinni/ directory, you’ll need to regenerate the bridging code.

​
Generate Bindings

From the djinni/ folder, run: 
make clean djinni
This generates:
  • Kotlin bindings for Android
  • C++ header files
  • JNI glue code (Android)
  • Objective-C glue code (iOS)
Only regenerate Djinni bindings if you’ve modified the interface definitions. Regenerating unnecessarily may cause build issues.

​
Building for Android

​
Using Android Studio

  1. Open Android Studio
  2. Select “Open an Existing Project”
  3. Navigate to the android/ folder in the repository
  4. Wait for Gradle sync to complete
  5. Build the project using the Build menu

​
Using Command Line

From the android/ directory: 
./gradlew assemble
The compiled .aar library will be available at: 
android/build/outputs/aar/

​
Development Setup

For development, include the library directly as a module in your Android application project:
  1. In your app’s settings.gradle, include the maps-core module
  2. Add it as a dependency in your app’s build.gradle
  3. You can now run the app on a device and iterate on the library code

​
Current Android Dependencies

When including the SDK as an .aar file (not via Maven Central), add these dependencies to your app’s build.gradle: 
implementation "androidx.activity:activity-ktx:1.8.2"
implementation "androidx.lifecycle:lifecycle-runtime-ktx:2.7.0"
implementation "org.jetbrains.kotlinx:kotlinx-coroutines-android:1.7.3"
implementation "com.squareup.okhttp3:okhttp:4.12.0" // for default DataLoader

​
Building for iOS

​
Using Xcode

  1. Open the Package.swift file in Xcode (located at the repository root)
  2. Xcode will automatically resolve dependencies
  3. Build the package using Product > Build (⌘B)

​
Using Command Line

From the repository root: 
swift build

​
Integration Methods

Add to your Package.swift: 
dependencies: [
    .package(url: "https://github.com/openmobilemaps/maps-core", from: .init(stringLiteral: "3.7.1"))
]

​
Xcode Project Integration

  1. In Xcode, go to File > Add Packages
  2. Enter the repository URL: https://github.com/openmobilemaps/maps-core
  3. Select the version or branch
  4. Add to your target
For local development, you can add the package using a local file path instead of a repository URL.

​
Platform-Specific Notes

​
Android

​
OpenGL ES Version

The SDK requires OpenGL ES 3.2, which is available on Android 8.0 (API level 26) and higher.

​
Gradle Configuration

Recent versions of the SDK use:
  • AGP: 8.13.1 (as of version 3.7.0)
  • Kotlin: 2.2.0 (as of version 3.4.0)
  • OkHttp: 5.1.0 (as of version 3.4.0)
  • Moshi: 1.15.2 (as of version 3.4.0)

​
16KB Page Size Support

Starting from version 3.5.0, the SDK supports 16KB page sizes on Android with target SDK 36.

​
iOS

​
Deployment Target

The minimum iOS deployment target is iOS 14 (as of version 2.6.0).

​
Metal vs OpenGL

The iOS implementation uses Metal for graphics rendering, providing better performance and integration with the iOS ecosystem.

​
SwiftUI Support

Starting from version 3.0.0, the MapView is exposed to SwiftUI. However, the SwiftUI MapView requires iOS 17.0 or later. For iOS 14-16, use the UIKit MCMapView component.

​
Coordinate Systems

The SDK comes with implementations for two coordinate systems:
  • EPSG:2056 (LV95/LV03+)
  • EPSG:3857 (Pseudo-Mercator / Web Mercator)
These can be created using the CoordinateSystemFactory.

​
Testing Your Build

​
Android

Create a test application that:
  1. Initializes MapsCore in the Application onCreate: 
    MapsCore.initialize()
  2. Creates a MapView and sets up the map: 
    mapView.setupMap(MapConfig(CoordinateSystemFactory.getEpsg3857System()))
mapView.registerLifecycle(lifecycle)
  3. Adds a test layer (e.g., TiledRasterLayer)

​
iOS

Create a test application that:
  1. Imports MapCore: 
    import MapCore
  2. Creates a MapView with a test layer: 
    let mapView = MCMapView()
mapView.add(layer: TiledRasterLayer("test", webMercatorUrlFormat: "https://tiles.example.org/{z}/{x}/{y}.png"))

​
Troubleshooting

​
Submodule Issues

If you encounter build errors, ensure submodules are properly initialized: 
git submodule update --init --recursive

​
Djinni Generation Errors

If Djinni code generation fails:
  1. Ensure you have the correct version of Djinni (1.1.1 as of SDK version 3.2.0)
  2. Check that you’re running the command from the djinni/ directory
  3. Verify that the Djinni configuration files are not corrupted

​
Android Build Errors

  • Verify your Android SDK and NDK versions
  • Check that Gradle can download dependencies
  • Ensure you have the correct AGP and Kotlin versions

​
iOS Build Errors

  • Verify Xcode Command Line Tools are installed: xcode-select --install
  • Check that your deployment target is iOS 14 or higher
  • Ensure Swift Package Manager can resolve dependencies

​
Contributing

If you plan to contribute to the project:
  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Ensure all builds pass (Android and iOS)
  5. Submit a pull request
Please follow the existing code style and conventions. Add tests for new features when applicable.

​
Additional Resources

Build docs developers (and LLMs) love

Get started for freeTalk to us