# Building ISO Droid

This document explains how to build ISO Droid from source and contribute to the project.

## Building from Source

### Prerequisites

**1. isodrive Binary (Required)**

ISO Droid requires the `isodrive` binary to function. This binary is the actual tool that communicates with the Linux kernel's USB gadget subsystem to mount ISO/IMG files.

- **Source**: The binary is compiled from [nitanmarcel/isodrive](https://github.com/nitanmarcel/isodrive)
- **Why required**: Android apps cannot directly access USB gadget interfaces - they need a native binary with root privileges
- **Location**: Place the binary at `app/src/main/assets/bin/isodrive`
- **Supported architectures**: ARM64 (arm64-v8a), ARM32 (armeabi-v7a), x86, x86_64

**How to obtain the binary:**

1. Download the latest release from [isodrive-magisk releases](https://github.com/nitanmarcel/isodrive-magisk/releases/latest)

2. Extract the `isodrive-magisk-v<version>.zip` file

3. The binaries for each architecture are in the `libs/` directory:
   ```
   libs/
   ├── arm64-v8a/
   │   └── isodrive
   ├── armeabi-v7a/
   │   └── isodrive
   ├── x86/
   │   └── isodrive
   └── x86_64/
       └── isodrive
   ```

4. Copy the binary for your target architecture to `app/src/main/assets/bin/isodrive`
   - For most modern devices: use `arm64-v8a/isodrive`
   - The app can bundle multiple architectures if needed

### 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 debug APK
./gradlew assembleDebug

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

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

## Contributing

### Adding OS Icons

OS icons are displayed in the file browser when ISO/IMG filenames match the icon name.

**Steps:**

1. Add your SVG file to `app/src/main/assets/osicons/`
   - Filename should be lowercase (e.g., `ubuntu.svg`, `archlinux.svg`)
   - SVG should be simple and recognizable
   - Recommended: Get icons from [Simple Icons](https://simpleicons.org/)

2. The app automatically detects and matches icons:
   - Filename `ubuntu-22.04-desktop-amd64.iso` → matches `ubuntu.svg`
   - Filename `archlinux-2024.12.01-x86_64.iso` → matches `archlinux.svg`
   - Matching is case-insensitive and searches for icon name within filename

3. **Symlinks for filename variations:**

   Sometimes ISO files use shortened or alternate names. Create symlinks to match these variations:
   ```bash
   cd app/src/main/assets/osicons/

   # Linux Mint ISOs often named "mint-*.iso"
   ln -s linuxmint.svg mint.svg

   # Windows ISOs might be "Win11.iso" or "Win.iso"
   ln -s windows.svg win.svg
   ln -s windows.svg win11.svg

   # FreeBSD might be shortened
   ln -s freebsd.svg bsd.svg
   ```

   This ensures `mint-21.3-cinnamon.iso` matches even though the icon is `linuxmint.svg`

4. Submit a pull request with your new icon(s) and any necessary symlinks

### Adding OS Download Links

The Downloads screen shows curated links to operating system ISOs.

**Steps:**

1. Edit `app/src/main/assets/os.json`

2. Add a new entry with all required fields:

```json
{
  "name": "Ubuntu Desktop",
  "category": "Linux",
  "description": "Popular Linux distribution with GNOME desktop",
  "icon": "ubuntu.svg",
  "url": "https://ubuntu.com/download/desktop"
}
```

**Field descriptions:**

- `name` (required): Display name for the OS
- `category` (required): One of: `Linux`, `BSD`, `Windows`, or `Recovery`
- `description` (required): Brief description (one sentence)
- `icon` (required): Filename of SVG in `osicons/` directory, or `null` if no icon
- `url` (required): Direct link to download page or ISO file

**Example with no icon:**
```json
{
  "name": "Custom Linux",
  "category": "Linux",
  "description": "A custom Linux distribution",
  "icon": null,
  "url": "https://example.com/download"
}
```

3. Test your changes:
   - Build the app
   - Navigate to Downloads screen
   - Verify your entry appears in the correct category
   - Verify the icon displays (if provided)
   - Verify the link opens correctly

4. Submit a pull request with:
   - Updated `os.json`
   - New SVG icon in `osicons/` (if applicable)
   - Brief description of what you added

## Testing

Before submitting a PR, test on a real rooted Android device:

- [ ] App builds successfully
- [ ] New OS icon displays correctly
- [ ] New download link opens properly
- [ ] No crashes or errors in logcat