Skip to content

Building and running Vela

To install the app, use the Obtainium or F-Droid badge on the README or an APK from Releases. This page is for building from source.

Build and run

Standard Android toolchain (JDK 17; the Gradle wrapper fetches Gradle 9.8.0 and AGP 9.4.1).

Three pieces are not in git and have to be fetched once before the first build, the same way CI does it. They are prebuilt binaries with no Maven artifact, hosted on this repo's own infrastructure releases:

# the neural voice runtime (sherpa-onnx), about 57 MB
mkdir -p app/libs
curl -fSL -o app/libs/sherpa-onnx-1.13.3.aar \
  https://github.com/PimpinPumpkin/Vela/releases/download/tts-runtime/sherpa-onnx-1.13.3.aar

# Cronet, Chromium's network stack, for the version gradle.properties pins (about 15 MB); or run
# scripts/build-cronet-aar.sh, which packs the same AAR from Chromium's own published build
v=$(sed -n 's/^vela.cronetVersion=//p' gradle.properties)
curl -fSL -o "app/libs/cronet-$v.aar" \
  "https://github.com/PimpinPumpkin/Vela/releases/download/cronet-runtime/cronet-$v.aar"

# OsmAnd's router and obf reader, for offline routing
mkdir -p core/libs
for f in osmand-java.jar osmand-shared-jvm.jar gnu-trove-osmand.jar kxml2-vela.jar; do
  curl -fSL -o "core/libs/$f" \
    "https://github.com/PimpinPumpkin/Vela/releases/download/obf-runtime/$f"
done

If .github/workflows/ci.yml names a newer file than this page does, trust the workflow.

# debug build (compile check / local install)
./gradlew :app:assembleDebug

# the build that goes on a phone (R8 and resource shrinking).
# A debug build drops frames on the map and reads as a performance bug.
./gradlew :app:assembleRelease

# unit tests for the pure logic in :core (parsers, nav engine, routing, the name rules)
./gradlew :core:test

Release signing comes from environment variables (VELA_KEYSTORE_PATH, VELA_KEYSTORE_PASSWORD, VELA_KEY_ALIAS). Without them a local build is signed with the debug keystore, so adb install still works. Do not hand out a local build with a -PappVersionCode above the release line: the next real release then looks like a downgrade. -PappId=app.vela.dev builds a copy that installs beside the real app.

What CI does

Every push to main or canary builds and tests. A push to canary replaces the rolling canary build. A daily job publishes a signed nightly prerelease (v0.5.<run>) when main has moved, and a weekly job (Mondays) promotes the newest nightly to stable. The F-Droid repository index is rebuilt after both. Docs-only pushes skip CI. Chapter 12 of the book has the details.

Architecture

Two Gradle modules. :core has no interface code: the models, the requests to Google and their parsers, the open routers and the on-phone router, the navigation engine, and the remote settings. :app is the Compose interface over MapLibre. core/data/MapDataSource is the seam between them. The module tree is in SPEC.md section 2.

Toolchain: JDK 17, Gradle 9.8, AGP 9.4, Kotlin 2.4. The app compiles against SDK 37, targets 35 and runs on Android 8 (SDK 26) and up.