Building BBPlayer

Build Variants

BBPlayer uses different build variants for various stages of development and release. These are configured in eas.json in the mobile app directory.

BBPlayer primarily targets Android. iOS builds are not actively maintained and may not compile successfully.

EAS Build Profiles

Expo Application Services (EAS) manages build configurations:

Profile	Purpose	Distribution	ABI Filters	Channel
`dev`	Development builds	Internal	arm64-v8a	development
`preview`	Internal testing	Internal	arm64-v8a	preview
`prod-v8a`	Production (64-bit)	Public	arm64-v8a	production
`prod-universal`	Universal APK	Public	All ABIs	production
`prod-ci`	CI/CD builds	Public	Auto	production

Understanding ABI Filters

ABI (Application Binary Interface) determines which CPU architectures the APK supports:

arm64-v8a - 64-bit ARM (most modern devices) - smallest file size
armeabi-v7a - 32-bit ARM (older devices)
x86 - 32-bit x86 (emulators, rare devices)
x86_64 - 64-bit x86 (some tablets, emulators)

For public releases, use prod-v8a for most users (smaller file size) and prod-universal for maximum compatibility.

Local Development Builds

Android Debug Build

Build and run a debug APK on a connected device or emulator:

cd apps/mobile
pnpm android

This command:

Runs expo run:android with Rozenite metro plugins enabled
Builds a debug APK
Installs it on your device/emulator
Starts the Metro bundler

Debug builds include development tools and are not optimized for performance. Use them only during development.

Production Builds with EAS

Prerequisites

Install EAS CLI

npm install -g eas-cli

eas login

Configure project

If building for the first time:

cd apps/mobile
eas build:configure

Build Production APK (arm64-v8a)

Build an optimized APK for 64-bit ARM devices:

cd apps/mobile
eas build --profile prod-v8a --platform android

Environment variables set:

APP_VARIANT=production
ABI_FILTERS=arm64-v8a

This creates the smallest APK suitable for most modern Android devices.

Build Universal APK

Build an APK supporting all architectures:

cd apps/mobile
eas build --profile prod-universal --platform android

Environment variables set:

APP_VARIANT=production
ABI_FILTERS=armeabi-v7a,arm64-v8a,x86,x86_64

Universal APKs are significantly larger (2-4x) than single-architecture APKs. Only use for maximum compatibility.

Build Preview Version

Create an internal preview build for testing:

cd apps/mobile
eas build --profile preview --platform android

Preview builds:

Include production optimizations
Have internal distribution settings
Use the preview update channel

Local Production Builds

You can build production APKs locally without EAS:

Set environment variables

export APP_VARIANT=production
export ABI_FILTERS=arm64-v8a

Build release APK

cd apps/mobile/android
./gradlew :app:assembleRelease

Locate the APK

The APK will be generated at:

apps/mobile/android/app/build/outputs/apk/release/app-release.apk

Local release builds are unsigned. You’ll need to sign them manually before distribution:

jarsigner -keystore your-keystore.jks \
  -storepass your-password \
  app-release.apk \
  your-key-alias

iOS Builds (Experimental)

iOS support is not actively maintained. The build process may fail. The project focuses on Android development.

If you want to attempt an iOS build:

Prerequisites

macOS with Xcode 15+
Apple Developer account
Provisioning profiles configured

Build iOS

cd apps/mobile
eas build --profile prod-v8a --platform ios

iOS builds are not regularly tested. Expect compilation errors and platform-specific issues.

Build Configuration Details

App Variants

The APP_VARIANT environment variable controls build behavior:

APP_VARIANT=development
// Enables:
// - Debug logging
// - React DevTools
// - Hot reloading
// - Development warnings

Metro Bundler Plugins

The mobile app uses Rozenite plugins for enhanced development:

WITH_ROZENITE=true pnpm start

Rozenite provides:

MMKV plugin - Storage inspection
TanStack Query plugin - Query devtools
Require profiler - Module load time profiling

