diff --git a/docs/BUILDING.md b/docs/BUILDING.md index feca454..c5efdb2 100644 --- a/docs/BUILDING.md +++ b/docs/BUILDING.md @@ -1,53 +1,50 @@ # Building ISO Droid -This document explains how to build ISO Droid from source and contribute to the project. +This document explains how to build ISO Droid from source. + +## Requirements + +- **Android Studio** (or command-line Gradle) +- **Android SDK** (API 26+) +- **Android NDK** (for compiling isodrive binary) +- **Git** (with submodule support) ## Building from Source -### Prerequisites +### 1. Clone with Submodules -**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.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 +ISO Droid uses [isodrive](https://git.shihaam.dev/shihaam/isodrive) as a git submodule. Clone with submodules: ```bash -# Clone the repository -git clone https://github.com/sargit/ISODroid.git +git clone --recurse-submodules https://git.shihaam.dev/shihaam/ISODroid.git cd ISODroid +``` -# Ensure isodrive binary is present -ls -la app/src/main/assets/bin/isodrive +Or if already cloned, initialize submodules: +```bash +git submodule update --init +``` + +### 2. Install Android NDK + +The isodrive binary is compiled from source during the build. This requires the Android NDK. + +**Android Studio:** +1. Go to **Tools → SDK Manager** +2. Click **SDK Tools** tab +3. Check **NDK (Side by side)** +4. Click **Apply** + +**NixOS:** +The build automatically uses `nix-shell` to get the NDK if available. + +**Manual:** +Set `ANDROID_NDK_HOME` environment variable to your NDK path. + +### 3. Build + +```bash # Build debug APK ./gradlew assembleDebug @@ -55,105 +52,38 @@ ls -la app/src/main/assets/bin/isodrive ./gradlew assembleRelease ``` -The compiled APK will be in: -- Debug: `app/debug/app-debug.apk` -- Release: `app/release/app-release.apk` +The Gradle build will automatically: +- Compile isodrive for all architectures (arm64-v8a, armeabi-v7a, x86_64, x86) +- Bundle the binaries into the APK assets +- Skip compilation if binaries already exist -## Contributing +**Output locations:** +- Debug: `app/build/outputs/apk/debug/app-debug.apk` +- Release: `app/build/outputs/apk/release/app-release.apk` -### Adding OS Icons +### Build from Android Studio -OS icons are displayed in the file browser when ISO/IMG filenames match the icon name. +1. Open the project in Android Studio +2. Ensure NDK is installed (see above) +3. Click **Build → Build Bundle(s) / APK(s) → Build APK(s)** -**Steps:** +The isodrive binary will be compiled automatically before the APK is built. -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/) +### Manual isodrive Build (Optional) -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 +To manually trigger isodrive compilation: -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" -} +```bash +./gradlew buildIsodrive ``` -**Field descriptions:** +To force rebuild, delete existing binaries first: -- `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" -} +```bash +rm -rf app/src/main/assets/bin/*/isodrive +./gradlew buildIsodrive ``` -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 +## F-Droid Build -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 +F-Droid uses `srclibs` instead of git submodules. The F-Droid metadata pre-builds isodrive before running Gradle, so the Gradle task skips compilation (binaries already exist). diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md new file mode 100644 index 0000000..0e02343 --- /dev/null +++ b/docs/CONTRIBUTING.md @@ -0,0 +1,99 @@ +# Contributing to ISO Droid + +This document explains how to contribute OS icons and download links to ISO Droid. + +For building the app, see [BUILDING.md](BUILDING.md). + +## 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 + ``` + + 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 (see [BUILDING.md](BUILDING.md)) + - 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