KioArch¶
KioArch is a Kotlin Multiplatform (KMP) library for on-demand archive inspection and extraction without intermediate disk writes. Built on top of native C engines from 7-Zip Core, miniz, and libbzip2, it streams decompressed chunks directly from any random-access SeekableSource into a kotlinx.io.Sink while keeping heap memory consumption constant regardless of archive size.
Native shared libraries (.dll, .so, .dylib), iOS static binaries (.a embedded in .klib), and WebAssembly binaries are built, packaged, and loaded automatically.
Key Capabilities¶
- On-Demand Streaming Extraction: Extract individual entries directly into memory buffers, network sockets, or output streams without unpacking the entire archive to temporary files.
- Constant Heap Footprint: Decompressed bytes are emitted in fixed-size chunks through native-to-Kotlin callbacks, preventing out-of-memory failures on multi-gigabyte archives.
- Magic-Byte Format Detection: Archive formats are identified by inspecting leading header signatures rather than relying on file extensions.
- Zero-Copy JNI Support: On JVM and Android,
DirectSeekableSourcetransfers bytes between OS file channels and native C decoders through a directByteBufferwithout intermediateByteArraycopies. - Automatic Shift_JIS Filename Fallback: Legacy ZIP archives created on Windows frequently store Japanese filenames in Shift_JIS (CP932) without setting the UTF-8 bit flag. KioArch validates byte sequences and automatically falls back from UTF-8 to Shift_JIS across all targets.
Supported Platforms¶
| Platform | Targets / Architectures | Packaging & Runtime |
|---|---|---|
| JVM (Desktop / Server) | Windows (x64), macOS (Universal), Linux (x64) |
Extracts and loads embedded native libraries at runtime |
| Android | armeabi-v7a, arm64-v8a, x86, x86_64 |
16 KB page size ready (Android 15+), integrated with Jetpack App Startup |
| iOS | iOS Device (arm64), iOS Simulator (x64, arm64) |
Distributed as .klib / XCFramework with embedded static C libraries |
| JS / WasmJs | Node.js, Browser (Web Worker) | Powered by Emscripten WebAssembly |
Supported Archive Formats¶
KioArch is strictly read-only and supports the following formats and compression codecs out of the box:
| Format | Magic Signature | Supported Codecs & Filters | Typical Extensions |
|---|---|---|---|
7-Zip (SEVEN_Z) |
37 7A BC AF 27 1C |
LZMA, LZMA2, PPMd, BZip2 + BCJ, BCJ2, ARM, ARM64, IA64, Delta filters |
.7z |
ZIP (ZIP) |
50 4B 03 04 |
Deflate, Store (uncompressed) |
.zip, .jar, .apk, .aar, .epub |
TAR + Gzip (TAR_GZ) |
1F 8B |
Gzip (Deflate) over ustar / POSIX TAR headers |
.tar.gz, .tgz |
Bzip2 / TAR + Bzip2 (BZIP2) |
42 5A 68 (BZh) |
BWT + Huffman (libbzip2) over raw streams or TAR containers |
.bz2, .tbz2, .tar.bz2 |
Next Steps¶
- Getting Started: Add KioArch to your Gradle project and extract your first archive.
- Platform Guides: Learn platform-specific integrations for JVM, Android SAF (
Uri), iOS (NSData/NSURL), and Web (WasmJs/JS). - Architecture: Explore the internal streaming pipeline, JNI zero-copy design, and thread-safety guarantees.
- API Reference: Browse the full multiplatform KDoc documentation generated by Dokka.