Skip to content

Development Environment Setup

Overview

This guide provides comprehensive instructions for setting up a development environment for the CulicidaeLab Flutter mobile application. The project supports both containerized development using VS Code Dev Containers and manual local setup.

Prerequisites

System Requirements

  • Operating System: Windows 10/11, macOS 10.14+, or Ubuntu 18.04+
  • RAM: Minimum 8GB, recommended 16GB
  • Storage: At least 10GB free space for development tools and dependencies
  • Network: Stable internet connection for downloading dependencies

Required Tools

  • Git: Version control system
  • VS Code: Recommended IDE with Flutter extensions
  • Docker: For containerized development (optional but recommended)

The easiest way to get started is using the provided Dev Container configuration, which provides a consistent development environment across all platforms.

Prerequisites for Dev Container

  1. Install Docker Desktop
  2. Windows: Download from Docker Desktop for Windows
  3. macOS: Download from Docker Desktop for Mac

  4. Linux: Follow Docker Engine installation guide

  5. Install VS Code

  6. Download from Visual Studio Code

  7. Install Dev Containers Extension

  8. Open VS Code
  9. Go to Extensions (Ctrl+Shift+X)
  10. Search for "Dev Containers" by Microsoft
  11. Install the extension

Setting Up Dev Container

  1. Clone the Repository 

    git clone https://github.com/your-org/culicidaelab.git
cd culicidaelab

  2. Open in Dev Container

  3. Open VS Code
  4. Open the project folder
  5. VS Code should detect the .devcontainer configuration

  6. Click "Reopen in Container" when prompted, or:

    • Press Ctrl+Shift+P (Cmd+Shift+P on Mac)
    • Type "Dev Containers: Reopen in Container"
    • Select the command

  7. Wait for Container Build

  8. The first build may take 10-15 minutes
  9. Subsequent starts will be much faster

  10. The container includes:

    • Flutter SDK 3.29.3
    • Android SDK with Platform 35
    • Android Build Tools 34.0.0
    • Android NDK 27.0.12077973
    • Java 17
    • All necessary development tools

  11. Verify Installation 

    flutter doctor

  12. This should show all checkmarks for Android development
  13. iOS development will show as unavailable (expected on Linux container)

Dev Container Features

The dev container includes:

  • Pre-configured Flutter SDK: Latest stable version with Android support
  • Android Development Tools: Complete Android SDK, NDK, and build tools
  • VS Code Extensions: Flutter, Dart, and helpful development extensions
  • USB Device Support: Physical device debugging capabilities
  • Port Forwarding: Automatic port forwarding for development servers

Option 2: Manual Local Setup

If you prefer to set up the development environment manually or cannot use Docker, follow these platform-specific instructions.

Windows Setup

  1. Install Git
  2. Download from Git for Windows

  3. Use default installation options

  4. Install Flutter SDK 

    # Download Flutter SDK
Invoke-WebRequest -Uri "https://storage.googleapis.com/flutter_infra_release/releases/stable/windows/flutter_windows_3.29.3-stable.zip" -OutFile "flutter_sdk.zip"

# Extract to C:\flutter
Expand-Archive -Path "flutter_sdk.zip" -DestinationPath "C:\"

# Add to PATH
$env:PATH += ";C:\flutter\bin"
[Environment]::SetEnvironmentVariable("PATH", $env:PATH, [EnvironmentVariableTarget]::User)

  5. Install Android Studio

  6. Download from Android Studio
  7. Install with default options
  8. Open Android Studio and complete the setup wizard

  9. Install Android SDK Platform 35 and Build Tools 34.0.0

  10. Configure Android SDK 

    # Set environment variables
[Environment]::SetEnvironmentVariable("ANDROID_SDK_ROOT", "$env:LOCALAPPDATA\Android\Sdk", [EnvironmentVariableTarget]::User)
[Environment]::SetEnvironmentVariable("ANDROID_HOME", "$env:LOCALAPPDATA\Android\Sdk", [EnvironmentVariableTarget]::User)

  11. Install VS Code and Extensions

  12. Download VS Code from code.visualstudio.com
  13. Install Flutter and Dart extensions

