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
Build for your platform
# 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
cargo make --profile development-windows-x86 appflowy-core-dev
cargo make --profile development-linux-x86_64 appflowy-core-dev
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-arm64macOS ARM64 Debug Development on Apple Silicon development-mac-x86_64macOS x86_64 Debug Development on Intel Macs production-mac-arm64macOS ARM64 Release Production builds for Apple Silicon production-mac-x86_64macOS x86_64 Release Production builds for Intel production-mac-universalUniversal Release Universal binary (both architectures) development-windows-x86Windows x64 Debug Development on Windows production-windows-x86Windows x64 Release Production builds for Windows development-linux-x86_64Linux x64 Debug Development on Linux production-linux-x86_64Linux x64 Release Production builds for Linux
Building the Rust Backend Development Build
Choose architecture
# Apple Silicon (M1/M2/M3) export ARCH = arm64 # Intel export ARCH = x86_64
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.
Build Rust backend
cargo make --profile development-windows-x86 appflowy-core-dev
Windows builds use cdylib (.dll) as a dynamic library.
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)
Windows
Linux
cargo make --profile production-mac-universal appflowy-core-release
Building the Flutter App Development Mode
Navigate to Flutter directory
Generate code
flutter pub run build_runner build --delete-conflicting-outputs
Run the app
flutter run -d macos # macOS flutter run -d windows # Windows flutter run -d linux # Linux
Release Build cd appflowy_flutter flutter build macos --release
The app will be at: appflowy_flutter/build/macos/Build/Products/Release/AppFlowy.app
cd appflowy_flutter flutter build windows --release
The app will be at: appflowy_flutter/build/windows/runner/Release/
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_FLAGdebug or releaseRUST_COMPILE_TARGETTarget triple (e.g., aarch64-apple-darwin) CRATE_TYPEstaticlib or cdylibTARGET_OSmacos, windows, or linuxFLUTTER_DESKTOP_FEATURESRust features to enable
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 Build Details Crate Type: Dynamic library (.dll)Build Target: x86_64-pc-windows-msvcVisual 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: Linux Build Details Crate Type: Shared library (.so)Build Targets:
x86_64-unknown-linux-gnuaarch64-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: 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-targe t > # Clean and rebuild cargo clean cargo make --profile < your-profil e > 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 # Verify library exists ls -la appflowy_flutter/packages/appflowy_backend/macos/ # Should contain libdart_ffi.a
# Verify DLL exists dir appflowy_flutter \w indows \f lutter \d art_ffi \ # Should contain dart_ffi.dll
# 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
Build Times To improve build times:
Use incremental compilation
export CARGO_INCREMENTAL = 1
Use cargo cache
cargo install cargo-cache
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
