ISODroid/docs/BUILDING.md

# 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 compiled binary at `app/src/main/assets/bin/isodrive`
- **Architecture**: Must be compiled for ARM64 (aarch64) for modern Android devices

**How to obtain the binary:**

Option 1: Download precompiled binary from [isodrive releases](https://github.com/nitanmarcel/isodrive/releases)

Option 2: Compile from source:
```bash
# Clone isodrive repository
git clone https://github.com/nitanmarcel/isodrive.git
cd isodrive

# Build for Android (requires Android NDK)
# Follow the build instructions in the isodrive repository
```

### 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 aliases:**

   Some distributions have multiple names. You can create symlinks:
   ```bash
   cd app/src/main/assets/osicons/

   # Example: Manjaro uses Arch Linux icon
   ln -s archlinux.svg manjaro.svg

   # Example: Kubuntu uses Ubuntu icon
   ln -s ubuntu.svg kubuntu.svg
   ```

4. Submit a pull request with your new icon(s)

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

### OS Icon Symlinks

Some distributions share the same logo. Use symlinks instead of duplicating files:

**Common symlinks:**

```bash
cd app/src/main/assets/osicons/

# Arch-based distributions
ln -s archlinux.svg manjaro.svg
ln -s archlinux.svg endeavouros.svg

# Ubuntu derivatives
ln -s ubuntu.svg kubuntu.svg
ln -s ubuntu.svg xubuntu.svg
ln -s ubuntu.svg lubuntu.svg

# Debian-based
ln -s debian.svg kali.svg
ln -s debian.svg raspbian.svg
```

**Why symlinks:**
- Reduces APK size
- Ensures consistency when upstream icon changes
- Makes maintenance easier

**Note:** Git tracks symlinks, so they work across all platforms when cloned.

## Project Structure

```
ISODroid/
├── app/src/main/
│   ├── assets/
│   │   ├── bin/
│   │   │   └── isodrive          # Required binary
│   │   ├── osicons/               # OS logo SVGs
│   │   │   ├── ubuntu.svg
│   │   │   ├── archlinux.svg
│   │   │   └── ...
│   │   └── os.json                # Download links
│   ├── java/sh/sar/isodroid/      # Kotlin source code
│   └── res/                        # Android resources
├── docs/
│   ├── BUILDING.md                 # This file
│   └── screenshots/                # App screenshots
└── README.md                       # Main documentation
```

## Code Style

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

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

## Questions?

Open an issue on the repository if you need help or have questions about contributing.

## License

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