diff --git a/Cargo.toml b/Cargo.toml index a8fb848..c433a08 100644 --- a/Cargo.toml +++ b/Cargo.toml @@ -3,7 +3,7 @@ name = "damascus" description = "filesystem utility crate for the Flamberg mod manager stack" authors = ["Yato202010"] keywords = ["filesystem", "fuse-overlayfs", "overlayfs"] -version = "0.0.4" +version = "0.0.6" repository = "https://github.com/Yato202010/Damascus" license-file = "LICENSE" edition = "2021" @@ -73,3 +73,7 @@ opt-level = "s" name = "end2end" path = "tests/end2end.rs" harness = false + +[package.metadata.docs.rs] +features = ["fuse-overlayfs", "overlayfs"] +no-default-features = true diff --git a/README.md b/README.md index 895647c..bfc98b2 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,29 @@ with filesystem from rust | Linux | Experimental | UnionFsFuse | | MacOS | Unsupported | / | +## How to use ? + +```rust +use damascus::{Filesystem, FuseOverlayFs, FuseOverlayFsOption, LinuxFilesystem, MountOption}; + +// handle can be created using complex or simple interface based on need +// NOTE : drop control if once dropped the filesystem should be unmounted +let mut o = FuseOverlayFs::new([&lower1, &lower2].iter(), Some(upper), Some(work), target, drop).unwrap(); +// or +let mut o = FuseOverlayFs::writable([&lower1, &lower2].iter(), upper, work, &target).unwrap(); +// or +let mut o = FuseOverlayFs::readonly([&lower1, &lower2].iter(), target).unwrap(); + +o.set_option(FuseOverlayFsOption::AllowRoot).unwrap(); +o.set_unmount_on_drop(false); // true by default + +// once configured you can mount it +o.mount().unwrap(); + +// and then unmount it +o.unmount().unwrap(); +``` + ## FAQ - Will you target Windows and MacOS support? diff --git a/build.rs b/build.rs index bd4d502..db1a20c 100644 --- a/build.rs +++ b/build.rs @@ -1,5 +1,3 @@ -use fs_extra::dir::CopyOptions; - fn main() { println!("cargo:rerun-if-changed=vendor"); @@ -24,7 +22,9 @@ fn main() { fs_extra::dir::copy( &d, &srcdir, - &CopyOptions::new().overwrite(true).content_only(true), + &fs_extra::dir::CopyOptions::new() + .overwrite(true) + .content_only(true), ) .unwrap(); autotools::Config::new(srcdir) diff --git a/src/common/fs.rs b/src/common/fs.rs index abcd66b..edb716c 100644 --- a/src/common/fs.rs +++ b/src/common/fs.rs @@ -66,5 +66,6 @@ pub trait CaseInsensitive: Filesystem {} /// ex: /etc/mtab on Linux, etc... #[allow(dead_code)] pub trait StateRecovery: Filesystem { + /// Recover filesystem handle from system information fn recover>(path: P) -> Result; } diff --git a/src/os/linux/fuseoverlay.rs b/src/os/linux/fuseoverlay.rs index 762658f..706bb0c 100644 --- a/src/os/linux/fuseoverlay.rs +++ b/src/os/linux/fuseoverlay.rs @@ -15,7 +15,7 @@ use tracing::{debug, error}; use crate::{ common::fs::Filesystem, - os::{linux::FuseOverlayFsOption, AsCString, AsPath}, + os::{linux::fuseoverlay::opt::FuseOverlayFsOption, AsCString, AsPath}, LinuxFilesystem, MountOption, PartitionID, StackableFilesystem, }; diff --git a/src/os/linux/mod.rs b/src/os/linux/mod.rs index d826297..c1271f2 100644 --- a/src/os/linux/mod.rs +++ b/src/os/linux/mod.rs @@ -1,15 +1,15 @@ #[cfg(feature = "unionfs-fuse")] -mod unionfs_fuse; +pub mod unionfs_fuse; #[cfg(feature = "unionfs-fuse")] -pub use unionfs_fuse::{opt::*, UnionFsFuse}; +pub use unionfs_fuse::UnionFsFuse; #[cfg(feature = "fuse-overlayfs")] -mod fuseoverlay; +pub mod fuseoverlay; #[cfg(feature = "fuse-overlayfs")] -pub use fuseoverlay::{opt::*, FuseOverlayFs}; +pub use fuseoverlay::FuseOverlayFs; #[cfg(feature = "overlayfs")] -mod overlay; +pub mod overlay; #[cfg(feature = "overlayfs")] -pub use overlay::{opt::*, OverlayFs}; +pub use overlay::OverlayFs; pub use option::{FsOption, LinuxFilesystem, MountOption}; @@ -35,6 +35,7 @@ mod recover_state { } } + /// Retrieve filesystem data from system information pub fn restore_fsdata, O: FsOption>(path: P) -> Result>> { let fd = unsafe { let mtab = CStr::from_bytes_with_nul_unchecked(b"/etc/mtab\0"); @@ -76,15 +77,21 @@ mod option { where O: FsOption, { + /// Set option + /// will send error if another incompatible option is present fn set_option(&mut self, option: impl Into>) -> Result<()>; + /// Remove an option fn remove_option(&mut self, option: impl Into>) -> Result<()>; + /// List currently active option fn options(&self) -> &[MountOption]; } pub trait FsOption: Sized + Clone + Display + FromStr { + /// Get defaults mount option for this filesystem fn defaults() -> Vec; + /// Check if mount option is incompatible fn incompatible(&self, other: &MountOption) -> bool; } @@ -98,6 +105,7 @@ mod option { } impl MountOption { + /// Get defaults mount option for this filesystem pub fn defaults() -> Vec { let mut v: Vec> = vec![]; let mut r = T::defaults(); @@ -105,6 +113,7 @@ mod option { v } + /// Check if mount option is incompatible pub fn incompatible(&self, other: &MountOption) -> bool { match self { MountOption::FsSpecific(o) => o.incompatible(other), diff --git a/src/os/linux/overlay.rs b/src/os/linux/overlay.rs index 4d8628f..9276f00 100644 --- a/src/os/linux/overlay.rs +++ b/src/os/linux/overlay.rs @@ -20,8 +20,8 @@ use tracing::{debug, error}; use crate::{ common::fs::{Filesystem, StateRecovery}, os::{ + linux::overlay::opt::OverlayFsOption, linux::recover_state::{restore_fsdata, FsData}, - linux::OverlayFsOption, AsCString, AsPath, LinuxFilesystem, MountOption, }, PartitionID, StackableFilesystem, diff --git a/src/os/linux/overlay/opt.rs b/src/os/linux/overlay/opt.rs index a8fc98a..c9e98bc 100644 --- a/src/os/linux/overlay/opt.rs +++ b/src/os/linux/overlay/opt.rs @@ -72,7 +72,7 @@ pub enum OverlayFsOption { /// bits for fsid, because the underlying filesystems rarely use the high inode number bits. In case the underlying inode number does overflow into the high xino /// bits, overlay filesystem will fall back to the non xino behavior for that inode. /// - /// For a detailed description of the effect of this option please refer to https://docs.kernel.org/filesystems/overlayfs.html + /// For a detailed description of the effect of this option please refer to Xino(Xino), /// Use the "user.overlay." xattr namespace instead of "trusted.overlay.". This is useful for unprivileged mounting of overlayfs. UserXattr, diff --git a/src/os/linux/unionfs_fuse.rs b/src/os/linux/unionfs_fuse.rs index 855b2b3..afee07a 100644 --- a/src/os/linux/unionfs_fuse.rs +++ b/src/os/linux/unionfs_fuse.rs @@ -16,7 +16,7 @@ use tracing::{debug, error}; use crate::{ common::fs::Filesystem, - os::{linux::UnionFsFuseOption, AsCString, AsPath}, + os::{linux::unionfs_fuse::opt::UnionFsFuseOption, AsCString, AsPath}, LinuxFilesystem, MountOption, PartitionID, StackableFilesystem, }; diff --git a/tests/linux/overlayfs.rs b/tests/linux/overlayfs.rs index dde3cf8..0c46b56 100644 --- a/tests/linux/overlayfs.rs +++ b/tests/linux/overlayfs.rs @@ -2,7 +2,8 @@ use crate::skip; use super::{execute_test, read_only_test, read_test, setup_namespaces, write_test}; use damascus::{ - Filesystem, LinuxFilesystem, OverlayFs, RedirectDir, StackableFilesystem, StateRecovery, + overlay::opt::RedirectDir, Filesystem, LinuxFilesystem, OverlayFs, StackableFilesystem, + StateRecovery, }; use nix::unistd::geteuid; use std::fs::create_dir_all;