Building for Mobile

This guide covers building AppFlowy for mobile platforms (iOS and Android) from source.

Prerequisites

Before building, ensure you have completed the development environment setup.

All commands should be run from the frontend/ directory.

iOS Setup

Install Xcode

Download and install Xcode from the App Store or developer.apple.com.

# Install Command Line Tools
xcode-select --install

# Accept license
sudo xcodebuild -license accept

Install CocoaPods

sudo gem install cocoapods
pod --version

Install cargo-lipo

For building iOS universal libraries:

cargo install cargo-lipo

Add iOS targets

rustup target add aarch64-apple-ios         # iOS devices
rustup target add aarch64-apple-ios-sim     # iOS simulator (M1/M2)
rustup target add x86_64-apple-ios          # iOS simulator (Intel)

Android Setup

Install Android Studio

Download from developer.android.com.

Install Android SDK

Through Android Studio:

SDK Platforms: Android 10+ (API 29+)
SDK Tools: NDK, CMake

Set environment variables

macOS/Linux
Windows

export ANDROID_HOME=$HOME/Android/Sdk
export ANDROID_NDK_HOME=$ANDROID_HOME/ndk/<version>
export PATH=$PATH:$ANDROID_HOME/platform-tools

$env:ANDROID_HOME = "C:\Users\<username>\AppData\Local\Android\Sdk"
$env:ANDROID_NDK_HOME = "$env:ANDROID_HOME\ndk\<version>"

Install cargo-ndk

For building Android libraries:

cargo install cargo-ndk

Add Android targets

rustup target add aarch64-linux-android     # ARM64 (most devices)
rustup target add armv7-linux-androideabi   # ARMv7 (older devices)

Building for iOS

Development Build

Build Rust backend

For iOS device (ARM64):

cargo make --profile development-ios-arm64 appflowy-core-dev-ios

For iOS simulator (Apple Silicon):

cargo make --profile development-ios-arm64-sim appflowy-core-dev-ios

This command:

Compiles Rust as a static library (.a)
Uses cargo-lipo for iOS targets
Copies the library to appflowy_flutter/packages/appflowy_backend/ios/

Install Flutter dependencies

cd appflowy_flutter
flutter pub get
cd ios
pod install

Run on simulator or device

cd ..
flutter run -d ios

Or open in Xcode:

open ios/Runner.xcworkspace

Production Build

Build Rust backend (release)

cargo make --profile production-ios-arm64 appflowy-core-dev-ios

Build iOS app

cd appflowy_flutter
flutter build ios --release

Archive and distribute

Open in Xcode:

open ios/Runner.xcworkspace

Then:

Product → Archive
Distribute App
Follow App Store Connect workflow

iOS builds use staticlib (.a) format for compatibility with iOS apps.

Building for Android

Development Build

Build Rust backend

For ARM64 devices (most common):

cargo make --profile development-android appflowy-core-dev-android

This command:

Compiles Rust as a shared library (.so)
Uses cargo-ndk to build for Android
Copies JNI libs to appflowy_flutter/android/app/src/main/jniLibs/

Install Flutter dependencies

cd appflowy_flutter
flutter pub get

Run on emulator or device

flutter run -d android

Production Build

Build Rust backend (release)

cargo make --profile production-android appflowy-core-dev-android

Build Android APK

cd appflowy_flutter
flutter build apk --release

The APK will be at:

build/app/outputs/flutter-apk/app-release.apk

Build Android App Bundle (AAB)

For Play Store distribution:

flutter build appbundle --release

The AAB will be at:

build/app/outputs/bundle/release/app-release.aab

Android builds use cdylib (.so) format as JNI shared libraries.

Multi-Architecture Builds

iOS Universal Library

For supporting multiple iOS architectures:

# Build for device and simulator
cargo lipo --release \
  --targets aarch64-apple-ios,aarch64-apple-ios-sim \
  --package=dart-ffi

This creates a universal library that works on both devices and simulators.

Android Multi-ABI

For CI/production builds supporting multiple architectures:

cargo make --profile production-android appflowy-core-dev-android-ci

This builds for:

arm64-v8a (ARM64) - Modern devices
armeabi-v7a (ARMv7) - Older devices

Building for multiple ABIs significantly increases APK/AAB size.

Build Targets

iOS Targets

Target	Architecture	Use Case
`aarch64-apple-ios`	ARM64	iOS devices (iPhone, iPad)
`aarch64-apple-ios-sim`	ARM64	iOS simulator on Apple Silicon Macs
`x86_64-apple-ios`	x86_64	iOS simulator on Intel Macs

Android Targets

Target	Architecture	Use Case
`aarch64-linux-android`	ARM64	Modern Android devices (2019+)
`armv7-linux-androideabi`	ARMv7	Older Android devices

ARMv7 support may be deprecated in future versions. ARM64 covers 95%+ of active Android devices.

Platform-Specific Configuration

iOS Configuration

Minimum iOS Version: 11.0 In appflowy_flutter/ios/Podfile:

platform :ios, '11.0'

Info.plist Configuration: Ensure proper permissions are set in ios/Runner/Info.plist:

<key>NSPhotoLibraryUsageDescription</key>
<string>AppFlowy needs access to photos</string>
<key>NSCameraUsageDescription</key>
<string>AppFlowy needs access to camera</string>

Android Configuration

Minimum Android Version: API 29 (Android 10) In appflowy_flutter/android/app/build.gradle:

