zarchive

Crates.iozarchive
lib.rszarchive
version0.2.0
sourcesrc
created_at2022-06-30 20:10:08.551646
updated_at2023-03-02 19:36:50.217095
descriptionSimple Rust bindings to Exzap's ZArchive library
homepage
repositoryhttps://github.com/NiceneNerd/zarchive-rs
max_upload_size
id616688
size274,583
Caleb Smith (NiceneNerd)

documentation

README

crates.io api license build

Simple Rust bindings to ZArchive.

Overview

ZArchive is yet another file archive format. Think of zip, tar, 7z, etc. but with the requirement of allowing random-access reads and supporting compression.

Features / Specifications

  • Supports random-access reads within stored files
  • Uses zstd compression (64KiB blocks)
  • Scales reasonably well up to multiple terabytes with millions of files
  • The theoretical size limit per-file is 2^48-1 (256 Terabyte)
  • The encoding for paths within the archive is Windows-1252 (case-insensitive)
  • Contains a SHA256 hash of the whole archive for integrity checks
  • Endian-independent. The format always uses big-endian internally
  • Stateless file and directory iterator handles which don't require memory allocation (not entirely true of the Rust bindings)

Rust Bindings

The zarchive crate provides Rust bindings to the C++ library. The API is intentionally limited. While most of the reader API is implemented, only a basic archive packing function is exposed for writing, due to complex safety considerations. The Rust bindings add some slight overhead to the reader's directory iteration API, but hopefully with a sufficient benefit of convenience.

Example - Pack and extract an archive

use zarchive::{pack, extract};
pack("/path/to/stuff/to/pack", "/path/to/archive.zar")?;
extract("/path/to/archive.zar", "/path/to/extract")?;

Limitations

  • Not designed for adding, removing or modifying files after the archive has been created

No-seek creation

When creating new archives only byte append operations are used. No file seeking is necessary. This makes it possible to create archives on storage which is write-once. It also simplifies streaming ZArchive creation over network.

UTF8 paths

UTF8 for file and folder paths is theoretically supported as paths are just binary blobs. But the case-insensitive comparison only applies to latin letters (a-z). The Rust bindings use the primitive &str type, which means that all paths passed through this API are UTF8.

Wii U specifics

Originally this format was created to store Wii U games dumps. These use the file extension .wua (Wii U Archive) but are otherwise regular ZArchive files. To allow multiple Wii U titles to be stored inside a single archive, each title must be placed in a subfolder following the naming scheme: 16-digit titleId followed by _v and then the version as decimal. For example: 0005000e10102000_v32

License

The zarchive crate is licensed under the GPL 3+. The original ZArchive library is licensed under MIT No Attribution, with the exception of sha_256.c and sha_256.h which are public domain, see: https://github.com/amosnier/sha-2.

Commit count: 26

cargo fmt