Building Signal Android

Prerequisites

Before cloning the repository, make sure you have the following installed.

Android Studio

The official IDE for Android development. Download from developer.android.com.

JDK 17

The project requires OpenJDK 17. The .tool-versions file pins java openjdk-17.0.2. Android Studio bundles a JDK, but you can also install it separately with asdf or sdkman.

Cloning the repository

git clone https://github.com/signalapp/Signal-Android.git
cd Signal-Android

The repository includes a build-logic/ directory that is an included Gradle build containing shared plugins and tooling — it is part of the same workspace and does not need to be cloned separately.

NDK and CMake

Signal uses native code through libsignal and other libraries. You need to install the exact NDK and CMake versions referenced in the project’s Docker configuration for reproducible builds.

Check the Dockerfile for the exact NDK and CMake versions currently in use. Using a different version may produce build failures.

The NDK version is also declared in app/build.gradle.kts:

ndkVersion = libs.versions.ndk.get()

Install both components through Android Studio → SDK Manager → SDK Tools:

Open SDK Manager

In Android Studio, go to Settings → Appearance & Behavior → System Settings → Android SDK, then select the SDK Tools tab.

Install NDK

Check NDK (Side by side), expand it, and install the version matching the Dockerfile.

Install CMake

Check CMake, expand it, and install the version matching the Dockerfile.

Opening in Android Studio

Open the project

Launch Android Studio and select Open, then navigate to the Signal-Android directory. Open the root of the repository — not a subdirectory.

Wait for sync

Gradle will sync and download dependencies. This may take several minutes on first open. The project pulls artifacts from several custom Maven repositories declared in settings.gradle.kts, including Signal’s own artifact server at build-artifacts.signal.org.

Select a build variant

Open the Build Variants panel (bottom-left in Android Studio) and select a variant. playProdDebug is the default for day-to-day development.

Build variants

The app uses two flavor dimensions — distribution and environment — combined with standard build types.

Distribution flavors

Flavor	Description
`play`	Google Play distribution. Does not self-manage APK updates.
`website`	APK distributed from signal.org. Self-manages updates.
`github`	GitHub release APK. Does not self-manage APK updates.
`nightly`	Internal nightly builds. Appends git hash to the version name.

Environment flavors

Flavor	Description
`prod`	Production Signal servers (`chat.signal.org`).
`staging`	Staging Signal servers (`chat.staging.signal.org`). Separate app ID.

Build types

Build type	Minified	Debuggable	Notes
`debug`	No	Yes	Default for development.
`release`	Yes	No	Production builds.
`instrumentation`	No	Yes	Instrumented tests. Uses `.instrumentation` app ID suffix.
`spinner`	No	Yes	Includes the Spinner database inspector.
`perf`	Yes	No	Performance profiling with tracing enabled.
`canary`	No	Yes	Canary feature preview.

Selectable variant examples

playProdDebug          — development on production servers via Play
playProdRelease        — production Play Store build
playStagingDebug       — development against staging servers
websiteProdRelease     — signal.org APK download
githubProdRelease      — GitHub release APK

Use playProdDebug for local development. Use playStagingDebug if you need to test against the staging environment without affecting a real account.

Building from the command line

Assemble APK
Install on device
Clean build

./gradlew assemblePlayProdDebug

The output APK lands in app/build/outputs/apk/playProd/debug/.

./gradlew installPlayProdDebug

Requires an ADB-connected device or running emulator.

./gradlew clean assemblePlayProdDebug

Running on a device or emulator

Enable Developer Options and USB Debugging on your Android device, or create an AVD in the Android Studio Device Manager.
Connect the device via USB (or start the emulator).
In Android Studio, select your device from the target dropdown and click Run, or run ./gradlew installPlayProdDebug from the terminal.

Signal requires a real phone number for registration. Use the staging environment flavor if you want to test registration without using your actual number.

Running tests

Unit tests
All module tests
Quality assurance

./gradlew testPlayProdDebugUnitTest

Unit tests run on the JVM and do not require a device.

./gradlew test

Runs unit tests across all submodules. Tests are parallelized up to half the available CPU cores.

./gradlew qa

Runs the full QA suite: clean, ktlint checks, STOPSHIP detection, unit tests for all modules, and lint. Run this before pushing.

Instrumented tests use ANDROIDX_TEST_ORCHESTRATOR and a dedicated instrumentation build type. They run against a managed virtual device (pixel3api30) configured in app/build.gradle.kts.

Development

Internals

Prerequisites

Android Studio

JDK 17

Cloning the repository

NDK and CMake

Opening in Android Studio

Build variants

Distribution flavors

Environment flavors

Build types

Selectable variant examples

Building from the command line

Running on a device or emulator

Running tests

​Prerequisites

Android Studio

JDK 17

​Cloning the repository

​NDK and CMake

​Opening in Android Studio

​Build variants

​Distribution flavors

​Environment flavors

​Build types

​Selectable variant examples

​Building from the command line

​Running on a device or emulator

​Running tests

Prerequisites

Cloning the repository

NDK and CMake

Opening in Android Studio

Build variants

Distribution flavors

Environment flavors

Build types

Selectable variant examples

Building from the command line

Running on a device or emulator

Running tests