This guide will help you set up your development environment to contribute to Icarus.
Prerequisites
FVM (Flutter Version Management)
Icarus uses FVM to pin the Flutter version. FVM is required - the project is pinned to Flutter 3.38.4 via .fvmrc.
Install FVM:
dart pub global activate fvm
fvm:
fvm flutter run
fvm dart run build_runner build
Install the required build dependencies:sudo apt-get install -y clang cmake ninja-build pkg-config libgtk-3-dev liblzma-dev libstdc++-14-dev
path_provider plugin):sudo apt-get install -y xdg-user-dirs
xdg-user-dirs-update
If you skip the XDG setup, the app will crash with MissingPlatformDirectoryException.
Ensure you have:
- Visual Studio 2022 with Desktop development with C++ workload
- Windows 10 SDK
For MSIX builds, you’ll also need:dart pub global activate msix
Install Xcode from the Mac App Store.Install CocoaPods:sudo gem install cocoapods
Installation
Clone the repository
git clone https://github.com/yourusername/icarus.git
cd icarus
Install Flutter version via FVM
FVM will read the .fvmrc file and install the correct Flutter version:fvm install
fvm use 3.38.4
Generate code
Icarus uses code generation for Hive adapters, Riverpod providers, and JSON serialization:fvm flutter pub run build_runner build --delete-conflicting-outputs
Run this command whenever you modify Hive models, Riverpod providers, or JSON-serializable classes.
Running the App
Linux
Windows
fvm flutter run -d windows
macOS
Development Workflow
Linting
Run the analyzer to check for issues:
Expect ~70 pre-existing warnings/infos (unused imports, deprecated APIs). There should be no errors.
Code Generation
After making changes to models or providers, regenerate code:
fvm flutter pub run build_runner build --delete-conflicting-outputs
Hot Reload
Flutter supports hot reload during development. Press r in the terminal where you ran flutter run to hot reload changes.
Testing
No automated tests currently exist in this codebase. Running fvm flutter test will find nothing.
Troubleshooting
If the app crashes on Linux with this exception, install XDG user directories:
sudo apt-get install -y xdg-user-dirs
xdg-user-dirs-update
Build Runner Conflicts
If you encounter conflicts during code generation, use the --delete-conflicting-outputs flag:
fvm flutter pub run build_runner build --delete-conflicting-outputs
FVM Not Found
Ensure FVM is in your PATH:
export PATH="$PATH:$HOME/.pub-cache/bin"