dwarfs_enc/lib.rs
1//! A library for writing [DwarFS][dwarfs] archives (aka. images),
2//! building on top of [`dwarfs` crate][::dwarfs].
3//!
4//! For reading archives only, check [`dwarfs` crate][::dwarfs] instead.
5//!
6//! [dwarfs]: https://github.com/mhx/dwarfs
7//!
8//! Currently, this crate writes DwarFS archive with filesystem version v2.5,
9//! which should be compatible with upstream dwarfs v0.7.0..=v0.12.4 (latest at
10//! the time of writing).
11//!
12//! ## Examples
13//!
14//! ```
15//! use dwarfs_enc::{
16//! chunker::{Chunker, BasicChunker, CdcChunker},
17//! metadata::{Builder as MetaBuilder, InodeMetadata},
18//! section::{Writer as SectionWriter, CompressParam},
19//! };
20//! use std::{fs, time::SystemTime};
21//!
22//! # fn work() -> dwarfs_enc::Result<()> {
23//! let f = fs::File::create("out.dwarfs")?;
24//!
25//! // Create inode metadata.
26//! let mut dir_meta = InodeMetadata::new(0o755);
27//! dir_meta.uid(1000).gid(1000).atime(SystemTime::now());
28//! // ... or initialize from OS metadata.
29//! let file_meta = InodeMetadata::from(&fs::metadata("./bar")?);
30//!
31//! // Create a hierarchy builder initialized with a root inode.
32//! let mut meta = MetaBuilder::new(&dir_meta);
33//!
34//! // Use ZSTD compression level 22, Content Defined Chunking (CDC) for deduplication.
35//! let compress = CompressParam::Zstd(22);
36//! let writer = SectionWriter::new(f)?;
37//! let chunker = BasicChunker::new(writer, meta.block_size(), compress);
38//! let mut chunker = CdcChunker::new(chunker);
39//!
40//! // Put a directories and a symlink.
41//! let root = meta.root();
42//! let subdir = meta.put_dir(root, "subdir", &dir_meta)?;
43//! meta.put_symlink(subdir, "symlink", &file_meta, "./subdir")?;
44//!
45//! // Put a regular file, using in-memory data.
46//! meta.put_file(root, "foo", &file_meta, chunker.put_bytes(b"hello world")?)?;
47//! // Put a regular file, reading from an OS File.
48//! let chunks = chunker.put_reader(&mut fs::File::open("bar")?)?;
49//! let bar = meta.put_file(root, "bar", &file_meta, chunks)?;
50//!
51//! // Hard links are also supported.
52//! meta.put_hard_link(root, "hardlink", bar)?;
53//!
54//! // Finalizing data chunks, metadata, and section writer in order.
55//! let mut writer = chunker.finish()?;
56//! writer.write_metadata_sections(&meta.finish()?, compress)?;
57//! writer.finish()?;
58//!
59//! # Ok(()) }
60//! ```
61//!
62//! See also the simple `mkdwarfs` impl at `./examples/mkdwarfs.rs`.
63//!
64//! ## Cargo features
65//!
66//! - `zstd`, `lzma` *(Only `zstd` is enabled by default)*
67//!
68//! Enable relevant compression algorithm support. `zstd` is the default
69//! compression algorithm `mkdwarfs` uses and it should be enough for most cases.
70#![cfg_attr(docsrs, feature(doc_auto_cfg))]
71#![forbid(unsafe_code)]
72#![warn(missing_debug_implementations)]
73#![warn(missing_docs)]
74mod error;
75
76pub mod chunker;
77pub mod metadata;
78mod ordered_parallel;
79pub mod section;
80
81use self::error::ErrorInner;
82pub use self::error::{Error, Result};