Rozenite plugins are development-only and automatically disabled in production builds.

Signing and Release

Generate Keystore

For manual signing, create a keystore:

keytool -genkey -v -keystore bbplayer-release.jks \
  -keyalg RSA -keysize 2048 -validity 10000 \
  -alias bbplayer-key

Configure Gradle

Add signing configuration to apps/mobile/android/app/build.gradle:

android {
    signingConfigs {
        release {
            storeFile file('bbplayer-release.jks')
            storePassword 'your-password'
            keyAlias 'bbplayer-key'
            keyPassword 'your-password'
        }
    }
    buildTypes {
        release {
            signingConfig signingConfigs.release
        }
    }
}

Never commit keystore files or passwords to version control! Use environment variables or secure credential storage.

Continuous Integration

The prod-ci profile is designed for CI/CD pipelines:

# Example GitHub Actions
name: Build APK
on: [push]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: pnpm/action-setup@v2
        with:
          version: 10.26.2
      - run: pnpm install
      - run: eas build --profile prod-ci --platform android --non-interactive

Troubleshooting

Build Fails with “Out of Memory”

Increase Gradle memory in apps/mobile/android/gradle.properties:

org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=512m

ABI Filter Issues

If the app crashes on certain devices, ensure the correct ABI is included:

# Check supported ABIs in the APK
unzip -l app-release.apk | grep "\.so$"

Metro Bundler Errors

Clear Metro cache:

cd apps/mobile
pnpm start --clear

Native Module Build Errors

Rebuild native modules:

cd apps/mobile/android
./gradlew clean
cd ..
pnpm android

Distribution

Once you have a signed APK:

GitHub Releases - Upload to GitHub for direct downloads
Google Play - Submit via Play Console
Alternative Stores - F-Droid, APKPure, etc.

BBPlayer releases are distributed via GitHub Releases. Check there for official builds.

Contributing

Resources

Building BBPlayer

Build Variants

EAS Build Profiles

Understanding ABI Filters

Local Development Builds

Android Debug Build

Production Builds with EAS

Prerequisites

Build Production APK (arm64-v8a)

Build Universal APK

Build Preview Version

Local Production Builds

iOS Builds (Experimental)

Prerequisites

Build iOS

Build Configuration Details

App Variants

Metro Bundler Plugins

Signing and Release

Generate Keystore

Configure Gradle

Continuous Integration

Troubleshooting

Build Fails with “Out of Memory”

ABI Filter Issues

Metro Bundler Errors

Native Module Build Errors

Distribution

Next Steps

Development Setup

Project Structure

Build docs developers (and LLMs) love

Contributing

Resources

​Build Variants

​EAS Build Profiles

​Understanding ABI Filters

​Local Development Builds

​Android Debug Build

​Production Builds with EAS

​Prerequisites

​Build Production APK (arm64-v8a)

​Build Universal APK

​Build Preview Version

​Local Production Builds

​iOS Builds (Experimental)

​Prerequisites

​Build iOS

​Build Configuration Details

​App Variants

​Metro Bundler Plugins

​Signing and Release

​Generate Keystore

​Configure Gradle

​Continuous Integration

​Troubleshooting

​Build Fails with “Out of Memory”

​ABI Filter Issues

​Metro Bundler Errors

​Native Module Build Errors

​Distribution

​Next Steps

Development Setup

Project Structure

Build docs developers (and LLMs) love

Build Variants

EAS Build Profiles

Understanding ABI Filters

Local Development Builds

Android Debug Build

Production Builds with EAS

Prerequisites

Build Production APK (arm64-v8a)

Build Universal APK

Build Preview Version

Local Production Builds

iOS Builds (Experimental)

Prerequisites

Build iOS

Build Configuration Details

App Variants

Metro Bundler Plugins

Signing and Release

Generate Keystore

Configure Gradle

Continuous Integration

Troubleshooting

Build Fails with “Out of Memory”

ABI Filter Issues

Metro Bundler Errors

Native Module Build Errors

Distribution

Next Steps