parana/modules/android/README.md

Android Development Module for NixOS

This module provides Android development environment setup using NixOS-specific approaches that respect the immutable filesystem while maintaining full functionality.

Features

• Android Studio Full - Includes FHS environment for compatibility
• androidenv - Declarative Android SDK management (reproducible)
• Android Emulator - Optimized for NixOS with GPU acceleration
• Flutter SDK - Optional Dart and Flutter support
• Build Tools - Gradle, Maven, Kotlin, Java
• Additional Tools - scrcpy for device screen sharing, APK signing utilities

Configuration

Add to your home.nix:

modules.android = {
  enable = true;
  enableEmulator = true;
  apiLevel = 34;
  enableFlutterSupport = true;
};

Configuration Options

• enable - Master switch for the module
• enableEmulator - Include Android emulator (default: true)
• apiLevel - Default Android API level (default: 34)
• enableFlutterSupport - Install Flutter SDK (default: true)

Why This Approach is Better for NixOS

Problem with Standard Android Tools on NixOS

NixOS uses an immutable filesystem and unique file structure that standard Android tools struggle with:

• Expected /system, /data, /cache paths don't exist
• SDK expects mutable /opt directories
• Dynamic library linking issues

Solution: NixOS-Specific Tools

android-studio-full - The recommended approach for NixOS

• Provides FHS (Filesystem Hierarchy Standard) environment
• Works out-of-the-box with proper file hierarchy
• Pre-configured with SDK, emulator, and build tools
• Manages mutable state in ~/.android directory
• No immutability conflicts

Initial Setup

After applying the module:

# Accept Android licenses
android-setup

# Or manually
yes | sdkmanager --licenses

# Create and start emulator
android-emulator

# Verify Flutter setup
flutter doctor

Usage

Launch Emulator

# Default emulator (flutter-dev, API 34)
android-emulator

# Custom name
android-emulator my-device

# Custom name and API level
android-emulator my-device 33

Launch Android Studio

android-studio

Flutter Development

# Create new project
flutter create my_app

# Run on emulator
cd my_app
flutter run

# Run with verbose output
flutter run -v

Physical Device Development

# Check connected devices
adb devices

# Screen sharing (requires scrcpy)
scrcpy

# View logs
adb logcat

Available API Levels

The module includes these Android API levels by default:

• API 28 (Android 9)
• API 31 (Android 12)
• API 33 (Android 13)
• API 34 (Android 14)
• API 35 (Android 15)

To use a specific API level:

android-emulator test-device 31
android-emulator latest 35

Build Tools

Included by default:

• Gradle (build system)
• Maven (alternative build system)
• Kotlin compiler
• Java JDK (11 and 21)
• CMake, Ninja, GNU Make

Hyprland Keybind

The module includes a Hyprland keybind:

SUPER + ALT + A  →  Launch Android emulator

Edit modules/hyprland/config.nix to customize.

Troubleshooting

"avdmanager: command not found"

Ensure the module is properly enabled and rebuilt:

home-manager switch --flake .#cody@nixos

Then source environment:

exec $SHELL

Emulator won't start

Check that the system image is available:

avdmanager list all

If the API level isn't listed, it may not be in the androidenv configuration. Edit the module to add it.

Flutter doctor shows issues

flutter doctor --verbose

# Accept licenses
yes | flutter doctor --android-licenses

# Clean cache
flutter clean
rm -rf pubspec.lock
flutter pub get

Physical device not detected

# Check ADB sees the device
adb devices

# Reload udev rules if you added a new device
sudo udevadm control --reload-rules
sudo udevadm trigger

# Ensure user is in correct group
groups  # Check for adbusers

Environment Variables

Automatically configured:

ANDROID_HOME        # Points to androidenv SDK
ANDROID_SDK_ROOT    # Points to androidenv SDK
ANDROID_USER_HOME   # $HOME/.android
JAVA_HOME          # JDK path
ANDROID_JAVA_HOME  # JDK for Android tools

Nix-Specific Notes

android-studio-full provides:

• Complete Android SDK with tools
• Emulator with hardware acceleration
• System images for multiple API levels
• Proper FHS environment for compatibility with standard Android tools

The module automatically configures:

• ANDROID_HOME environment variable
• ANDROID_SDK_ROOT for SDK location
• JAVA_HOME for Java toolchain
• All necessary PATH entries

Adding More API Levels

Android Studio's SDK Manager handles API level management. After installation:

1. Open Android Studio
2. Go to SDK Manager (Tools → SDK Manager)
3. Select additional API levels and download system images
4. Use android-emulator my-device 31 for the new level

Advanced: Manual SDK Management

If you prefer not to use Android Studio, you can manage the SDK manually using android-tools:

# List available SDK components
sdkmanager --list

# Install specific SDK component
sdkmanager "system-images;android-34;google_apis;x86_64"

# Create AVD
avdmanager create avd --name test --package "system-images;android-34;google_apis;x86_64"

Additional Resources

• NixOS Android Environment
• Android Studio on NixOS
• Android Developer Docs
• Flutter Documentation

Module Implementation Details

The module uses:

• android-studio-full for complete Android SDK with FHS environment
• android-tools for command-line utilities
• Standard Nix packages for build tools (Gradle, Maven, CMake)
• Environment variable configuration for automatic tool discovery
• Helper scripts for emulator management