Setup

Setting up your development environment for Icarus

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

Always prefix Flutter and Dart commands with fvm:

fvm flutter run
fvm dart run build_runner build

Platform-Specific Dependencies

Linux

Install the required build dependencies:

sudo apt-get install -y clang cmake ninja-build pkg-config libgtk-3-dev liblzma-dev libstdc++-14-dev

Install XDG user directories (required by 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.

Windows

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

macOS

Install Xcode from the Mac App Store.

Install CocoaPods:

sudo gem install cocoapods

Installation

1. Clone the repository

   git clone https://github.com/yourusername/icarus.git
   cd icarus
   
2. Install Flutter version via FVM

   FVM will read the .fvmrc file and install the correct Flutter version:

   fvm install
   fvm use 3.38.4
   
3. Install dependencies

   fvm flutter pub get
   
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

fvm flutter run -d linux

Windows

fvm flutter run -d windows

macOS

fvm flutter run -d macos

Development Workflow

Linting

Run the analyzer to check for issues:

fvm flutter analyze

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

MissingPlatformDirectoryException (Linux)

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"