Skip to main content
This guide provides comprehensive instructions for building Musika from source for different device architectures and configurations.

​
Device Information

Musika supports multiple Android device architectures:
  • arm64-v8a: ARM 64-bit (most modern devices)
  • armeabi-v7a: ARM 32-bit (older devices)
  • x86_64: x86 64-bit (emulators)
  • x86: x86 32-bit (emulators)
For optimal performance, use the architecture-specific build matching your device. For maximum compatibility, use the universal build.

​
Quick Build Commands

The universal build includes all architectures and works on any Android device. 
./gradlew assembleUniversalDebug

​
Build ARM64 Optimized APK

For modern Android devices (recommended for best performance on 64-bit devices). 
./gradlew assembleArm64Debug

​
Build Variants

Musika supports multiple build variants for different architectures:
VariantArchitectureUse Case
universalAll (armeabi-v7a, arm64-v8a, x86, x86_64)Maximum compatibility
arm64ARM 64-bit onlyModern devices (Samsung, Google, etc.)
armeabiARM 32-bit onlyOlder Android devices
x86x86 32-bitAndroid emulators
x86_64x86 64-bitModern emulators
Most modern Android devices (2017+) use arm64-v8a architecture. The universal build is larger but ensures compatibility with all devices.

​
Installing on Device

​
Using ADB

Install the APK on a connected device using ADB: 
adb install -r app/build/outputs/apk/universal/debug/app-universal-debug.apk

​
Build and Install in One Command

Gradle can build and install directly to a connected device: 
./gradlew installUniversalDebug

​
Configuration Files

​
Required Configuration

Before building, ensure you have the following configuration files:
1

local.properties

Contains Android SDK path configuration.
cp local.properties.template local.properties
Edit and add your SDK path:
sdk.dir=/path/to/your/Android/sdk
Never commit local.properties to version control. It contains environment-specific paths.
2

google-services.json (Optional)

Firebase configuration for analytics and crash reporting.
cp app/google-services.json.template app/google-services.json
Never commit google-services.json to version control. It contains sensitive API keys.
Firebase is optional. The app will build and run without it, but analytics and crash reporting will be disabled.
3

persistent-debug.keystore

Debug signing key (automatically generated).
Debug builds use the persistent-debug.keystore for consistent signing across builds.

​
Building for Different Configurations

​
Debug Builds

Debug builds include debugging information and are not optimized: 
./gradlew assembleUniversalDebug

​
Release Builds

Release builds are optimized and require signing configuration: 
./gradlew assembleUniversalRelease
Release builds require proper signing configuration in gradle.properties or environment variables. See the Contributing Guide for details.

​
Troubleshooting

​
Check Connected Devices

Verify that your device is connected and recognized: 
adb devices
You should see your device listed: 
List of devices attached
RZ8M90F41BL    device

​
Check Device Architecture

Determine which architecture your device uses: 
adb shell getprop ro.product.cpu.abi
Common outputs:
  • arm64-v8a - Use ARM64 build
  • armeabi-v7a - Use ARMv7 build
  • x86_64 - Use x86_64 build

​
Clean Build

If you encounter build issues, try a clean build:
1

Clean project

./gradlew clean
2

Rebuild

./gradlew assembleUniversalDebug

​
View Build Logs

For detailed build information, use the --info flag: 
./gradlew assembleUniversalDebug --info
For even more detail, use --debug: 
./gradlew assembleUniversalDebug --debug

​
Common Build Errors

​
SDK Location Not Found

SDK location not found. Define location with an ANDROID_SDK_ROOT environment
variable or by setting the sdk.dir path in your project's local properties file.
Solution: Create local.properties with your SDK path: 
sdk.dir=/path/to/your/Android/sdk

​
Google Services Plugin Error

File google-services.json is missing. The Google Services Plugin cannot function without it.
Solution: Either:
  1. Add your google-services.json file, or
  2. Build the FOSS variant without Firebase: 
    ./gradlew assembleFossDebug

​
Out of Memory

GC overhead limit exceeded
Solution: Increase Gradle memory in gradle.properties: 
org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=512m

​
Build Optimization Tips

​
Parallel Builds

Enable parallel builds in gradle.properties: 
org.gradle.parallel=true
org.gradle.configureondemand=true

​
Build Cache

Enable build cache for faster builds: 
org.gradle.caching=true

​
Configuration Cache (Experimental)

./gradlew assembleDebug --configuration-cache

​
Advanced Build Options

​
Building All Variants

Build all variants at once: 
./gradlew assembleDebug
This creates builds for all architectures in the debug configuration.

​
Building Bundles (AAB)

For Google Play Store distribution: 
./gradlew bundleRelease
Android App Bundles (AAB) allow Google Play to generate optimized APKs for each device configuration automatically.

​
Custom Build Tasks

List all available tasks: 
./gradlew tasks
List tasks with detailed information: 
./gradlew tasks --all

​
Notes

  • Most modern Android devices use arm64-v8a architecture
  • The universal build is larger but ensures maximum compatibility
  • ARM64 builds are smaller and may offer better performance on 64-bit devices
  • Debug builds use the persistent-debug.keystore for consistent signing
  • Firebase is optional - the app builds and runs without it

​
Example: Samsung Galaxy M30s

As a reference, here’s how to build for the Samsung Galaxy M30s:
  • Model: Samsung SM-M307F (Galaxy M30s)
  • Architecture: arm64-v8a
  • Device ID: RZ8M90F41BL
./gradlew assembleArm64Debug

​
Install Directly

./gradlew installArm64Debug
The arm64 build is smaller and optimized for this device, but the universal build will also work perfectly.

Build docs developers (and LLMs) love

Get started for freeTalk to us