hadris_cd/
lib.rs

1//! # Hadris CD
2//!
3//! A Rust library for creating hybrid ISO+UDF optical disc images.
4//!
5//! ## Overview
6//!
7//! This crate creates "UDF Bridge" format images that contain both
8//! ISO 9660 and UDF filesystems. This provides maximum compatibility:
9//! - Legacy systems read ISO 9660
10//! - Modern systems read UDF
11//! - **Both filesystems share the same file data on disk**
12//!
13//! ## Quick Start
14//!
15//! ```rust
16//! use hadris_cd::{OpticalImageWriter, OpticalImageOptions, FileTree, FileEntry};
17//! # use std::io::Cursor;
18//!
19//! // Create a file tree
20//! let mut tree = FileTree::new();
21//! tree.add_file(FileEntry::from_buffer("readme.txt", b"Hello, World!".to_vec()));
22//!
23//! // Create the hybrid image
24//! # // Use a Cursor for the doctest instead of a real file
25//! # let buffer = vec![0u8; 2 * 1024 * 1024]; // 2MB buffer
26//! # let file = Cursor::new(buffer);
27//! let options = OpticalImageOptions::default()
28//!     .volume_id("MY_DISC")
29//!     .joliet(hadris_cd::JolietLevel::Level3);
30//!
31//! let _file = OpticalImageWriter::new(file, options)
32//!     .finish(tree)
33//!     .unwrap();
34//! ```
35//!
36//! ## Disk Layout
37//!
38//! The UDF Bridge format interleaves ISO 9660 and UDF structures:
39//!
40//! ```text
41//! Sector 0-15:    System area (boot code, partition tables)
42//! Sector 16-...:  ISO 9660 Volume Descriptors
43//! Sector 17-19:   UDF Volume Recognition Sequence (BEA01, NSR02, TEA01)
44//! Sector 256:     UDF Anchor Volume Descriptor Pointer
45//! Sector 257+:    UDF Volume Descriptor Sequence
46//! File data:      Shared between ISO and UDF (both point to same sectors)
47//! ```
48//!
49//! ## Features
50//!
51//! - ISO 9660 with Joliet (Windows long filenames) and Rock Ridge (POSIX)
52//! - UDF 1.02/1.50/2.00+ support
53//! - El-Torito bootable images
54//! - Hybrid MBR+GPT for USB booting
55//!
56//! Bridge output is continuously tested by opening the completed image through
57//! both the ISO 9660 and UDF readers.
58//!
59//! Hybrid image creation currently uses the synchronous ISO and UDF writers.
60//! This crate therefore exposes a sync-only writer API; `std` selects hosted
61//! platform support, while the default feature set selects `sync` explicitly.
62
63#![allow(async_fn_in_trait)]
64#![deny(missing_docs)]
65
66// ---------------------------------------------------------------------------
67// Shared types (compiled once)
68// ---------------------------------------------------------------------------
69
70#[cfg(feature = "sync")]
71pub mod error;
72#[cfg(feature = "sync")]
73pub mod layout;
74#[cfg(feature = "sync")]
75pub mod options;
76#[cfg(feature = "sync")]
77pub mod tree;
78
79// ---------------------------------------------------------------------------
80// Sync module
81// ---------------------------------------------------------------------------
82
83#[cfg(feature = "sync")]
84#[path = ""]
85/// Synchronous hybrid optical-image writer API.
86pub mod sync {
87    pub use hadris_io::SeekFrom;
88    pub use hadris_io::sync::{Borrowed, Read, Seek, Write};
89
90    macro_rules! io_transform {
91        ($($item:tt)*) => { hadris_macros::strip_async!{ $($item)* } };
92    }
93
94    #[allow(unused_macros)]
95    macro_rules! sync_only {
96        ($($item:tt)*) => { $($item)* };
97    }
98
99    #[allow(unused_macros)]
100    macro_rules! async_only {
101        ($($item:tt)*) => {};
102    }
103
104    #[path = "."]
105    mod __inner {
106        pub mod writer;
107    }
108    pub use __inner::*;
109
110    pub use __inner::writer::OpticalImageWriter;
111}
112
113// ---------------------------------------------------------------------------
114// Default re-exports for backwards compatibility (sync)
115// ---------------------------------------------------------------------------
116
117#[cfg(feature = "sync")]
118pub use sync::*;
119
120// Re-exports from shared types
121#[cfg(feature = "sync")]
122pub use error::{Error, Result};
123#[cfg(feature = "sync")]
124pub use layout::{LayoutInfo, LayoutManager};
125#[cfg(feature = "sync")]
126pub use options::{IsoOptions, JolietLevel, OpticalImageOptions, UdfOptions};
127#[cfg(feature = "sync")]
128pub use tree::{Directory, FileData, FileEntry, FileExtent, FileTree};
hadris_cd/lib.rs

hadris_cd/
lib.rs
