android-sparse

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, libsparse is part of the Android Open Source Project (AOSP). It provides utilities to convert from raw to sparse images and back, called img2simg and simg2img, 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 (img2simg)
• converting sparse to raw images (simg2img)

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.

Installation

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:

$ 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:

• $HOME/.cargo/bin on Unix
• %USERPROFILE%\.cargo\bin on Windows

Usage

Encoding

Encoding a raw image to a sparse image:

$ img2simg <raw_image> <sparse_image>

The -c/--crc flag makes img2simg write a checksum to the sparse image:

$ img2simg --crc <raw_image> <sparse_image>

Decoding

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>

The -c/--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>

License

This project is licensed under the MIT license (LICENSE or http://opensource.org/licenses/MIT).

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.