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

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

# 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/debug/app-debug.apk
• Release: app/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

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