Valhalla Mobile

This project builds valhalla as a static iOS or shared Android library.

It currently exposes valhalla's route action, for the primary purpose of generating turn by turn navigation routes using a downloaded pre-parsed valhalla tileset, along with the two map matching actions — trace_route, which snaps a GPS trace to the road network and returns a route along it, and trace_attributes, which returns the attributes of every edge the trace matched. Like routing, both run entirely against the tiles on the device.

We welcome contributions to expand the functionality of this library. See our CONTRIBUTING.md for more information. If you've got questions, would like to have informal discussions, or just want to ping us about a question, PR. Feel free to reach out on the OpenStreetMap Slack (osmus.slack.com) under the #valhalla-mobile channel.

Setup

Android

Using a libs.versions.toml with a build.gradle.kts

[verisons]
valhallaMobile = "0.1.0"
[libraries]
valhalla-mobile = { group = "io.github.rallista", name = "valhalla-mobile", version.ref = "valhallaMobile" }

implementation(libs.valhalla.mobile)

Using a standard build.gradle.kts

implementation("io.github.rallista:valhalla-mobile:0.1.0")

Using a standard build.gradle

implementation 'io.github.rallista:valhalla-mobile:0.1.0'

iOS

In a swift package:

let package = Package(
    dependencies: [
        .package(url: "https://github.com/rallista/valhalla-mobile.git", from: "0.1.0"),
    ],
    targets: [
        .target(
            dependencies: [
                .product(name: "Valhalla", package: "valhalla-mobile")
            ]
        ),
    ]
)

Manually Building Valhalla C++

Fetching submodules

git submodule update --init --recursive

Set up VCPKG

git clone https://github.com/microsoft/vcpkg && git -C vcpkg checkout 2025.12.12
./vcpkg/bootstrap-vcpkg.sh
export VCPKG_ROOT=`pwd`/vcpkg

iOS Swift Package

On iOS, you must pre-build the xcframework using the command:

./build.sh ios clean

Android

Prerequisites: See development.md, specifically setting up NDK 29.0.14206865 to match CI.

The project's build.gradle.kts includes a build task that automatically runs the script below selectively per architecture. It's also possible to run this manually:

./build.sh android clean

Valhalla Fork

This project uses our fork of valhalla at https://github.com/Rallista/valhalla as a submodule. If a feature is missing, please open an issue or PR on that repository to upgrade it to valhalla's latest version.

References

• Valhalla https://github.com/valhalla/valhalla
• Swift Package Manager C++ (for fun - this repo takes the old approach) https://www.swift.org/documentation/articles/wrapping-c-cpp-library-in-swift.html