8 releases (5 breaking)
Uses new Rust 2021
|0.6.0||Dec 8, 2021|
|0.5.0||Aug 19, 2018|
|0.4.0||Aug 5, 2018|
|0.3.1||Nov 11, 2017|
|0.1.1||Oct 22, 2017|
#443 in Command line utilities
21 downloads per month
An implementation of Android's sparse file format in Rust.
Sparse is a simple file compression format. It is supported by Android's fastboot protocol as a means of dealing with images that are too large to fit into the device's memory at once. Android images are often provided in sparse format and must be decoded before they can be further inspected.
There is no official documentation of the sparse format. However,
is part of the Android Open Source Project (AOSP). It provides utilities to
convert from raw to sparse images and back, called
respectively. Unfortunately, these tools are not part of the Android SDK. To
use them, one has to download the AOSP and build them from source, which can
be a rather time-consuming undertaking.
This project reimplements parts of libsparse in Rust to make working with sparse images less of a hassle. While android-sparse doesn't implement all features of libsparse, it supports the main use cases of:
- converting raw to sparse images (
- converting sparse to raw images (
Additionally, being implemented in Rust it has a couple of advantages over libsparse, namely guaranteed memory safety and a significantly simpler build process across all major operating systems.
To build android-sparse, you need a working installation of Rust. Check out https://www.rustup.rs for instructions.
The latest stable version of android-sparse is available on
crates.io. You can install it with
$ cargo install android-sparse
This installs the android-sparse tools in
cargo's bin directory. If you
installed Rust via
rustup, this directory is located at:
Encoding a raw image to a sparse image:
$ img2simg <raw_image> <sparse_image>
--crc flag makes
img2simg write a checksum to the sparse image:
$ img2simg --crc <raw_image> <sparse_image>
Decoding a sparse image to a raw image:
$ simg2img <sparse_image> <raw_image>
It's also possible to decode multiple sparse images to a single raw image by specifying them separated by commas:
$ simg2img <sparse_image>,<sparse_image>,... <raw_image>
--crc flag makes
simg2img check the checksums included in the
sparse image. Decoding is aborted if they don't match.
$ simg2img --crc <sparse_image> <raw_image>
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in android-sparse by you, shall be licensed as above, without any additional terms or conditions.