Skip to main content

Choosing a crate

Start with the narrowest crate that owns the format or layer you need. Add a facade only when the application must detect formats or work across several storage categories.

Hadris architecture: applications use the umbrella crate over block, optical, and archive formats backed by shared I/O, paths, and storage

Quick decision table​

NeedStart withWhy
FAT12/16/32 filesystem accesshadris-fatComplete FAT API, including formatting and mutation
Experimental read-only NTFS accesshadris-ntfsNTFS remains a separate experimental leaf crate
MBR or GPT partition tableshadris-partConcrete partition parsing and writing
Block-format detection and partition viewshadris-blockCombines storage, partitions, and FAT without erasing concrete types
ISO 9660 imageshadris-isoISO, Joliet, Rock Ridge, and El Torito APIs
UDF imageshadris-udfUDF descriptors, reading, and image creation
ISO/UDF detection and openinghadris-opticalDetects bridge images and applies an explicit open policy
Hybrid ISO/UDF authoringhadris-cdBuilds images sharing file data between both filesystems
CPIO newc archives or initramfshadris-cpioComplete CPIO reader and writer
Several categories through one dependencyhadrisRe-exports selected category facades

Leaf crates​

Leaf crates own a concrete format. They expose the richest API, produce the smallest dependency graph, and are normally the right choice when the input format is known in advance.

Examples include hadris-fat, hadris-part, hadris-iso, hadris-udf, and hadris-cpio.

[dependencies]
hadris-fat = "2.1.0"

Category facades​

Category facades combine related layers and add detection or opening policy:

  • hadris-block combines storage traits, partitions, FAT, and block detection.
  • hadris-optical combines ISO, UDF, bridge detection, and hybrid authoring.
  • hadris-archive provides a common feature surface for sequential archives.

Facades preserve the underlying leaf types. They do not force unrelated formats behind one generic filesystem interface.

The umbrella crate​

Use hadris when an application spans multiple categories and benefits from a single dependency declaration.

[dependencies]
hadris = {
  version = "2.1.0",
  default-features = false,
  features = ["std", "sync", "read", "block", "optical"]
}

Using the umbrella does not enable every format automatically. Select category, platform, I/O, and capability features explicitly.

Foundation crates​

Most applications consume these indirectly, but they are useful integration points for kernels, firmware, and other storage libraries:

CrateRole
hadris-ioSync and async byte-stream traits and adapters
hadris-storageLogical-block geometry, device traits, and bounded views
hadris-pathAllocation-free lexical paths for virtual filesystems
hadris-fixedFixed-capacity byte, UTF-8, and UTF-16 values
hadris-commonShared endian and disk-format primitives
hadris-macrosInternal dual sync/async code-generation support

Experimental APIs​

The unstable-exfat feature and hadris-ntfs crate are outside the stable V2 API promise. They are appropriate for evaluation and compatibility testing, but callers should expect API and behavior changes.

NTFS is intentionally not opened by hadris-block or re-exported by the hadris umbrella. exFAT remains an opt-in feature of hadris-fat.

Next steps​