Development Environment Setup

Set up your development environment to build AppFlowy from source

This guide will help you set up your development environment for building and running AppFlowy from source.

Prerequisites

Flutter SDK

Version 3.13.19 or higher

Rust Toolchain

Version 1.70 or higher

Git

For cloning the repository

Build Tools

Platform-specific compilers and SDKs

Installing Flutter

1. Download Flutter SDK

   Download the Flutter SDK from the official website:

   macOS

   # Download Flutter
   cd ~/development
   git clone https://github.com/flutter/flutter.git -b stable
   
   # Add to PATH
   export PATH="$PATH:$HOME/development/flutter/bin"
   

   Linux

   # Download Flutter
   cd ~/development
   git clone https://github.com/flutter/flutter.git -b stable
   
   # Add to PATH
   export PATH="$PATH:$HOME/development/flutter/bin"
   

   Windows

   Download the Flutter SDK zip file and extract it to C:\src\flutter.

   Add C:\src\flutter\bin to your PATH environment variable.

2. Verify installation

   flutter --version
   flutter doctor
   

   The output should show Flutter 3.13.19 or higher.

3. Install required Flutter dependencies

   flutter doctor --android-licenses  # Accept Android licenses if building for mobile
   flutter config --enable-macos-desktop  # Enable desktop support
   flutter config --enable-linux-desktop
   flutter config --enable-windows-desktop
   

Installing Rust

1. Install rustup

   macOS/Linux

   curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
   

   Windows

   Download and run rustup-init.exe.

2. Verify installation

   rustc --version
   cargo --version
   

   You should see Rust 1.70 or higher.

3. Install required Rust components

   # Install the stable toolchain
   rustup default stable
   
   # Add platform targets
   rustup target add aarch64-apple-darwin    # macOS ARM
   rustup target add x86_64-apple-darwin     # macOS Intel
   rustup target add x86_64-pc-windows-msvc  # Windows
   rustup target add x86_64-unknown-linux-gnu # Linux
   

Installing cargo-make

AppFlowy uses cargo-make for build automation:

cargo install cargo-make

Verify installation:

cargo make --version

Platform-Specific Setup

macOS

macOS Requirements

1. Install Xcode

   Install Xcode from the App Store or download from developer.apple.com.

   # Install Xcode Command Line Tools
   xcode-select --install
   
   # Accept license
   sudo xcodebuild -license accept
   
2. Install Homebrew

   /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
   
3. Install dependencies

   brew install protobuf
   

Linux

Linux Requirements

1. Install build essentials

   Ubuntu/Debian

   sudo apt-get update
   sudo apt-get install -y \
     curl \
     build-essential \
     libssl-dev \
     clang \
     cmake \
     ninja-build \
     pkg-config \
     libgtk-3-dev \
     libsqlite3-dev \
     protobuf-compiler
   

Windows

Windows Requirements

1. Install Visual Studio

   Download and install Visual Studio 2022.

   During installation, select:

   • Desktop development with C++
   • Windows 10/11 SDK
2. Install vcpkg

   # Clone vcpkg
   git clone https://github.com/Microsoft/vcpkg.git C:\vcpkg
   cd C:\vcpkg
   .\bootstrap-vcpkg.bat
   
   # Install dependencies
   .\vcpkg install protobuf:x64-windows
   
3. Set environment variables

   Add to your system PATH:

   • C:\vcpkg
   • C:\src\flutter\bin

Clone the Repository

1. Clone AppFlowy

   git clone https://github.com/AppFlowy-IO/AppFlowy.git
   cd AppFlowy
   
2. Navigate to frontend

   cd frontend
   

Repository Structure

Understanding the repository layout:

AppFlowy/
├── frontend/
│   ├── appflowy_flutter/    # Flutter application
│   ├── rust-lib/            # Rust backend
│   ├── scripts/             # Build scripts
│   └── Makefile.toml        # Build configuration
├── doc/                     # Documentation
├── README.md
└── LICENSE

All build commands should be run from the frontend/ directory.

Verify Setup

1. Check Flutter

   flutter doctor -v
   

   Ensure all required components are installed.

2. Check Rust

   rustc --version
   cargo --version
   cargo make --version
   
3. Install Flutter dependencies

   cd appflowy_flutter
   flutter pub get
   

IDE Setup

VS Code

Visual Studio Code

Install recommended extensions:

{
  "recommendations": [
    "dart-code.dart-code",
    "dart-code.flutter",
    "rust-lang.rust-analyzer",
    "tamasfe.even-better-toml",
    "vadimcn.vscode-lldb"
  ]
}

Open the workspace:

code AppFlowy/

Android Studio

Android Studio / IntelliJ IDEA

Install plugins:

• Flutter
• Dart
• Rust

Open the project:

• File → Open
• Select the AppFlowy/frontend/appflowy_flutter directory

Build Tools

Protobuf

AppFlowy uses Protocol Buffers for serialization:

# Verify protobuf installation
protoc --version

If not installed:

macOS

brew install protobuf

Linux

# Ubuntu/Debian
sudo apt-get install protobuf-compiler

# Fedora
sudo dnf install protobuf-compiler

Windows

# Using vcpkg
vcpkg install protobuf:x64-windows

Next Steps

Now that your environment is set up, you can build AppFlowy:

Building Desktop

Build AppFlowy for macOS, Windows, or Linux

Building Mobile

Build AppFlowy for iOS or Android

Architecture

Learn about AppFlowy’s architecture

Contributing

Start contributing to AppFlowy

Troubleshooting

If you encounter issues during setup, check the following:

Common Issues

Flutter

Flutter doctor shows issues:

# Update Flutter
flutter upgrade

# Clean and reinstall
flutter clean
flutter pub get

Rust

Rust compilation fails:

# Update Rust
rustup update

# Clean build
cargo clean

Protobuf

Protobuf errors:

Make sure protoc is in your PATH:

which protoc  # macOS/Linux
where protoc  # Windows

For more help, join the AppFlowy Discord community.