# Building ISO Droid

This document contains technical information for building and understanding ISO Droid.

## Building from Source

### Prerequisites

Before building the app, you need to obtain the `isodrive` binary:

1. The `isodrive` binary is compiled from [nitanmarcel/isodrive](https://github.com/nitanmarcel/isodrive)
2. Place the compiled binary at `app/src/main/assets/bin/isodrive` before building
3. The binary must be executable and compiled for the appropriate Android architecture (ARM64 recommended for modern devices)

### Build Steps

```bash
# Clone the repository
git clone https://github.com/sargit/ISODroid.git
cd ISODroid

# Ensure isodrive binary is present
ls -la app/src/main/assets/bin/isodrive

# Build the debug APK
./gradlew assembleDebug

# Or build the release APK (requires signing configuration)
./gradlew assembleRelease
```

The compiled APK will be located at:
- Debug: `app/build/outputs/apk/debug/app-debug.apk`
- Release: `app/build/outputs/apk/release/app-release.apk`

## Technical Architecture

### Overview

ISO Droid is built using modern Android development practices:
- **Language**: Kotlin
- **UI Framework**: Jetpack Compose (Material 3)
- **Architecture**: MVVM (Model-View-ViewModel)
- **Minimum SDK**: 26 (Android 8.0)
- **Target SDK**: 34 (Android 14)

### Core Components

#### 1. IsoDriveManager (`isodrive/IsoDriveManager.kt`)

The central component that interfaces with the `isodrive` binary:

- **Binary Extraction**: Copies the bundled `isodrive` binary from assets to app-specific storage
- **Permission Management**: Ensures the binary has executable permissions (`chmod 755`)
- **Command Execution**: Wraps all isodrive commands (mount, unmount, status checks)
- **Device Support Detection**: Checks for configfs or sysfs USB gadget support

```kotlin
// Example: Mounting an ISO
isoDriveManager.mount(
    filePath = "/sdcard/isodrive/ubuntu.iso",
    mountType = MountType.CDROM,
    readOnly = true
)
```

#### 2. RootManager (`root/RootManager.kt`)

Handles all root access operations:

- **Root Detection**: Checks for available root methods (Magisk, KernelSU, APatch, su binary)
- **Cached Status**: Stores root grant status to avoid repeated prompts
- **Command Execution**: Executes shell commands with root privileges
- **Error Handling**: Captures stdout, stderr, and exit codes

```kotlin
val result = RootManager.executeCommand("isodrive status")
if (result.isSuccess) {
    // Parse output
}
```

#### 3. USB Gadget Subsystem

ISO Droid supports both modern and legacy USB gadget interfaces:

**ConfigFS (Modern - Preferred)**
- Path: `/config/usb_gadget/`
- More flexible and feature-rich
- Standard on Android 8.0+ devices

**SysFS (Legacy)**
- Path: `/sys/class/android_usb/`
- Older interface
- Fallback for older devices

The `isodrive` binary automatically detects and uses the appropriate interface.

#### 4. Mount Types

**Mass Storage Mode**
- Exposes the file as a USB mass storage device
- Supports read-write mode for IMG files
- Host PC sees it as a USB flash drive
- Can be formatted with any filesystem (FAT32, NTFS, exFAT, ext4)

**CD-ROM Mode**
- Exposes the file as a virtual CD/DVD drive
- Always read-only
- Ideal for bootable ISOs
- Host PC sees it as an optical drive

### UI Architecture

#### Jetpack Compose

All UI is built using Jetpack Compose with Material 3:

- **Declarative**: UI is a function of state
- **Reactive**: Automatically updates when state changes
- **Type-safe**: Compile-time checking for UI code

#### Key Screens

1. **MainScreen** (`ui/screens/MainScreen.kt`)
   - File browser with OS icon detection
   - Mount/unmount operations
   - Status card showing current mount state

2. **DownloadsScreen** (`ui/screens/DownloadsScreen.kt`)
   - Curated list of OS download links
   - Grouped by category (Linux, BSD, Windows, Recovery)

3. **SettingsScreen** (`ui/screens/SettingsScreen.kt`)
   - Root permission status
   - Notification permission (Android 13+)
   - Default ISO directory configuration
   - App version and build information

#### State Management

Uses Kotlin StateFlow for reactive state:

```kotlin
data class MainUiState(
    val isLoading: Boolean = true,
    val hasRoot: Boolean? = null,
    val isSupported: Boolean? = null,
    val mountStatus: MountStatus = MountStatus.UNMOUNTED,
    val isoFiles: List<IsoFile> = emptyList(),
    // ...
)
```

### OS Icon Detection

Dynamic icon matching system:

1. **Icon Storage**: SVG files in `app/src/main/assets/osicons/`
2. **Dynamic Loading**: Icons are loaded at runtime via `AssetManager`
3. **Fuzzy Matching**: Filename matching algorithm:
   - Converts filename to lowercase
   - Checks for icon name presence (e.g., "ubuntu" in "ubuntu-22.04-desktop.iso")
   - Prioritizes longer matches (e.g., "linuxmint" over "linux")
   - Prefers earlier position in filename

4. **Rendering**: Uses Coil image library with SVG decoder
5. **Badge System**: Small circular badge shows file type (ISO/IMG)

### File Operations

#### Creating IMG Files

```kotlin
// User specifies size (e.g., 4 GB)
val sizeBytes = 4L * 1024 * 1024 * 1024

// Creates sparse file using dd with progress reporting
dd if=/dev/zero of=/sdcard/isodrive/custom.img bs=1M count=4096

// Progress events are emitted via CreateImgEventBus
```

#### Rename/Delete Protection

- Files currently mounted cannot be renamed or deleted
- UI shows warning message and disables actions
- Prevents accidental data corruption

### Notifications

Persistent notification while mounted:

- **Information**: Shows mounted filename and mount type
- **Quick Actions**: Unmount button in notification
- **Foreground Service**: Ensures notification stays visible
- **Auto-dismiss**: Notification removed after unmount

### Data Persistence

Uses Android DataStore (Preferences):

```kotlin
// Saves user preferences
dataStore.edit { preferences ->
    preferences[KEY_ISO_DIRECTORY] = "/sdcard/custom/path"
}
```

Stores:
- ISO directory path
- Root grant status (from setup wizard)
- App settings

### Event Bus System

Decoupled communication using Kotlin Flow:

```kotlin
// Mount events
object MountEventBus {
    private val _events = MutableSharedFlow<MountEvent>()
    val events: SharedFlow<MountEvent> = _events.asSharedFlow()
}

// Emit event from notification
MountEventBus.emit(MountEvent.Unmounted)

// Observe in ViewModel
MountEventBus.events.collect { event ->
    when (event) {
        is MountEvent.Unmounted -> updateUiState()
    }
}
```

## Dependencies

### Core Libraries

- **Jetpack Compose**: Modern declarative UI
- **Material 3**: Design system and components
- **Lifecycle & ViewModel**: Android Architecture Components
- **DataStore**: Modern preference storage
- **Coroutines**: Asynchronous programming

### Image Loading

- **Coil**: Image loading library
- **Coil SVG**: SVG decoder for OS icons

### JSON Parsing

- **org.json**: Parsing OS download list (`assets/os.json`)

## Testing

### Manual Testing Checklist

- [ ] Root access granted on first launch
- [ ] USB gadget support detected correctly
- [ ] ISO files mount successfully
- [ ] IMG files can be created and mounted
- [ ] OS icons display correctly
- [ ] Unmount via notification works
- [ ] File rename/delete protection when mounted
- [ ] Settings persist across app restarts
- [ ] Dark mode toggles correctly

### Device Compatibility

Tested on:
- Modern devices with ConfigFS (Android 8.0+)
- Legacy devices with SysFS (older Android versions)
- Various root methods (Magisk, KernelSU, APatch)

## Debugging

### Enable Verbose Logging

Check logcat for ISO Droid logs:

```bash
adb logcat | grep -i "isodroid\|isodrive"
```

### Common Issues

**"Device not supported"**
- Check for USB gadget support: `ls /config/usb_gadget/` or `ls /sys/class/android_usb/`
- Verify kernel has USB gadget drivers

**"Root access required"**
- Ensure root manager (Magisk/KernelSU) is installed
- Grant root access when prompted
- Check `RootManager.hasRoot()` returns true

**Mount fails**
- Verify file exists and is readable
- Check file isn't corrupted
- Ensure no other USB modes are active
- Try rebooting device

### isodrive Binary Version

Check the bundled binary version:

```bash
adb shell
su
/data/data/sh.sar.isodroid/files/isodrive --version
```

## Contributing

### Code Style

- Follow Kotlin coding conventions
- Use meaningful variable names
- Comment complex logic
- Keep functions focused and small

### Pull Requests

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly on a real device
5. Submit a pull request with description

## License

GNU General Public License v3.0 - See [LICENSE](../LICENSE) file for details