diff --git a/README.md b/README.md index 398c3dd..5a324dc 100644 --- a/README.md +++ b/README.md @@ -3,44 +3,29 @@

-### About +# Armbian Imager -Armbian Imager is the official tool for downloading and flashing Armbian OS images to single-board computers. It checks the target disk before writing, validates the checksum, and verifies the image after the write, so a bad download or the wrong disk doesn't turn into a broken card. +Armbian Imager is the official cross-platform desktop tool for downloading and flashing Armbian OS images to SD cards and USB drives. It checks the target disk before writing, validates the checksum, and verifies the image after the write, so a bad download or the wrong disk doesn't turn into a broken card. -### Features +## Features -- Works with 300+ boards, with filtering and board metadata from armbian.com +- Works with 300+ boards, with filtering and board metadata sourced from armbian.com - Disk safety checks, checksum validation, and post-write verification -- Native builds for Linux, Windows, and macOS, on x64 and ARM64 -- Multi-language interface that follows your system language by default -- Built-in application updates +- Native builds for Linux, Windows, and macOS on x64 and ARM64 +- Multi-language interface (18 locales), auto-detected from your system +- Built-in application updates (via Tauri updater) +- Support for Qualcomm EDL / QDL flashing (e.g. Arduino UNO Q) +- First-boot autoconfig injection into the image's ext4 rootfs before flashing - Small binary with few runtime dependencies -### Testimonials - -> "What a fantastic tool for getting people started with a non Raspberry PI" -> *Interfacing Linux*, hardware and software guides for Linux creatives ([source](https://www.youtube.com/watch?v=RAxQebKsnuc)) - -> "A proper multi-platform desktop app that actually works, which is rarer than you'd think." -> *Bruno Verachten*, Senior Developer Relations Engineer ([source](https://www.linkedin.com/pulse/adding-risc-v-support-armbian-imager-tale-qemu-tauri-deja-verachten-86fxe)) - -> "The Upcoming Armbian Imager Tool is a Godsend for Non-Raspberry Pi SBC Owners" -> *Sourav Rudra*, It's FOSS ([source](https://itsfoss.com/news/armbian-imager-quietly-debuts/)) - -> "According to Armbian, this results in less RAM and storage usage and a faster experience." -> *Jordan Gloor*, HowtoGeek.com ([source](https://www.howtogeek.com/armbians-raspberry-pi-imager-alternative-is-here/)) - -> "It's super easy to write an operating system... I'm always happy when an Armbian version comes out because you've got more stability and much more compatibility." -> *leepspvideo*, Simple Linux install for 300+ Arm devices ([source](https://www.youtube.com/watch?v=vUvGD2GSALI)) - ## Download -Prebuilt binaries are available for every supported platform. +Prebuilt binaries for every supported platform are published on the [Releases page](https://github.com/armbian/imager/releases). |
macOS |
Windows |
Linux | |:---:|:---:|:---:| | Intel & Apple Silicon | x64 & ARM64 (code-signed) | x64 & ARM64 | -| .dmg / .app.zip | .exe / .msi | .deb / .AppImage | +| `.dmg` | `.exe` / `.msi` | `.deb` / `.AppImage` | ## How It Works @@ -49,36 +34,159 @@ Prebuilt binaries are available for every supported platform. 3. **Pick an image.** Desktop or server, a kernel branch, and a stable, nightly, or rolling release build. 4. **Flash.** The app downloads, decompresses, writes, and verifies for you. -## Customization - -- Theme: light, dark, or follow the system setting -- Developer mode: turn on detailed logging and open the log viewer -- Language: 18 languages, auto-detected from your system - ## Platform Support | Platform | Architecture | Notes | -|----------|-------------|-------| +|----------|--------------|-------| | macOS | Intel x64 | Full support | -| macOS | Apple Silicon | Native ARM64 build, Touch ID support | +| macOS | Apple Silicon | Native ARM64 build | | Windows | x64 | Requires Administrator privileges | | Windows | ARM64 | Native ARM64 build, requires Administrator privileges | -| Linux | x64 | Uses lsblk for detection and UDisks2/polkit for elevated device access | +| Linux | x64 | Uses `lsblk` and UDisks2/polkit for elevated device access | | Linux | ARM64 | Native ARM64 build | -### Supported Languages +## Supported Languages + +English, Italian, German, French, Spanish, Portuguese, Portuguese (Brazil), Dutch, Polish, Russian, Chinese, Japanese, Korean, Ukrainian, Turkish, Slovenian, Swedish, Croatian. + +Locale files live in [`src/locales/`](src/locales/) and are kept in sync with `en.json` (the source of truth) by the `Data: Sync translation files` GitHub Actions workflow. + +## Tech Stack + +Armbian Imager is a [Tauri 2](https://tauri.app) desktop application. + +- **Frontend:** TypeScript, React 19, Vite, i18next, `lucide-react` +- **Backend:** Rust (edition 2021, MSRV 1.85.0), Tokio, `reqwest` (rustls), `serde` +- **Bundled Rust crate:** [`crates/armbian-write-conf`](crates/armbian-write-conf/) — writes a first-boot config file into an ext4 rootfs of a RAW disk image in userspace, then validates it (uses `gptman`, `mbrman`, `ext4-view`) +- **Decompression:** `xz2`, `lzma-rust2`, `bzip2`, `flate2`, `zstd` +- **Platform integration:** + - Linux: `libc`, `udisks2`, `zbus` + - macOS: `security-framework`, `core-foundation` + - Windows: `windows-sys` (Win32 Storage / Ioctl / IO) +- **QDL / EDL:** [`qdl`](https://github.com/qualcomm/qdlrs), `nusb` +- **Tauri plugins:** `shell`, `dialog`, `updater`, `process`, `store`, `fs` + +## Repository Layout + +``` +. +├── src/ # React frontend (TypeScript) +│ ├── App.tsx, main.tsx, i18n.ts +│ ├── components/ # flash/, layout/, modals/, settings/, shared/ +│ ├── config/ # constants, badges, os-info, i18n, qdlBoards, ... +│ ├── contexts/ # ThemeContext, UpdateContext +│ ├── hooks/ # useTauri, useFlashOperation, useSettings, ... +│ ├── locales/ # 18 translation files +│ ├── styles/ # Design-token CSS +│ ├── types/, utils/, assets/ +├── src-tauri/ # Rust backend (Tauri 2) +│ ├── src/ +│ │ ├── main.rs +│ │ ├── commands/ # IPC handlers (operations, settings, qdl, ...) +│ │ ├── flash/ # linux/, macos/, windows.rs, verify.rs +│ │ ├── devices/ # per-OS block-device enumeration +│ │ ├── images/ # models + filters +│ │ ├── qdl/ # Qualcomm EDL loader, flash, provision +│ │ ├── decompress.rs, download.rs, cache.rs, autoconfig.rs +│ │ └── utils/, logging/, paste/, config/ +│ ├── icons/ # Desktop, Android, iOS icon sets +│ ├── capabilities/default.json +│ ├── tauri.conf.json, Cargo.toml, build.rs +├── crates/ +│ └── armbian-write-conf/ # ext4 rootfs config writer (Rust library + tests) +├── scripts/ +│ ├── locales/sync-locales.js # AI-assisted locale sync +│ └── setup/ # install.sh, install-linux.sh, install-macos.sh, install-windows.ps1 +├── .github/ +│ ├── workflows/ # build, release, PR check, sync-labels, sync-locales, delete-releases +│ ├── ISSUE_TEMPLATE/, labels.yml, dependabot.yml +├── public/, index.html, vite.config.ts, eslint.config.js +├── tsconfig.json, tsconfig.app.json, tsconfig.node.json +├── package.json, package-lock.json +├── README.md, DEVELOPMENT.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, LICENSE +``` + +## Development + +Full setup, prerequisites, and build instructions live in [DEVELOPMENT.md](DEVELOPMENT.md). Quick start: + +```bash +git clone https://github.com/armbian/imager.git && cd imager +bash scripts/setup/install.sh +npm install +npm run tauri:dev +``` + +Prerequisites (see `DEVELOPMENT.md` for details): + +- Node.js ≥ 20.19.0 (declared in `package.json` `engines`) +- Rust ≥ 1.85.0 (`rust-version` in `src-tauri/Cargo.toml`) + +### npm Scripts -English, Italian, German, French, Spanish, Portuguese, Portuguese (Brazil), Dutch, Polish, Russian, Chinese, Japanese, Korean, Ukrainian, Turkish, Slovenian, Swedish, Croatian +| Command | Description | +|---------|-------------| +| `npm run dev` | Vite dev server (frontend only) | +| `npm run tauri:dev` | Full app with hot reload | +| `npm run build` | Production frontend build (`tsc -b && vite build`) | +| `npm run build:dev` | Development-mode frontend build | +| `npm run tauri:build` | Production distributable | +| `npm run tauri:build:dev` | Debug build with symbols | +| `npm run lint` | ESLint | +| `npm run clean` | Remove `node_modules`, `dist`, `src-tauri/target` | + +## Quality Checks + +CI runs the following on every pull request; run them locally before opening a PR. + +Frontend: + +```bash +npm run lint # ESLint +npx tsc --noEmit # TypeScript type check +``` + +Backend: + +```bash +cd src-tauri +cargo fmt --check +cargo clippy --all-targets --all-features -- -D warnings +``` + +## CI / GitHub Actions + +| Workflow | Purpose | +|----------|---------| +| `Maintenance: Build` | Manual builds for Linux x64/ARM64, macOS (x64 + ARM64), Windows x64/ARM64 | +| `Maintenance: Release` | Tag-triggered release pipeline (draft release, per-platform builds, updater signing) | +| `Maintenance: PR check` | Frontend lint + type check, Rust fmt + clippy, per-platform test builds | +| `Maintenance: Delete old releases` | Daily cleanup keeping N full releases and N prereleases | +| `Data: Sync translation files` | Daily sync of `src/locales/*.json` against `en.json` with AI-assisted translation | +| `Infrastructure: Sync labels` | Applies `.github/labels.yml` to the repository | + +## Contributing + +Contributions are welcome — see [CONTRIBUTING.md](CONTRIBUTING.md) for the workflow, commit conventions, and translation guidelines. Please also read the [Code of Conduct](CODE_OF_CONDUCT.md). + +Other ways to help: + +- [Become a new board maintainer](https://docs.armbian.com/Board_Maintainers_Procedures_and_Guidelines/) +- [Apply for an open position](https://forum.armbian.com/staffapplications/) +- [Help cover running costs](https://forum.armbian.com/subscriptions/) +- [Help community members in the forum](https://forum.armbian.com/) ## Why We Sign Our Code Downloading software shouldn't take a leap of faith. Every Windows release is cryptographically signed, so you can confirm the binary is exactly what we built and hasn't been tampered with on the way to you. -This is possible thanks to [SignPath Foundation](https://signpath.org?utm_source=foundation&utm_medium=github&utm_campaign=armbian-imager), which gives free code signing certificates to open source projects, and [SignPath.io](https://signpath.io?utm_source=foundation&utm_medium=github&utm_campaign=armbian-imager) for the signing infrastructure. +This is possible thanks to [SignPath Foundation](https://signpath.org?utm_source=foundation&utm_medium=github&utm_campaign=armbian-imager), which provides free code-signing certificates to open source projects, and [SignPath.io](https://signpath.io?utm_source=foundation&utm_medium=github&utm_campaign=armbian-imager) for the signing infrastructure. -## Development +## License + +Distributed under the **GNU General Public License v2.0**. See [LICENSE](LICENSE) for the full text. -Setup, build instructions, and project layout live in [DEVELOPMENT.md](DEVELOPMENT.md). +The bundled `armbian-write-conf` crate is licensed under MIT (see [`crates/armbian-write-conf/Cargo.toml`](crates/armbian-write-conf/Cargo.toml)). ---