Crate hadris_iso 

Hadris ISO

A comprehensive Rust implementation of the ISO 9660 filesystem with support for Joliet, Rock Ridge (RRIP), El-Torito booting, and no-std environments.

This crate provides both reading and writing capabilities for ISO 9660 images, making it suitable for:

• Bootloaders: Minimal no-std + no-alloc read support
• OS Kernels: Read ISO filesystems with only a heap allocator
• Desktop Applications: Full-featured ISO creation and extraction
• Build Systems: Automated bootable ISO generation

Quick Start

Reading an ISO Image

use hadris_iso::read::IsoImage;

let image = IsoImage::open(reader).unwrap();

// Get the root directory
let root = image.root_dir();

// Iterate through files
for entry in root.iter(&image).entries() {
    let entry = entry.unwrap();
    println!("File: {:?}", String::from_utf8_lossy(entry.name()));
}

Creating a Bootable ISO

use std::io::Cursor;
use std::sync::Arc;
use hadris_iso::boot::options::{BootEntryOptions, BootOptions};
use hadris_iso::boot::EmulationType;
use hadris_iso::read::PathSeparator;
use hadris_iso::write::options::{BaseIsoLevel, CreationFeatures, FormatOptions};
use hadris_iso::write::{File as IsoFile, InputFiles, IsoImageWriter};

// Prepare files to include (use dummy boot image for example)
let files = InputFiles {
    path_separator: PathSeparator::ForwardSlash,
    files: vec![
        IsoFile::File {
            name: Arc::new("boot.bin".to_string()),
            contents: boot_image,
        },
    ],
};

// Configure boot options
let boot_options = BootOptions {
    write_boot_catalog: true,
    default: BootEntryOptions {
        boot_image_path: "boot.bin".to_string(),
        load_size: Some(std::num::NonZeroU16::new(4).unwrap()),
        boot_info_table: false,
        grub2_boot_info: false,
        emulation: EmulationType::NoEmulation,
    },
    entries: vec![],
};

// Create the ISO
let format_options = FormatOptions {
    volume_name: "MY_BOOTABLE_ISO".to_string(),
    sector_size: 2048,
    path_seperator: PathSeparator::ForwardSlash,
    features: CreationFeatures {
        filenames: BaseIsoLevel::Level1 {
            supports_lowercase: false,
            supports_rrip: false,
        },
        long_filenames: false,
        joliet: None,
        rock_ridge: None,
        el_torito: Some(boot_options),
        hybrid_boot: None,
    },
};

let mut buffer = Cursor::new(vec![0u8; 2 * 1024 * 1024]); // 2MB buffer
IsoImageWriter::format_new(&mut buffer, files, format_options).unwrap();

Feature Flags

This crate uses feature flags to control functionality and dependencies:

Feature	Description	Dependencies
read	Minimal read support (no-std, no-alloc)	None
alloc	Heap allocation without full std	alloc crate
std	Full standard library support	std, alloc, thiserror, tracing, chrono
write	ISO creation/formatting	std, alloc
joliet	UTF-16 Unicode filename support	alloc

Feature Combinations

For Bootloaders (minimal footprint):

[dependencies]
hadris-iso = { version = "0.2", default-features = false, features = ["read"] }

For Kernels with Heap (no-std + alloc):

[dependencies]
hadris-iso = { version = "0.2", default-features = false, features = ["read", "alloc"] }

For Desktop Applications (full features):

[dependencies]
hadris-iso = { version = "0.2" }  # Uses default features: std, write

ISO 9660 Extensions

Joliet Extension

Joliet provides Unicode filename support using UTF-16 encoding. It allows filenames up to 64 characters and preserves case. Enable with the joliet feature.

use hadris_iso::joliet::JolietLevel;
use hadris_iso::write::options::CreationFeatures;

let features = CreationFeatures {
    joliet: Some(JolietLevel::Level3), // Full Unicode support
    ..Default::default()
};

Rock Ridge (RRIP) Extension

Rock Ridge provides POSIX filesystem semantics including:

• Long filenames (up to 255 characters)
• Unix permissions and ownership
• Symbolic links
• Device files

El-Torito Boot Extension

El-Torito enables bootable CD/DVD images. This crate supports:

• BIOS boot (x86/x86_64)
• UEFI boot
• No-emulation boot mode
• Boot information table injection

Hybrid Boot (USB Boot)

Hybrid boot enables ISOs to be bootable when written directly to USB drives:

• MBR mode - For BIOS systems (isohybrid-compatible)
• GPT mode - For UEFI systems
• Hybrid MBR+GPT - For dual BIOS/UEFI compatibility

use hadris_iso::write::options::{CreationFeatures, HybridBootOptions, PartitionScheme};

// Enable MBR-based hybrid boot for USB
let features = CreationFeatures {
    hybrid_boot: Some(HybridBootOptions::mbr()),
    ..Default::default()
};

// Enable dual BIOS/UEFI boot
let features = CreationFeatures {
    hybrid_boot: Some(HybridBootOptions::hybrid()),
    ..Default::default()
};

Architecture

The crate is organized into several modules:

• boot - El-Torito boot catalog structures and options
• directory - Directory record parsing and creation
• file - File entry types and filename handling
• io - Sector-based I/O abstractions
• joliet - Joliet UTF-16 extension support
• path - Path table structures
• read - ISO image reading and navigation
• rrip - Rock Ridge extension support
• susp - System Use Sharing Protocol (base for Rock Ridge)
• types - Common types (endian values, strings, dates)
• volume - Volume descriptor structures
• write - ISO image creation

Compatibility

ISOs created with this crate are compatible with:

• Linux (mount, isoinfo)
• Windows (built-in ISO support)
• macOS (built-in ISO support)
• QEMU/VirtualBox (bootable ISOs)
• xorriso (can read/verify)

Specification References

This implementation follows these specifications:

• ECMA-119 (ISO 9660)
• Joliet Specification (Microsoft)
• IEEE P1282 (Rock Ridge / RRIP)
• El-Torito Bootable CD-ROM Format Specification

For detailed specification documentation, see the spec directory.

Modules

boot

El-Torito boot support.

directory

Directory record structures for parsing and creating directory entries.

file

File entry types and interchange levels.

io

Sector-based I/O abstractions for reading and writing ISOs.

joliet

Joliet extension for Unicode filenames.

modify

ISO image modification and append support.

path

Path table structures for fast directory lookup.

read

ISO image reading and navigation.

rrip

Rock Ridge Interchange Protocol (RRIP) extension.

susp

System Use Sharing Protocol (SUSP).

types

Common types used throughout the crate.

volume

Volume descriptor structures.

write

ISO image creation and formatting.