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 filename variations:

   Sometimes ISO files use shortened or alternate names. Create symlinks to match these variations:

   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:

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

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