macOS Setup

  1. Install Homebrew (if not already installed) 

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

  2. Install Git 

    brew install git

  3. Install Flutter SDK 

    # Download and extract Flutter
cd ~/development
curl -O https://storage.googleapis.com/flutter_infra_release/releases/stable/macos/flutter_macos_3.29.3-stable.zip
unzip flutter_macos_3.29.3-stable.zip

# Add to PATH
echo 'export PATH="$PATH:$HOME/development/flutter/bin"' >> ~/.zshrc
source ~/.zshrc

  4. Install Android Studio

  5. Download from Android Studio
  6. Install and complete setup wizard

  7. Install required SDK components

  8. Install Xcode (for iOS development) 

    # Install Xcode from App Store
# Install Xcode command line tools
sudo xcode-select --install

  9. Configure Environment 

    # Add Android SDK to PATH
echo 'export ANDROID_SDK_ROOT=$HOME/Library/Android/sdk' >> ~/.zshrc
echo 'export PATH=$PATH:$ANDROID_SDK_ROOT/platform-tools' >> ~/.zshrc
source ~/.zshrc

Linux (Ubuntu) Setup

  1. Update System 

    sudo apt update && sudo apt upgrade -y

  2. Install Dependencies 

    sudo apt install -y curl git unzip xz-utils zip libglu1-mesa openjdk-17-jdk

  3. Install Flutter SDK 

    # Download Flutter
cd ~/development
wget https://storage.googleapis.com/flutter_infra_release/releases/stable/linux/flutter_linux_3.29.3-stable.tar.xz
tar xf flutter_linux_3.29.3-stable.tar.xz

# Add to PATH
echo 'export PATH="$PATH:$HOME/development/flutter/bin"' >> ~/.bashrc
source ~/.bashrc

  4. Install Android Studio 

    # Download Android Studio
wget https://redirector.gvt1.com/edgedl/android/studio/ide-zips/2023.1.1.28/android-studio-2023.1.1.28-linux.tar.gz
tar -xzf android-studio-*-linux.tar.gz -C ~/development/

# Run Android Studio
~/development/android-studio/bin/studio.sh

  5. Configure Environment 

    # Set environment variables
echo 'export ANDROID_SDK_ROOT=$HOME/Android/Sdk' >> ~/.bashrc
echo 'export PATH=$PATH:$ANDROID_SDK_ROOT/platform-tools' >> ~/.bashrc
source ~/.bashrc

Project Setup

Clone and Initialize

  1. Clone Repository 

    git clone https://github.com/your-org/culicidaelab.git
cd culicidaelab

  2. Install Dependencies 

    flutter pub get

  3. Verify Setup 

    flutter doctor

  4. Resolve any issues shown by flutter doctor
  5. Ensure Android toolchain shows green checkmark

IDE Configuration

VS Code Setup

  1. Install Extensions
  2. Flutter (Dart-Code.flutter)
  3. Dart (Dart-Code.dart-code)
  4. EditorConfig (EditorConfig.EditorConfig)

  5. VSCode Icons (vscode-icons-team.vscode-icons)

  6. Configure Settings Create .vscode/settings.json: 

    {
  "dart.flutterSdkPath": "/path/to/flutter",
  "dart.lineLength": 120,
  "editor.formatOnSave": true,
  "editor.tabSize": 2,
  "editor.insertSpaces": true,
  "editor.detectIndentation": false,
  "dart.previewFlutterUiGuides": true,
  "dart.previewFlutterUiGuidesCustomTracking": true,
  "dart.debugExternalLibraries": false,
  "dart.debugSdkLibraries": false,
  "files.autoSave": "afterDelay"
}

Android Studio Setup

  1. Install Flutter Plugin
  2. Go to File → Settings → Plugins
  3. Search for "Flutter" and install

  4. Restart Android Studio

  5. Configure SDK Paths

  6. Go to File → Project Structure
  7. Verify Android SDK path
  8. Set Flutter SDK path

Device Setup

Android Device Setup

Physical Device

  1. Enable Developer Options
  2. Go to Settings → About Phone
  3. Tap "Build Number" 7 times

  4. Go back to Settings → Developer Options

  5. Enable USB Debugging

  6. In Developer Options, enable "USB Debugging"
  7. Connect device via USB

  8. Accept debugging authorization on device

  9. Verify Connection 

    flutter devices

