diff --git a/README.md b/README.md index 565908e756859..c85d798a76225 100644 --- 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 new file mode 100644 index 0000000000000..dcc17beb3d72e --- /dev/null +++ b/doc/BUILD_FROM_SOURCE.md @@ -0,0 +1,219 @@ +# 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` + +**Additional Setup:** + +1. **Set Environment Variables** + + **Windows:** + ```cmd + set ANDROID_NDK_HOME=C:\Users\%USERNAME%\AppData\Local\Android\Sdk\ndk\24.0.8215888 + ``` + + **macOS/Linux:** + ```bash + export ANDROID_NDK_HOME=~/Android/Sdk/ndk/24.0.8215888 + ``` + +2. **Configure Cargo for Android** + + Create or edit `~/.cargo/config` (Linux/macOS) or `%USERPROFILE%\.cargo\config` (Windows): + + **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" + linker = "/home/user/Android/Sdk/ndk/24.0.8215888/toolchains/llvm/prebuilt/linux-x86_64/bin/aarch64-linux-android29-clang" + + [target.armv7-linux-androideabi] + ar = "/home/user/Android/Sdk/ndk/24.0.8215888/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-ar" + linker = "/home/user/Android/Sdk/ndk/24.0.8215888/toolchains/llvm/prebuilt/linux-x86_64/bin/armv7a-linux-androideabi29-clang" + + [target.i686-linux-android] + ar = "/home/user/Android/Sdk/ndk/24.0.8215888/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-ar" + linker = "/home/user/Android/Sdk/ndk/24.0.8215888/toolchains/llvm/prebuilt/linux-x86_64/bin/i686-linux-android29-clang" + + [target.x86_64-linux-android] + ar = "/home/user/Android/Sdk/ndk/24.0.8215888/toolchains/llvm/prebuilt/linux-x86_64/bin/llvm-ar" + 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" + ``` + +3. **NDK 24 Clang Fix** + + Create a file named `libgcc.a` with this content: + ``` + INPUT(-lunwind) + ``` + + **Linux/macOS:** Place it in `Android/Sdk/ndk/24.0.8215888/toolchains/llvm/prebuilt/linux-x86_64/lib64/clang/14.0.1/lib/linux/` + + **Windows:** Place it in `Android\Sdk\ndk\24.0.8215888\toolchains\llvm\prebuilt\windows-x86_64\lib64\clang\14.0.1\lib\linux\` + + Copy this file to the following subdirectories: `aarch64`, `arm`, `i386`, and `x86_64`. + +#### 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 index 7da2cb55fdd75..128495f59d55a 100644 --- a/frontend/appflowy_flutter/.metadata +++ b/frontend/appflowy_flutter/.metadata @@ -1,11 +1,11 @@ # 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 @@ -13,11 +13,11 @@ project_type: app 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 index 116cd63f22b54..a172764a04833 100644 --- 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 index 52f0dd3e6fd03..c76a3b09958a0 100644 --- 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 - ``` \ No newline at end of file +This will use the appropriate build scripts for your platform (Windows, macOS, or Linux). \ No newline at end of file diff --git a/frontend/appflowy_flutter/android/app/src/main/kotlin/io/appflowy/appflowy/MainActivity.kt b/frontend/appflowy_flutter/android/app/src/main/kotlin/io/appflowy/appflowy/MainActivity.kt new file mode 100644 index 0000000000000..c380c8bf1f458 --- /dev/null +++ b/frontend/appflowy_flutter/android/app/src/main/kotlin/io/appflowy/appflowy/MainActivity.kt @@ -0,0 +1,5 @@ +package io.appflowy.appflowy + +import io.flutter.embedding.android.FlutterActivity + +class MainActivity: FlutterActivity() diff --git a/frontend/appflowy_flutter/android/app/src/main/res/drawable/launch_background.xml b/frontend/appflowy_flutter/android/app/src/main/res/drawable/launch_background.xml new file mode 100644 index 0000000000000..304732f884201 --- /dev/null +++ b/frontend/appflowy_flutter/android/app/src/main/res/drawable/launch_background.xml @@ -0,0 +1,12 @@ + + + + + + + + diff --git a/frontend/scripts/makefile/mobile.toml b/frontend/scripts/makefile/mobile.toml index 6f89c1235ebd6..f0ef6162c41c2 100644 --- 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 -o ./jniLibs build --features "${FLUTTER_DESKTOP_FEATURES}" --package=dart-ffi + else + echo "🚀 🚀 🚀 Building Android SDK for release" + exec cargo ndk -t arm64-v8a -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 = [