fix: Address code review feedback

Akhash16 · Akhash16 · commit c3c839098a6c · 2025-08-09T23:48:21.000-07:00
- Remove .history folders from commit - Fix 'macOS' spelling (was 'MacOS') - Add armeabi-v7a target to Windows Android build scripts for ABI parity - Remove duplicated Android setup instructions, reference dedicated guide instead - Remove unrelated Android app files from commit scope Addresses feedback from PR #8163
diff --git a/README.md b/README.md
@@ -63,8 +63,9 @@ AppFlowy is the AI workspace where you achieve more without losing control of yo
 
 ## Getting Started with development
 
-Please view the [documentation](https://docs.appflowy.io/docs/documentation/appflowy/from-source) for OS specific
-development instructions
+Please view our comprehensive [build from source guide](doc/BUILD_FROM_SOURCE.md) for detailed OS-specific development instructions, including desktop and mobile platform support.
+
+For additional documentation, visit [docs.appflowy.io](https://docs.appflowy.io/docs/documentation/appflowy/from-source).
 
 ## Roadmap
 
diff --git a/doc/BUILD_FROM_SOURCE.md b/doc/BUILD_FROM_SOURCE.md
@@ -0,0 +1,160 @@
+# Building AppFlowy from Source
+
+This guide provides comprehensive instructions for building AppFlowy from source code on all supported platforms.
+
+## Prerequisites
+
+Before building AppFlowy, ensure you have the following installed:
+
+### All Platforms
+- [Git](https://git-scm.com/)
+- [Rust](https://rustup.rs/) (1.70 or later)
+- [Flutter](https://flutter.dev/docs/get-started/install) (3.13.19 or later)
+- [cargo-make](https://github.com/sagiegurari/cargo-make) - Install with: `cargo install cargo-make`
+
+### Platform-Specific Requirements
+
+#### Windows
+- [Visual Studio 2019/2022](https://visualstudio.microsoft.com/) with C++ development tools
+- [vcpkg](https://github.com/microsoft/vcpkg)
+
+#### macOS
+- Xcode Command Line Tools: `xcode-select --install`
+
+#### Linux
+- Build essentials: `sudo apt install build-essential pkg-config libssl-dev`
+- Additional dependencies: `sudo apt install clang cmake ninja-build pkg-config libgtk-3-dev`
+
+## Building for Desktop
+
+### 1. Clone the Repository
+```bash
+git clone https://github.com/AppFlowy-IO/AppFlowy.git
+cd AppFlowy
+```
+
+### 2. Build for Your Platform
+
+#### Windows
+```bash
+cd frontend
+cargo make appflowy-windows
+```
+
+#### macOS
+```bash
+cd frontend
+cargo make appflowy-macos
+```
+
+#### Linux
+```bash
+cd frontend
+cargo make appflowy-linux
+```
+
+### 3. Run the Application
+
+After building, the executable will be located in:
+- **Windows**: `frontend/appflowy_flutter/product/[version]/windows/Release/AppFlowy/`
+- **macOS**: `frontend/appflowy_flutter/product/[version]/macos/Release/AppFlowy.app/`
+- **Linux**: `frontend/appflowy_flutter/product/[version]/linux/Release/AppFlowy/`
+
+## Building for Mobile
+
+### iOS
+
+#### Prerequisites
+- macOS with Xcode installed
+- iOS development setup for Flutter
+
+#### Build Steps
+```bash
+cd frontend
+cargo make appflowy-ios
+```
+
+The iOS app will be built and available in `frontend/appflowy_flutter/build/ios/`.
+
+### Android
+
+#### Prerequisites
+
+**All Platforms:**
+- [Android NDK](https://developer.android.com/ndk/downloads/) version 24
+- cargo-ndk: `cargo install cargo-ndk`
+
+#### Detailed Setup Instructions
+
+For comprehensive Android build setup including Windows support, please refer to the [Android-specific build guide](../frontend/appflowy_flutter/android/README.md) which covers:
+
+- Platform-specific environment variable setup
+- Cargo configuration for all operating systems
+- NDK 24 clang fixes
+- Path configuration
+- Troubleshooting common issues
+
+#### Build Steps
+```bash
+cd frontend
+cargo make appflowy-android
+```
+
+The Android APK will be built and available in `frontend/appflowy_flutter/build/app/outputs/flutter-apk/`.
+
+## Development Builds
+
+For faster development builds without optimizations:
+
+### Desktop Development
+```bash
+cd frontend
+cargo make appflowy-dev  # Uses platform-specific aliases
+```
+
+### Mobile Development
+```bash
+# iOS development build
+cd frontend
+cargo make appflowy-ios-dev
+
+# Android development build
+cd frontend
+cargo make appflowy-android-dev
+```
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Flutter Doctor Issues**: Run `flutter doctor` to check for missing dependencies
+2. **Rust Version**: Ensure you're using Rust 1.70 or later
+3. **Path Issues**: Make sure all tools are in your system PATH
+4. **NDK Issues**: Verify ANDROID_NDK_HOME is set correctly
+
+### Platform-Specific Issues
+
+#### Windows
+- Ensure Visual Studio C++ tools are installed
+- Check that vcpkg is properly configured
+- Use PowerShell or Command Prompt, not Git Bash for building
+
+#### macOS
+- Ensure Xcode Command Line Tools are installed
+- For iOS builds, you need a full Xcode installation
+
+#### Linux
+- Install all required system dependencies
+- Check that pkg-config can find required libraries
+
+### Getting Help
+
+- Check the [AppFlowy Documentation](https://docs.appflowy.io/)
+- Join our [Discord](https://discord.gg/9Q2xaN37tV) for community support
+- Report issues on [GitHub](https://github.com/AppFlowy-IO/AppFlowy/issues)
+
+## Additional Resources
+
+- [AppFlowy Development Guide](https://docs.appflowy.io/docs/documentation/appflowy/from-source)
+- [Contributing Guidelines](CONTRIBUTING.md)
+- [Android-specific instructions](../frontend/appflowy_flutter/android/README.md)
diff --git a/frontend/appflowy_flutter/.metadata b/frontend/appflowy_flutter/.metadata
@@ -1,23 +1,23 @@
 # This file tracks properties of this Flutter project.
 # Used by Flutter tool to assess capabilities and perform upgrades etc.
 #
-# This file should be version controlled.
+# This file should be version controlled and should not be manually edited.
 
 version:
-  revision: 682aa387cfe4fbd71ccd5418b2c2a075729a1c66
-  channel: unknown
+  revision: "d8a9f9a52e5af486f80d932e838ee93861ffd863"
+  channel: "[user-branch]"
 
 project_type: app
 
 # Tracks metadata for the flutter migrate command
 migration:
   platforms:
     - platform: root
-      create_revision: 682aa387cfe4fbd71ccd5418b2c2a075729a1c66
-      base_revision: 682aa387cfe4fbd71ccd5418b2c2a075729a1c66
+      create_revision: d8a9f9a52e5af486f80d932e838ee93861ffd863
+      base_revision: d8a9f9a52e5af486f80d932e838ee93861ffd863
     - platform: android
-      create_revision: 682aa387cfe4fbd71ccd5418b2c2a075729a1c66
-      base_revision: 682aa387cfe4fbd71ccd5418b2c2a075729a1c66
+      create_revision: d8a9f9a52e5af486f80d932e838ee93861ffd863
+      base_revision: d8a9f9a52e5af486f80d932e838ee93861ffd863
 
   # User provided section
 
diff --git a/frontend/appflowy_flutter/README.md b/frontend/appflowy_flutter/README.md
@@ -32,7 +32,11 @@ To contribute to `AppFlowy_Flutter` codebase specifically (coding contribution)
 
 ### What OS should I use for development?
 
-We support all OS for Development i.e. Linux, MacOS and Windows. However, most of us promote macOS and Linux over Windows. We have detailed [docs](https://docs.appflowy.io/docs/documentation/appflowy/from-source/environment-setup) on how to setup `AppFlowy_Flutter` on your local system respectively per operating system.
+We support all OS for Development i.e. Linux, macOS and Windows. We have detailed documentation on how to setup `AppFlowy_Flutter` on your local system for each operating system:
+
+- [Build from Source Guide](../../doc/BUILD_FROM_SOURCE.md) - Comprehensive setup instructions for all platforms
+- [Android-specific Guide](android/README.md) - Detailed Android build instructions including Windows support
+- [Online Documentation](https://docs.appflowy.io/docs/documentation/appflowy/from-source/environment-setup) - Additional setup resources
 
 ### Getting Started ❇
 
diff --git a/frontend/appflowy_flutter/android/README.md b/frontend/appflowy_flutter/android/README.md
@@ -12,15 +12,28 @@ When compiling for android we need the following pre-requisites:
 - [Download](https://developer.android.com/ndk/downloads/) Android NDK version 24.
 - When downloading Android NDK you can get the compressed version as a standalone from the site.
     Or you can download it through [Android Studio](https://developer.android.com/studio).
-- After downloading the two you need to set the environment variables. For Windows that's a separate process.
-    On macOS and Linux the process is similar.
+- After downloading the two you need to set the environment variables. The process differs by operating system.
 - The variables needed are '$ANDROID_NDK_HOME', this will point to where the NDK is located.
+
+**Setting Environment Variables**
+
+**Windows:**
+```cmd
+set ANDROID_NDK_HOME=C:\Users\%USERNAME%\AppData\Local\Android\Sdk\ndk\24.0.8215888
+```
+Or add to your system environment variables permanently.
+
+**macOS/Linux:**
+```bash
+export ANDROID_NDK_HOME=~/Android/Sdk/ndk/24.0.8215888
+```
 ---
 
 **Cargo Config File**
-This code needs to be written in ~/.cargo/config, this helps cargo know where to locate the android tools(linker and archiver).
-**NB** Keep in mind just replace 'user' with your own user name. Or just point it to the location of where you put the NDK.
+This code needs to be written in `~/.cargo/config` (Linux/macOS) or `%USERPROFILE%\.cargo\config` (Windows). This helps cargo know where to locate the android tools (linker and archiver).
+**NB** Replace the paths with your actual NDK installation location.
 
+**Linux/macOS:**
 ```toml
 [target.aarch64-linux-android]
 ar = "/home/user/Android/Sdk/ndk/24.0.8215888/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-ar"
@@ -39,26 +52,68 @@ ar = "/home/user/Android/Sdk/ndk/24.0.8215888/toolchains/llvm/prebuilt/linux-x86
 linker = "/home/user/Android/Sdk/ndk/24.0.8215888/toolchains/llvm/prebuilt/linux-x86_64/bin/x86_64-linux-android29-clang"
 ```
 
+**Windows:**
+```toml
+[target.aarch64-linux-android]
+ar = "C:\\Users\\%USERNAME%\\AppData\\Local\\Android\\Sdk\\ndk\\24.0.8215888\\toolchains\\llvm\\prebuilt\\windows-x86_64\\bin\\llvm-ar.exe"
+linker = "C:\\Users\\%USERNAME%\\AppData\\Local\\Android\\Sdk\\ndk\\24.0.8215888\\toolchains\\llvm\\prebuilt\\windows-x86_64\\bin\\aarch64-linux-android29-clang.exe"
+
+[target.armv7-linux-androideabi]
+ar = "C:\\Users\\%USERNAME%\\AppData\\Local\\Android\\Sdk\\ndk\\24.0.8215888\\toolchains\\llvm\\prebuilt\\windows-x86_64\\bin\\llvm-ar.exe"
+linker = "C:\\Users\\%USERNAME%\\AppData\\Local\\Android\\Sdk\\ndk\\24.0.8215888\\toolchains\\llvm\\prebuilt\\windows-x86_64\\bin\\armv7a-linux-androideabi29-clang.exe"
+
+[target.i686-linux-android]
+ar = "C:\\Users\\%USERNAME%\\AppData\\Local\\Android\\Sdk\\ndk\\24.0.8215888\\toolchains\\llvm\\prebuilt\\windows-x86_64\\bin\\llvm-ar.exe"
+linker = "C:\\Users\\%USERNAME%\\AppData\\Local\\Android\\Sdk\\ndk\\24.0.8215888\\toolchains\\llvm\\prebuilt\\windows-x86_64\\bin\\i686-linux-android29-clang.exe"
+
+[target.x86_64-linux-android]
+ar = "C:\\Users\\%USERNAME%\\AppData\\Local\\Android\\Sdk\\ndk\\24.0.8215888\\toolchains\\llvm\\prebuilt\\windows-x86_64\\bin\\llvm-ar.exe"
+linker = "C:\\Users\\%USERNAME%\\AppData\\Local\\Android\\Sdk\\ndk\\24.0.8215888\\toolchains\\llvm\\prebuilt\\windows-x86_64\\bin\\x86_64-linux-android29-clang.exe"
+```
+
 **Clang Fix**
- In order to get clang to work properly with version 24 you need to create this file.
- libgcc.a, then add this one line.
- ```
- INPUT(-lunwind)
- ```
-
-**Folder path: 'Android/Sdk/ndk/24.0.8215888/toolchains/llvm/prebuilt/linux-x86_64/lib64/clang/14.0.1/lib/linux'.**
-After that you have to copy this file into three different folders namely aarch64, arm, i386 and x86_64.
-We have to do this so we Android NDK can find clang on our system, if we used NDK 22 we wouldn't have to do this process.
-Though using NDK v22 will not give us a lot of features to work with.
+In order to get clang to work properly with version 24 you need to create this file.
+Create a file named `libgcc.a` with this one line:
+```
+INPUT(-lunwind)
+```
+
+**Linux/macOS:**
+Folder path: `Android/Sdk/ndk/24.0.8215888/toolchains/llvm/prebuilt/linux-x86_64/lib64/clang/14.0.1/lib/linux/`
+
+**Windows:**
+Folder path: `Android\Sdk\ndk\24.0.8215888\toolchains\llvm\prebuilt\windows-x86_64\lib64\clang\14.0.1\lib\linux\`
+
+After creating the file, copy it into four different folders: `aarch64`, `arm`, `i386` and `x86_64`.
+We have to do this so the Android NDK can find clang on our system. If we used NDK 22 we wouldn't have to do this process, though using NDK v22 will not give us a lot of features to work with.
 This GitHub [issue](https://github.com/fzyzcjy/flutter_rust_bridge/issues/419) explains the reason why we are doing this.
 
  ---
 
- **Android NDK**
+**Android NDK Path Setup**
+
+After installing the NDK tools for Android you should add the NDK path to your system PATH.
 
- After installing the NDK tools for android you should export the PATH to your config file
- (.vimrc, .zshrc, .profile, .bashrc file), That way it can be found.
+**Linux/macOS:**
+Add to your shell config file (.bashrc, .zshrc, .profile):
+```bash
+export PATH=$PATH:~/Android/Sdk/ndk/24.0.8215888
+```
+
+**Windows:**
+Add to your system PATH environment variable or add to PowerShell profile:
+```powershell
+$env:PATH += ";C:\Users\$env:USERNAME\AppData\Local\Android\Sdk\ndk\24.0.8215888"
+```
+
+**Building AppFlowy Android**
+
+Once you have completed the setup above, you can build AppFlowy for Android using:
+
+**All platforms:**
+```bash
+cd frontend
+cargo make appflowy-android
+```
 
- ```vim
- export PATH=/home/sean/Android/Sdk/ndk/24.0.8215888
- ```
+This will use the appropriate build scripts for your platform (Windows, macOS, or Linux).
diff --git a/frontend/scripts/makefile/mobile.toml b/frontend/scripts/makefile/mobile.toml
@@ -76,6 +76,11 @@ run_task = { name = [
 ] }
 
 [tasks.sdk-build-android]
+mac_alias = "sdk-build-android-unix"
+linux_alias = "sdk-build-android-unix"
+windows_alias = "sdk-build-android-windows"
+
+[tasks.sdk-build-android-unix]
 dependencies = ["set-app-version"]
 private = true
 script = [
@@ -93,8 +98,31 @@ script = [
 ]
 script_runner = "@shell"
 
+[tasks.sdk-build-android-windows]
+dependencies = ["set-app-version"]
+private = true
+script = [
+  """
+    cd rust-lib
+    if eq ${BUILD_FLAG} debug
+      echo "🚀 🚀 🚀  Building Android SDK for debug"
+      exec cargo ndk -t arm64-v8a -t armeabi-v7a -o ./jniLibs build --features "${FLUTTER_DESKTOP_FEATURES}" --package=dart-ffi
+    else
+      echo "🚀 🚀 🚀  Building Android SDK for release"
+      exec cargo ndk -t arm64-v8a -t armeabi-v7a -o ./jniLibs build --features "${FLUTTER_DESKTOP_FEATURES}" --package=dart-ffi --release
+    end
+    cd ..
+  """,
+]
+script_runner = "@duckscript"
+
 # only use in CI job
 [tasks.sdk-build-android-ci]
+mac_alias = "sdk-build-android-ci-unix"
+linux_alias = "sdk-build-android-ci-unix"
+windows_alias = "sdk-build-android-ci-windows"
+
+[tasks.sdk-build-android-ci-unix]
 dependencies = ["set-app-version"]
 private = true
 script = [
@@ -106,6 +134,18 @@ script = [
 ]
 script_runner = "@shell"
 
+[tasks.sdk-build-android-ci-windows]
+dependencies = ["set-app-version"]
+private = true
+script = [
+  """
+    cd rust-lib
+    exec cargo ndk -t arm64-v8a -t armeabi-v7a -o ./jniLibs build --features "${FLUTTER_DESKTOP_FEATURES}" --package=dart-ffi
+    cd ..
+  """,
+]
+script_runner = "@duckscript"
+
 [tasks.post-mobile-ios]
 private = true
 script = [