Android Emulator

  1. Create AVD
  2. Open Android Studio
  3. Go to Tools → AVD Manager
  4. Create Virtual Device
  5. Choose Pixel 4 or similar
  6. Select API Level 35 (Android 14)

  7. Finish setup

  8. Start Emulator 

    flutter emulators --launch <emulator_id>

iOS Device Setup (macOS only)

Physical Device

  1. Install iOS Development Certificate
  2. Open Xcode
  3. Go to Preferences → Accounts
  4. Add Apple ID

  5. Download development certificates

  6. Configure Device

  7. Connect iOS device
  8. Trust computer on device
  9. Enable Developer Mode in Settings

iOS Simulator

  1. Install Simulator 

    sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
open -a Simulator

  2. Verify Setup 

    flutter devices

Running the Application

Development Mode

  1. Start Application 

    # Run on connected device/emulator
flutter run

# Run on specific device
flutter run -d <device_id>

# Run with hot reload
flutter run --hot

  2. Debug Mode Features

  3. Hot reload: Press r in terminal or save files
  4. Hot restart: Press R in terminal
  5. Debug inspector: Press w in terminal

Build Modes

  1. Debug Build 

    flutter build apk --debug

  2. Release Build 

    flutter build apk --release

  3. Profile Build 

    flutter build apk --profile

Troubleshooting

Common Issues

Flutter Doctor Issues

  1. Android License Issues 

    flutter doctor --android-licenses
    Accept all licenses when prompted.

  2. Android SDK Not Found

  3. Verify ANDROID_SDK_ROOT environment variable

  4. Ensure Android SDK is installed in correct location

  5. Flutter SDK Issues 

    flutter channel stable
flutter upgrade
flutter doctor

Build Issues

  1. Gradle Build Failures 

    cd android
./gradlew clean
cd ..
flutter clean
flutter pub get

  2. Dependency Conflicts 

    flutter pub deps
flutter pub upgrade

Device Connection Issues

  1. ADB Issues 

    adb kill-server
adb start-server
flutter devices

  2. USB Debugging Not Working

  3. Try different USB cable
  4. Enable "File Transfer" mode on device
  5. Revoke USB debugging authorizations and reconnect

Performance Issues

  1. Slow Build Times
  2. Increase Gradle memory: Add org.gradle.jvmargs=-Xmx4g to android/gradle.properties
  3. Use --no-sound-null-safety flag if needed

  4. Clear build cache: flutter clean

  5. Hot Reload Not Working

  6. Ensure you're in debug mode
  7. Check for syntax errors
  8. Restart debug session

Development Workflow

  1. Start Development Session 

    # Open project in VS Code
code .

# Start device/emulator
flutter devices
flutter run

  2. Development Cycle

  3. Make code changes
  4. Save files (auto hot reload)
  5. Test changes on device

  6. Commit changes with meaningful messages

  7. Testing 

    # Run unit tests
flutter test

# Run integration tests
flutter test integration_test/

# Run specific test file
flutter test test/unit/services/classification_service_test.dart

  8. Code Quality 

    # Format code
flutter format .

# Analyze code
flutter analyze

# Check for outdated dependencies
flutter pub outdated

Next Steps

After completing the development environment setup:

  1. Read the Architecture Documentation: Understand the app's structure and patterns
  2. Review the Project Structure Guide: Learn about directory organization and conventions
  3. Check the Contributing Guidelines: Understand the development workflow and standards
  4. Run the Test Suite: Ensure everything is working correctly
  5. Start with Small Changes: Make a minor change to familiarize yourself with the codebase

Getting Help

If you encounter issues during setup:

  1. Check Flutter Doctor: Run flutter doctor -v for detailed diagnostics
  2. Review Logs: Check console output for specific error messages
  3. Search Documentation: Flutter and Android documentation often have solutions
  4. Ask for Help: Create an issue in the project repository with:
  5. Your operating system and version
  6. Flutter doctor output
  7. Complete error messages
  8. Steps you've already tried

Additional Resources