Building for Desktop

Build AppFlowy for macOS, Windows, and Linux platforms

This guide covers building AppFlowy for desktop platforms (macOS, Windows, and Linux) from source.

Prerequisites

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

All commands should be run from the frontend/ directory.

Quick Start

1. Navigate to frontend

   cd AppFlowy/frontend
   
2. Build for your platform

   macOS

   # For Apple Silicon (M1/M2/M3)
   cargo make --profile development-mac-arm64 appflowy-core-dev
   
   # For Intel Macs
   cargo make --profile development-mac-x86_64 appflowy-core-dev
   

   Windows

   cargo make --profile development-windows-x86 appflowy-core-dev
   

   Linux

   cargo make --profile development-linux-x86_64 appflowy-core-dev
   
3. Run Flutter app

   cd appflowy_flutter
   flutter run
   

Build Profiles

AppFlowy uses cargo-make with different build profiles:

Profile	Target	Build Type	Use Case
development-mac-arm64	macOS ARM64	Debug	Development on Apple Silicon
development-mac-x86_64	macOS x86_64	Debug	Development on Intel Macs
production-mac-arm64	macOS ARM64	Release	Production builds for Apple Silicon
production-mac-x86_64	macOS x86_64	Release	Production builds for Intel
production-mac-universal	Universal	Release	Universal binary (both architectures)
development-windows-x86	Windows x64	Debug	Development on Windows
production-windows-x86	Windows x64	Release	Production builds for Windows
development-linux-x86_64	Linux x64	Debug	Development on Linux
production-linux-x86_64	Linux x64	Release	Production builds for Linux

Building the Rust Backend

Development Build

macOS

1. Choose architecture

   # Apple Silicon (M1/M2/M3)
   export ARCH=arm64
   
   # Intel
   export ARCH=x86_64
   
2. Build Rust backend

   cargo make --profile development-mac-${ARCH} appflowy-core-dev
   

   This command:

   • Compiles the Rust backend as a static library
   • Copies the library to the Flutter app
   • Generates FFI bindings

macOS builds use staticlib (.a) for better integration with the app bundle.

Windows

1. Build Rust backend

   cargo make --profile development-windows-x86 appflowy-core-dev
   

Windows builds use cdylib (.dll) as a dynamic library.

Linux

1. Build Rust backend

   cargo make --profile development-linux-x86_64 appflowy-core-dev
   

Linux builds use cdylib (.so) as a shared library.

Production Build

Production builds are optimized with LTO and higher optimization levels:

macOS (Universal)

cargo make --profile production-mac-universal appflowy-core-release

Building the Flutter App

Development Mode

1. Navigate to Flutter directory

   cd appflowy_flutter
   
2. Install dependencies

   flutter pub get
   
3. Generate code

   flutter pub run build_runner build --delete-conflicting-outputs
   
4. Run the app

   flutter run -d macos    # macOS
   flutter run -d windows  # Windows
   flutter run -d linux    # Linux
   

Release Build

macOS

cd appflowy_flutter
flutter build macos --release

The app will be at:

appflowy_flutter/build/macos/Build/Products/Release/AppFlowy.app

Windows

cd appflowy_flutter
flutter build windows --release

The app will be at:

appflowy_flutter/build/windows/runner/Release/

Linux

cd appflowy_flutter
flutter build linux --release

The app will be at:

appflowy_flutter/build/linux/x64/release/bundle/

Build Configuration

Makefile.toml

The build process is configured in frontend/Makefile.toml:

[env]
RUST_LOG = "info"
CARGO_PROFILE = "dev"
APPFLOWY_VERSION = "0.9.9"
PRODUCT_NAME = "AppFlowy"

Environment Variables

Key environment variables:

Variable	Description
BUILD_FLAG	debug or release
RUST_COMPILE_TARGET	Target triple (e.g., aarch64-apple-darwin)
CRATE_TYPE	staticlib or cdylib
TARGET_OS	macos, windows, or linux
FLUTTER_DESKTOP_FEATURES	Rust features to enable

Platform-Specific Details

macOS

macOS Build Details

Crate Type: Static library (.a)

Build Targets:

• aarch64-apple-darwin (Apple Silicon)
• x86_64-apple-darwin (Intel)

Universal Binary:

To create a universal binary that runs on both architectures:

# Build for both architectures
cargo make --profile production-mac-arm64 appflowy-core-release
cargo make --profile production-mac-x86_64 appflowy-core-release

# Combine with lipo
lipo -create \
  target/aarch64-apple-darwin/release/libdart_ffi.a \
  target/x86_64-apple-darwin/release/libdart_ffi.a \
  -output libdart_ffi.a

Code Signing:

For distribution, you’ll need to sign the app:

codesign --deep --force --verify --verbose \
  --sign "Developer ID Application: Your Name" \
  AppFlowy.app

Windows

Windows Build Details

Crate Type: Dynamic library (.dll)

Build Target: x86_64-pc-windows-msvc

Visual Studio Requirement:

Ensure you have Visual Studio 2022 with C++ build tools installed.

Library Location:

The DLL is copied to:

appflowy_flutter/windows/flutter/dart_ffi/dart_ffi.dll

Dependencies:

Windows builds may require Visual C++ Redistributable:

• VC++ Redistributable

Linux

Linux Build Details

Crate Type: Shared library (.so)

Build Targets:

• x86_64-unknown-linux-gnu
• aarch64-unknown-linux-gnu (ARM64)

Library Location:

The shared library is copied to:

appflowy_flutter/linux/flutter/dart_ffi/libdart_ffi.so

System Dependencies:

Runtime dependencies include:

• GTK 3
• SQLite 3
• OpenSSL

On Ubuntu/Debian:

sudo apt-get install libgtk-3-0 libsqlite3-0 libssl3

Clean Build

To clean all build artifacts:

# Clean Rust
cd rust-lib
cargo clean

# Clean Flutter
cd ../appflowy_flutter
flutter clean

Troubleshooting

Common build issues and solutions:

Rust Build Fails

# Update Rust toolchain
rustup update

# Ensure target is installed
rustup target add <your-target>

# Clean and rebuild
cargo clean
cargo make --profile <your-profile> appflowy-core-dev

Flutter Build Fails

# Clean Flutter cache
flutter clean
flutter pub get

# Regenerate code
flutter pub run build_runner clean
flutter pub run build_runner build --delete-conflicting-outputs

Library Not Found

macOS

# Verify library exists
ls -la appflowy_flutter/packages/appflowy_backend/macos/

# Should contain libdart_ffi.a

Windows

# Verify DLL exists
dir appflowy_flutter\windows\flutter\dart_ffi\

# Should contain dart_ffi.dll

Linux

# Verify library exists
ls -la appflowy_flutter/linux/flutter/dart_ffi/

# Should contain libdart_ffi.so

Protobuf Errors

# Ensure protoc is installed
protoc --version

# Regenerate protobuf files
cd frontend
cargo make install_flutter_protobuf

Performance Optimization

Build Times

To improve build times:

1. Use incremental compilation

   export CARGO_INCREMENTAL=1
   
2. Use cargo cache

   cargo install cargo-cache
   
3. Parallel jobs

   # Set number of parallel jobs
   export CARGO_BUILD_JOBS=8
   

Release Optimization

The production profile uses:

[profile.release]
lto = true              # Link-time optimization
opt-level = 3           # Maximum optimization
codegen-units = 1       # Better optimization, slower build

Next Steps

Building Mobile

Build AppFlowy for iOS and Android

Testing

Learn how to run tests

Contributing

Contribute your changes

Code Style

Follow coding conventions