> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/AppFlowy-IO/AppFlowy/llms.txt
> Use this file to discover all available pages before exploring further.

# Building for Mobile

> Build AppFlowy for iOS and Android platforms

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

## Prerequisites

Before building, ensure you have completed the [development environment setup](/developer/setup).

<Note>
  All commands should be run from the `frontend/` directory.
</Note>

## iOS Setup

<Steps>
  <Step title="Install Xcode">
    Download and install Xcode from the App Store or [developer.apple.com](https://developer.apple.com/xcode/).

    ```bash theme={null}
    # Install Command Line Tools
    xcode-select --install

    # Accept license
    sudo xcodebuild -license accept
    ```
  </Step>

  <Step title="Install CocoaPods">
    ```bash theme={null}
    sudo gem install cocoapods
    pod --version
    ```
  </Step>

  <Step title="Install cargo-lipo">
    For building iOS universal libraries:

    ```bash theme={null}
    cargo install cargo-lipo
    ```
  </Step>

  <Step title="Add iOS targets">
    ```bash theme={null}
    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)
    ```
  </Step>
</Steps>

## Android Setup

<Steps>
  <Step title="Install Android Studio">
    Download from [developer.android.com](https://developer.android.com/studio).
  </Step>

  <Step title="Install Android SDK">
    Through Android Studio:

    * SDK Platforms: Android 10+ (API 29+)
    * SDK Tools: NDK, CMake
  </Step>

  <Step title="Set environment variables">
    <Tabs>
      <Tab title="macOS/Linux">
        ```bash theme={null}
        export ANDROID_HOME=$HOME/Android/Sdk
        export ANDROID_NDK_HOME=$ANDROID_HOME/ndk/<version>
        export PATH=$PATH:$ANDROID_HOME/platform-tools
        ```
      </Tab>

      <Tab title="Windows">
        ```powershell theme={null}
        $env:ANDROID_HOME = "C:\Users\<username>\AppData\Local\Android\Sdk"
        $env:ANDROID_NDK_HOME = "$env:ANDROID_HOME\ndk\<version>"
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Install cargo-ndk">
    For building Android libraries:

    ```bash theme={null}
    cargo install cargo-ndk
    ```
  </Step>

  <Step title="Add Android targets">
    ```bash theme={null}
    rustup target add aarch64-linux-android     # ARM64 (most devices)
    rustup target add armv7-linux-androideabi   # ARMv7 (older devices)
    ```
  </Step>
</Steps>

## Building for iOS

### Development Build

<Steps>
  <Step title="Build Rust backend">
    For iOS device (ARM64):

    ```bash theme={null}
    cargo make --profile development-ios-arm64 appflowy-core-dev-ios
    ```

    For iOS simulator (Apple Silicon):

    ```bash theme={null}
    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/`
  </Step>

  <Step title="Install Flutter dependencies">
    ```bash theme={null}
    cd appflowy_flutter
    flutter pub get
    cd ios
    pod install
    ```
  </Step>

  <Step title="Run on simulator or device">
    ```bash theme={null}
    cd ..
    flutter run -d ios
    ```

    Or open in Xcode:

    ```bash theme={null}
    open ios/Runner.xcworkspace
    ```
  </Step>
</Steps>

### Production Build

<Steps>
  <Step title="Build Rust backend (release)">
    ```bash theme={null}
    cargo make --profile production-ios-arm64 appflowy-core-dev-ios
    ```
  </Step>

  <Step title="Build iOS app">
    ```bash theme={null}
    cd appflowy_flutter
    flutter build ios --release
    ```
  </Step>

  <Step title="Archive and distribute">
    Open in Xcode:

    ```bash theme={null}
    open ios/Runner.xcworkspace
    ```

    Then:

    1. Product → Archive
    2. Distribute App
    3. Follow App Store Connect workflow
  </Step>
</Steps>

<Note>
  iOS builds use **staticlib** (.a) format for compatibility with iOS apps.
</Note>

## Building for Android

### Development Build

<Steps>
  <Step title="Build Rust backend">
    For ARM64 devices (most common):

    ```bash theme={null}
    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/`
  </Step>

  <Step title="Install Flutter dependencies">
    ```bash theme={null}
    cd appflowy_flutter
    flutter pub get
    ```
  </Step>

  <Step title="Run on emulator or device">
    ```bash theme={null}
    flutter run -d android
    ```
  </Step>
</Steps>

### Production Build

<Steps>
  <Step title="Build Rust backend (release)">
    ```bash theme={null}
    cargo make --profile production-android appflowy-core-dev-android
    ```
  </Step>

  <Step title="Build Android APK">
    ```bash theme={null}
    cd appflowy_flutter
    flutter build apk --release
    ```

    The APK will be at:

    ```
    build/app/outputs/flutter-apk/app-release.apk
    ```
  </Step>

  <Step title="Build Android App Bundle (AAB)">
    For Play Store distribution:

    ```bash theme={null}
    flutter build appbundle --release
    ```

    The AAB will be at:

    ```
    build/app/outputs/bundle/release/app-release.aab
    ```
  </Step>
</Steps>

<Note>
  Android builds use **cdylib** (.so) format as JNI shared libraries.
</Note>

## Multi-Architecture Builds

### iOS Universal Library

For supporting multiple iOS architectures:

```bash theme={null}
# 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:

```bash theme={null}
cargo make --profile production-android appflowy-core-dev-android-ci
```

This builds for:

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

<Warning>
  Building for multiple ABIs significantly increases APK/AAB size.
</Warning>

## 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          |

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

## Platform-Specific Configuration

### iOS Configuration

**Minimum iOS Version:** 11.0

In `appflowy_flutter/ios/Podfile`:

```ruby theme={null}
platform :ios, '11.0'
```

**Info.plist Configuration:**

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

```xml theme={null}
<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`:

```gradle theme={null}
android {
    defaultConfig {
        minSdkVersion 29
        targetSdkVersion 34
    }
}
```

**Permissions:**

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

```xml theme={null}
<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

<Steps>
  <Step title="List available simulators">
    ```bash theme={null}
    xcrun simctl list devices
    ```
  </Step>

  <Step title="Launch simulator">
    ```bash theme={null}
    open -a Simulator
    ```
  </Step>

  <Step title="Run app">
    ```bash theme={null}
    flutter run -d <simulator-id>
    ```
  </Step>
</Steps>

### iOS Device

<Steps>
  <Step title="Connect device">
    Connect your iPhone/iPad via USB.
  </Step>

  <Step title="Trust computer">
    Unlock device and trust the computer.
  </Step>

  <Step title="Configure signing">
    Open Xcode and configure automatic signing:

    ```bash theme={null}
    open ios/Runner.xcworkspace
    ```

    Select your team in Signing & Capabilities.
  </Step>

  <Step title="Run app">
    ```bash theme={null}
    flutter run
    ```
  </Step>
</Steps>

### Android Emulator

<Steps>
  <Step title="Create AVD">
    In Android Studio:

    1. Tools → Device Manager
    2. Create Virtual Device
    3. Select a device (e.g., Pixel 6)
    4. Download a system image (Android 10+)
  </Step>

  <Step title="Start emulator">
    ```bash theme={null}
    flutter emulators --launch <emulator-id>
    ```
  </Step>

  <Step title="Run app">
    ```bash theme={null}
    flutter run
    ```
  </Step>
</Steps>

### Android Device

<Steps>
  <Step title="Enable developer options">
    On your Android device:

    1. Settings → About phone
    2. Tap "Build number" 7 times
  </Step>

  <Step title="Enable USB debugging">
    Settings → Developer options → Enable USB debugging
  </Step>

  <Step title="Connect device">
    Connect via USB and authorize the computer.
  </Step>

  <Step title="Verify connection">
    ```bash theme={null}
    flutter devices
    ```
  </Step>

  <Step title="Run app">
    ```bash theme={null}
    flutter run
    ```
  </Step>
</Steps>

## Troubleshooting

<Warning>
  Common mobile build issues and solutions:
</Warning>

### iOS Build Fails

<Tabs>
  <Tab title="Simulator stdbool.h error">
    If you see `stdbool.h file not found` when building for simulator:

    ```bash theme={null}
    export SDKROOT=$(xcrun --sdk iphonesimulator --show-sdk-path)
    export BINDGEN_EXTRA_CLANG_ARGS="-target arm64-apple-ios14.0-simulator"
    ```

    Then rebuild:

    ```bash theme={null}
    cargo make --profile development-ios-arm64-sim appflowy-core-dev-ios
    ```
  </Tab>

  <Tab title="Pod install fails">
    ```bash theme={null}
    cd appflowy_flutter/ios
    pod deintegrate
    pod install
    ```
  </Tab>

  <Tab title="Code signing error">
    Open Xcode:

    ```bash theme={null}
    open ios/Runner.xcworkspace
    ```

    1. Select Runner target
    2. Signing & Capabilities
    3. Select your team
    4. Change bundle identifier if needed
  </Tab>
</Tabs>

### Android Build Fails

<Tabs>
  <Tab title="NDK not found">
    Install NDK through Android Studio:

    1. Tools → SDK Manager
    2. SDK Tools tab
    3. Check "NDK (Side by side)"
    4. Apply

    Then set environment variable:

    ```bash theme={null}
    export ANDROID_NDK_HOME=$ANDROID_HOME/ndk/<version>
    ```
  </Tab>

  <Tab title="Gradle build fails">
    ```bash theme={null}
    cd appflowy_flutter/android
    ./gradlew clean
    cd ..
    flutter clean
    flutter pub get
    ```
  </Tab>

  <Tab title="Library not found">
    Verify JNI libraries exist:

    ```bash theme={null}
    ls -la appflowy_flutter/android/app/src/main/jniLibs/arm64-v8a/
    ```

    Should contain `libdart_ffi.so`.
  </Tab>
</Tabs>

## Hot Reload & Development

### Hot Reload

Flutter's hot reload works on mobile:

```bash theme={null}
# Press 'r' in terminal to hot reload
# Press 'R' to hot restart
# Press 'q' to quit
```

<Note>
  Hot reload only works for Dart code changes. Rust changes require a full rebuild.
</Note>

### Debugging

<Tabs>
  <Tab title="Flutter DevTools">
    ```bash theme={null}
    flutter run --debug
    # Then press 'w' to open DevTools
    ```
  </Tab>

  <Tab title="iOS Logs">
    ```bash theme={null}
    # Terminal 1: Run app
    flutter run

    # Terminal 2: View logs
    xcrun simctl spawn booted log stream --predicate 'processImagePath contains "Runner"'
    ```
  </Tab>

  <Tab title="Android Logs">
    ```bash theme={null}
    # Terminal 1: Run app
    flutter run

    # Terminal 2: View logs
    adb logcat | grep flutter
    ```
  </Tab>
</Tabs>

## App Distribution

### iOS App Store

<Steps>
  <Step title="Configure App Store Connect">
    1. Create app in App Store Connect
    2. Configure metadata, screenshots
    3. Set up TestFlight for beta testing
  </Step>

  <Step title="Build and archive">
    ```bash theme={null}
    flutter build ios --release
    ```

    Then archive in Xcode:

    1. Open `ios/Runner.xcworkspace`
    2. Product → Archive
    3. Distribute App → App Store Connect
  </Step>
</Steps>

### Google Play Store

<Steps>
  <Step title="Create Play Console app">
    1. Create app in Google Play Console
    2. Configure store listing
    3. Set up internal testing track
  </Step>

  <Step title="Generate signing key">
    ```bash theme={null}
    keytool -genkey -v -keystore ~/appflowy.jks \
      -keyalg RSA -keysize 2048 -validity 10000 \
      -alias appflowy
    ```
  </Step>

  <Step title="Configure signing">
    Create `android/key.properties`:

    ```properties theme={null}
    storePassword=<password>
    keyPassword=<password>
    keyAlias=appflowy
    storeFile=<path-to-jks>
    ```
  </Step>

  <Step title="Build and upload">
    ```bash theme={null}
    flutter build appbundle --release
    ```

    Upload `build/app/outputs/bundle/release/app-release.aab` to Play Console.
  </Step>
</Steps>

## Next Steps

<CardGroup cols={2}>
  <Card title="Testing" href="/developer/testing" icon="vial">
    Learn how to run tests
  </Card>

  <Card title="Contributing" href="/developer/contributing" icon="code-pull-request">
    Contribute your changes
  </Card>

  <Card title="Building Desktop" href="/developer/building-desktop" icon="desktop">
    Build for desktop platforms
  </Card>

  <Card title="Code Style" href="/developer/code-style" icon="paintbrush">
    Follow coding conventions
  </Card>
</CardGroup>