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

Option 2: Compile from source:

# 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

# 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

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:

   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:

{
  "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:

{
  "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:

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 file for details