littlefs_rust/lib.rs
1#![cfg_attr(not(feature = "std"), no_std)]
2
3//! Pure Rust implementation of the littlefs v2 on-disk format.
4//!
5//! Inspired by littlefs. This is independent Rust code with interoperability
6//! against upstream littlefs treated as a design constraint.
7//!
8//! The public API is centered on a synchronous [`BlockDevice`] trait plus
9//! mounted read-only and mutable filesystem handles. Core library code supports
10//! `no_std + alloc`; the default `std` feature adds [`FileBlockDevice`] for
11//! local-file backed images in tests and host-side tools.
12//!
13//! # Example
14//!
15//! ```no_run
16//! use littlefs_rust::{Config, FileBlockDevice, FileOptions, Filesystem};
17//!
18//! fn main() -> littlefs_rust::Result<()> {
19//! let cfg = Config {
20//! block_size: 512,
21//! block_count: 4096,
22//! };
23//!
24//! let path = std::env::temp_dir().join("littlefs-rust-doc-example.img");
25//! let mut device = FileBlockDevice::create_erased(&path, cfg)?;
26//! Filesystem::format_device(&mut device)?;
27//!
28//! let mut fs = Filesystem::mount_device_mut(device)?;
29//! fs.create_dir("/logs")?;
30//!
31//! let mut file = fs.open_file(
32//! "/logs/current.txt",
33//! FileOptions::new()
34//! .create(true)
35//! .write(true)
36//! .append(true),
37//! )?;
38//! file.write_all(b"boot ok\n")?;
39//! file.sync()?;
40//! file.close()?;
41//!
42//! let device = fs.into_device();
43//! let ro = Filesystem::mount_device(&device)?;
44//! assert_eq!(ro.read_file("/logs/current.txt")?, b"boot ok\n");
45//!
46//! let _ = std::fs::remove_file(path);
47//! Ok(())
48//! }
49//! ```
50//!
51//! # Main Entry Points
52//!
53//! - [`Filesystem::format_device`] formats a block device.
54//! - [`Filesystem::mount_device`] mounts a borrowed block device read-only.
55//! - [`Filesystem::mount_device_mut`] mounts an owned block device for writes.
56//! - [`FilesystemOptions`] configures littlefs-style cache, program, limit,
57//! block-cycle, and inline-file policy.
58//! - [`FileOptions`] configures open-file handles for read, write, append,
59//! create, create-new, and truncate behavior.
60//!
61//! # Interoperability
62//!
63//! The repository's default test suite uses real image bytes and compares
64//! filesystem-visible behavior with the bundled upstream C littlefs
65//! implementation whenever a matching oracle exists. See `tests/README.md` in
66//! the repository for the current compatibility matrix.
67//!
68//! # Internal Layout
69//!
70//! The crate is intentionally split by littlefs layers:
71//!
72//! - `format` knows about raw on-disk numbers, tags, endian quirks, and CRCs.
73//! - `commit` writes metadata block commits using the same tag/CRC machinery.
74//! - `metadata` turns committed metadata logs into semantic file records.
75//! - `fs` exposes read-only and mounted mutable filesystem APIs.
76//! - `writer` contains explicit full-image builder/editor utilities for
77//! fixtures, host tools, and interop tests.
78
79extern crate alloc;
80
81#[cfg(feature = "std")]
82extern crate std;
83
84mod allocator;
85mod block_device;
86mod cache;
87mod commit;
88mod format;
89mod fs;
90mod metadata;
91mod path;
92mod types;
93mod writer;
94
95#[cfg(feature = "std")]
96pub use block_device::FileBlockDevice;
97pub use block_device::{BlockDevice, MemoryBlockDevice};
98pub use fs::{DirHandle, FileHandle, FileOptions, FileWriter, Filesystem, FilesystemMut};
99pub use types::{
100 Config, DirEntry, DirectoryUsage, Error, FileType, FilesystemLimits, FilesystemOptions, FsInfo,
101 InlineMax, Result, WalkEntry,
102};
103pub use writer::{ImageBuilder, ImageEditor};