android {
    defaultConfig {
        minSdkVersion 29
        targetSdkVersion 34
    }
}

Permissions: In android/app/src/main/AndroidManifest.xml:

<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />

Device Testing

iOS Simulator

List available simulators

xcrun simctl list devices

Launch simulator

open -a Simulator

Run app

flutter run -d <simulator-id>

iOS Device

Connect device

Connect your iPhone/iPad via USB.

Trust computer

Unlock device and trust the computer.

Configure signing

Open Xcode and configure automatic signing:

open ios/Runner.xcworkspace

Select your team in Signing & Capabilities.

Run app

flutter run

Android Emulator

Create AVD

In Android Studio:

Tools → Device Manager
Create Virtual Device
Select a device (e.g., Pixel 6)
Download a system image (Android 10+)

Start emulator

flutter emulators --launch <emulator-id>

Run app

flutter run

Android Device

Enable developer options

On your Android device:

Settings → About phone
Tap “Build number” 7 times

Enable USB debugging

Settings → Developer options → Enable USB debugging

Connect device

Connect via USB and authorize the computer.

Verify connection

flutter devices

Run app

flutter run

Troubleshooting

Common mobile build issues and solutions:

iOS Build Fails

Simulator stdbool.h error
Pod install fails
Code signing error

If you see stdbool.h file not found when building for simulator:

export SDKROOT=$(xcrun --sdk iphonesimulator --show-sdk-path)
export BINDGEN_EXTRA_CLANG_ARGS="-target arm64-apple-ios14.0-simulator"

Then rebuild:

cargo make --profile development-ios-arm64-sim appflowy-core-dev-ios

cd appflowy_flutter/ios
pod deintegrate
pod install

Open Xcode:

open ios/Runner.xcworkspace

Select Runner target
Signing & Capabilities
Select your team
Change bundle identifier if needed

Android Build Fails

NDK not found
Gradle build fails
Library not found

Install NDK through Android Studio:

Tools → SDK Manager
SDK Tools tab
Check “NDK (Side by side)”
Apply

Then set environment variable:

export ANDROID_NDK_HOME=$ANDROID_HOME/ndk/<version>

cd appflowy_flutter/android
./gradlew clean
cd ..
flutter clean
flutter pub get

Verify JNI libraries exist:

ls -la appflowy_flutter/android/app/src/main/jniLibs/arm64-v8a/

Should contain libdart_ffi.so.

Hot Reload & Development

Hot Reload

Flutter’s hot reload works on mobile:

# Press 'r' in terminal to hot reload
# Press 'R' to hot restart
# Press 'q' to quit

Hot reload only works for Dart code changes. Rust changes require a full rebuild.

Debugging

Flutter DevTools
iOS Logs
Android Logs

flutter run --debug
# Then press 'w' to open DevTools

# Terminal 1: Run app
flutter run

# Terminal 2: View logs
xcrun simctl spawn booted log stream --predicate 'processImagePath contains "Runner"'

# Terminal 1: Run app
flutter run

# Terminal 2: View logs
adb logcat | grep flutter

App Distribution

iOS App Store

Configure App Store Connect

Create app in App Store Connect
Configure metadata, screenshots
Set up TestFlight for beta testing

Build and archive

flutter build ios --release

Then archive in Xcode:

Open ios/Runner.xcworkspace
Product → Archive
Distribute App → App Store Connect

Google Play Store

Create Play Console app

Create app in Google Play Console
Configure store listing
Set up internal testing track

Generate signing key

keytool -genkey -v -keystore ~/appflowy.jks \
  -keyalg RSA -keysize 2048 -validity 10000 \
  -alias appflowy

Configure signing

Create android/key.properties:

storePassword=<password>
keyPassword=<password>
keyAlias=appflowy
storeFile=<path-to-jks>

Build and upload

flutter build appbundle --release

Upload build/app/outputs/bundle/release/app-release.aab to Play Console.

Next Steps

Testing

Learn how to run tests

Contributing

Contribute your changes

Building Desktop

Build for desktop platforms

Code Style

Follow coding conventions

​Prerequisites

​iOS Setup

​Android Setup

​Building for iOS

​Development Build

​Production Build

​Building for Android

​Development Build

​Production Build

​Multi-Architecture Builds

​iOS Universal Library

​Android Multi-ABI

​Build Targets

​iOS Targets

​Android Targets

​Platform-Specific Configuration

​iOS Configuration

​Android Configuration

​Device Testing

​iOS Simulator

​iOS Device

​Android Emulator

​Android Device

​Troubleshooting

​iOS Build Fails

​Android Build Fails

​Hot Reload & Development

​Hot Reload

​Debugging

​App Distribution

​iOS App Store

​Google Play Store

​Next Steps

Testing

Contributing

Building Desktop

Code Style

Prerequisites

iOS Setup

Android Setup

Building for iOS

Development Build

Production Build

Building for Android

Development Build

Production Build

Multi-Architecture Builds

iOS Universal Library

Android Multi-ABI

Build Targets

iOS Targets

Android Targets

Platform-Specific Configuration

iOS Configuration

Android Configuration

Device Testing

iOS Simulator

iOS Device

Android Emulator

Android Device

Troubleshooting

iOS Build Fails

Android Build Fails

Hot Reload & Development

Hot Reload

Debugging

App Distribution

iOS App Store

Google Play Store

Next Steps