feat(doc): add doc + import rework

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

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?

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)

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<P: AsRef<Path>>(path: P) -> Result<Self>;
 }

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,
 };
 

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<P: AsRef<Path>, O: FsOption>(path: P) -> Result<Option<FsData<O>>> {
         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<MountOption<O>>) -> Result<()>;
 
+        /// Remove an option
         fn remove_option(&mut self, option: impl Into<MountOption<O>>) -> Result<()>;
 
+        /// List currently active option
         fn options(&self) -> &[MountOption<O>];
     }
 
     pub trait FsOption: Sized + Clone + Display + FromStr {
+        /// Get defaults mount option for this filesystem
         fn defaults() -> Vec<Self>;
+        /// Check if mount option is incompatible
         fn incompatible(&self, other: &MountOption<Self>) -> bool;
     }
 
@@ -98,13 +105,15 @@ mod option {
     }
 
     impl<T: FsOption> MountOption<T> {
+        /// Get defaults mount option for this filesystem
         pub fn defaults() -> Vec<Self> {
             let mut v: Vec<MountOption<T>> = vec![];
             let mut r = T::defaults();
             v.extend(r.iter_mut().map(|x| MountOption::FsSpecific(x.clone())));
             v
         }
 
+        /// Check if mount option is incompatible
         pub fn incompatible(&self, other: &MountOption<T>) -> bool {
             match self {
                 MountOption::FsSpecific(o) => o.incompatible(other),

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,

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 <https://docs.kernel.org/filesystems/overlayfs.html>
     Xino(Xino),
     /// Use the "user.overlay." xattr namespace instead of "trusted.overlay.". This is useful for unprivileged mounting of overlayfs.
     UserXattr,

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,
 };
 

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;