Format, fix, document, Etc 09/15

README.md

@@ -23,9 +23,9 @@ of continuing development. In particular adding features from ABIs after 7.19
 
 A working FUSE filesystem consists of three parts:
 
-1. The **kernel driver** that registers as a filesystem and forwards operations into a communication channel to a userspace process that handles them.
-1. The **userspace library** (libfuse) that helps the userspace process to establish and run communication with the kernel driver.
-1. The **userspace implementation** that actually processes the filesystem operations.
+1. The **kernel driver** (part of the operating system) that registers as a filesystem and forwards operations into a communication channel to a userspace process that handles them.
+1. The **userspace library** (e.g., `fuser` and/or `libfuse`) that helps the userspace process to establish and run communication with the kernel driver.
+1. The **userspace implementation** (your code here) that actually processes the filesystem operations.
 
 The kernel driver is provided by the FUSE project, the userspace implementation needs to be provided by the developer. FUSE-Rust provides a replacement for the libfuse userspace library between these two. This way, a developer can fully take advantage of the Rust type interface and runtime features when building a FUSE filesystem in Rust.
 
@@ -107,6 +107,13 @@ fuser = "0.15"
 
 To create a new filesystem, implement the trait `fuser::Filesystem`. See the [documentation] for details or the `examples` directory for some basic examples.
 
+### Feature Gates
+
+The crate uses feature gates to manage optional functionality and dependencies. Some key features include:
+*   **`abi-7-x`**: A set of features to select the FUSE protocol version. Recommended to select the highest version.
+*   **`libfuse`**: Use libfuse bindings for some very low-level operations. An older alternative to the newer Rust-native implementations.
+*   **`serializable`**: Enable conversion between `fuser` data structures and raw bytes, for saving to disk or transmission over a network.
+
 ## To Do
 
 Most features of libfuse up to 3.10.3 are implemented. Feel free to contribute. See the [list of issues][issues] on GitHub and search the source files for comments containing "`TODO`" or "`FIXME`" to see what's still missing.
@@ -119,10 +126,26 @@ Developed and tested on Linux. Tested under [Linux][FUSE for Linux] and [FreeBSD
 
 Licensed under [MIT License](LICENSE.md), except for those files in `examples/` that explicitly contain a different license.
 
-## Contribution
+## Contributing
 
 Fork, hack, submit pull request. Make sure to make it useful for the target audience, keep the project's philosophy and Rust coding standards in mind. For larger or essential changes, you may want to open an issue for discussion first. Also remember to update the [Changelog] if your changes are relevant to the users.
 
+### Concepts
+
+A brief overview of Fuser concepts for new contributors.
+
+* **`Session`**: The core struct which saves configuration options. Its provides methods to start and end event handling loops.
+* **`Request`** and **`Reply`**: These structures represents one FUSE operation initiated by the Kernel. The Request methods handle unpacks this message, and directs it to the filesystem. The Reply methods packege the response and pass it back to the kernel.
+* **`Notification`**: This structure represents a message for the Kernel initiated by the User application (i.e., not in response to a `Request`).
+* **`Filesystem`**: User application code.
+
+### Subdirectories
+
+A bried overview of repository organization for new contributors. 
+
+*   **`src/mnt/`**: Code for establishing communication with the fuse device, which is called mounting.
+*   **`src/ll/`**: The low-level FUSE message interface. This module contains the raw FUSE ABI definitions and is responsible for the translating between Rust-based data structures and byte-based fuse kernel messages. It is not recommended for applications to use this code directly.
+
 [Rust]: https://rust-lang.org
 [Homebrew]: https://brew.sh
 [Changelog]: https://keepachangelog.com/en/1.0.0/

examples/ioctl.rs

@@ -1,6 +1,6 @@
 // This example requires fuse 7.11 or later. Run with:
 //
-//   cargo run --example ioctl --features abi-7-11 /tmp/foobar
+//   cargo run --example ioctl DIR
 
 use clap::{Arg, ArgAction, Command, crate_version};
 use fuser::{

examples/passthrough.rs

@@ -1,6 +1,6 @@
 // This example requires fuse 7.40 or later. Run with:
 //
-//   cargo run --example passthrough --features abi-7-40 /tmp/foobar
+//   cargo run --example passthrough --features abi-7-40 DIR
 
 use clap::{Arg, ArgAction, Command, crate_version};
 use fuser::{

examples/simple.rs

@@ -5,8 +5,11 @@ use clap::{Arg, ArgAction, Command, crate_version};
 use fuser::consts::FOPEN_DIRECT_IO;
 #[cfg(feature = "abi-7-26")]
 use fuser::consts::FUSE_HANDLE_KILLPRIV;
-// #[cfg(feature = "abi-7-31")]
-// use fuser::consts::FUSE_WRITE_KILL_PRIV;
+/*
+// Note: see fn write().
+#[cfg(feature = "abi-7-31")]
+use fuser::consts::FUSE_WRITE_KILL_PRIV;
+*/
 use fuser::TimeOrNow::Now;
 use fuser::{
     FUSE_ROOT_ID, Filesystem, KernelConfig, MountOption, ReplyAttr, ReplyCreate, ReplyData,
@@ -188,6 +191,7 @@ fn system_time_from_time(secs: i64, nsecs: u32) -> SystemTime {
     }
 }
 
+// Time as i64: see fuse_abi::fuse_attr
 fn time_from_system_time(system_time: &SystemTime) -> (i64, u32) {
     // Convert to signed 64-bit time with epoch at 0
     match system_time.duration_since(UNIX_EPOCH) {
@@ -1438,7 +1442,7 @@ impl Filesystem for SimpleFS {
         offset: i64,
         data: &[u8],
         _write_flags: u32,
-        #[allow(unused_variables)] flags: i32,
+        _flags: i32,
         _lock_owner: Option<u64>,
         reply: ReplyWrite,
     ) {