# 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`:

```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:

```bash
# Accept Android licenses
android-setup

# Or manually
yes | sdkmanager --licenses

# Create and start emulator
android-emulator

# Verify Flutter setup
flutter doctor
```

## Usage

### Launch Emulator

```bash
# 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

```bash
android-studio
```

### Flutter Development

```bash
# 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

```bash
# 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:

```bash
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:

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

Then source environment:

```bash
exec $SHELL
```

### Emulator won't start

Check that the system image is available:

```bash
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

```bash
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

```bash
# 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:

```bash
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`:

```bash
# 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](https://search.nixos.org/packages?channel=unstable&query=androidenv)
- [Android Studio on NixOS](https://github.com/NixOS/nixpkgs/blob/master/pkgs/applications/editors/android-studio)
- [Android Developer Docs](https://developer.android.com/)
- [Flutter Documentation](https://flutter.dev/docs)

## 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