update docs
This commit is contained in:
+58
-128
@@ -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<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
|
||||
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).
|
||||
|
||||
@@ -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
|
||||
Reference in New Issue
Block a user