dwarfs 0.2.0

A library for reading DwarFS archives (aka. DwarFS images)
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115

//! A library for reading [DwarFS][dwarfs] archives (aka. images).
//!
//! Currently, DwarFS filesystem version 2.3..=2.5 is supported,
//! which should be compatible with files generated by
//! [upstream `mkdwarfs`][dwarfs] v0.5.0..=v0.12.4 (latest at the time of
//! writing). Other versions may also be readable but are not guaranteed.
//!
//! [dwarfs]: https://github.com/mhx/dwarfs
//!
//! ```
//! use dwarfs::{Archive, ArchiveIndex, AsChunks};
//! use std::fs::File;
//!
//! # fn wrap() -> dwarfs::Result<()> {
//! // Open an archive file and load the metadata of it.
//! let file = File::open("./my.dwarfs")?;
//! let (index, mut archive) = Archive::new(file)?;
//!
//! // Hierarchy traversal.
//! for entry in index.root().entries() {
//!     let inode = entry.inode();
//!     println!("/{} mode={}", entry.name(), inode.metadata().file_type_mode());
//!     if let Some(deep) = inode.as_dir() {
//!         for entry in deep.entries() {
//!             // ...
//!         }
//!     }
//! }
//!
//! // Resolve paths.
//! let file: dwarfs::File = index.get_path(["src", "Cargo.toml"])
//!     .expect("does not exist")
//!     .as_file()
//!     .expect("not a file");
//! // The simple way to read content.
//! let bytes: Vec<u8> = file.read_to_vec(&mut archive)?;
//!
//! # Ok(()) }
//! ```
//!
//! ## Cargo features
//!
//! - `zstd`, `lzma`, `lz4` *(Only `zstd` is enabled by default)*
//!
//!   Enable relevant decompression algorithm support. `zstd` is the default
//!   compression algorithm `mkdwarfs` uses and it should be enough for most cases.
//!
//! - `log` *(Enabled by default)*
//!
//!   Enable trace-level logging and time measurement for internal events via
//!   [`log` crate][log]. Useful for profiling or debugging. Should not
//!   have performance penalty unless trace-level log is enabled.
//!
//! - `serialize` *(Disabled by default)*
//!
//!   Enable serialization support for various structures. Currently, it only
//!   includes [`metadata::Schema::to_bytes`].
//!
//! [log]: https://crates.io/crates/log
#![cfg_attr(docsrs, feature(doc_auto_cfg))]
#![forbid(unsafe_code)]
#![warn(missing_debug_implementations)]
#![warn(missing_docs)]

#[cfg(feature = "log")]
#[macro_use(trace_time)]
extern crate measure_time;

#[cfg(feature = "log")]
#[macro_use(trace)]
extern crate log;

#[cfg(not(feature = "log"))]
#[macro_use]
mod macros {
    macro_rules! trace {
        ($($tt:tt)*) => {
            let _ = if false {
                let _ = ::std::format_args!($($tt)*);
            };
        };
    }

    macro_rules! trace_time {
        ($($tt:tt)*) => {
            trace!($($tt)*)
        };
    }
}

macro_rules! bail {
    ($err:expr $(,)?) => {
        return Err(Into::into($err))
    };
}

pub mod archive;
pub mod fsst;
pub mod metadata;
pub mod section;

pub extern crate positioned_io;
pub extern crate zerocopy;

/// The range of filesystem version tuple `(major, minor)` supported by this library.
///
/// Currently this is `(2, 3)..=(2, 5)`.
// TODO: We could lower this.
pub const SUPPORTED_VERSION_RANGE: std::ops::RangeInclusive<(u8, u8)> = (2, 3)..=(2, 5);

#[doc(inline)]
pub use archive::{
    Archive, ArchiveIndex, AsChunks, Device, Dir, DirEntry, Error, File, Inode, InodeKind,
    InodeMetadata, Ipc, Result, Symlink,
};