Repository files navigation

fuse-rs is aRust library crate for easy implementation ofFUSE filesystems in userspace.

fuse-rs does not just provide bindings, it is a rewrite of the original FUSE C library to fully take advantage of Rust's architecture.

Crate documentation

A working FUSE filesystem consists of three parts:

1. Thekernel driver that registers as a filesystem and forwards operations into a communication channel to a userspace process that handles them.
2. Theuserspace library (libfuse) that helps the userspace process to establish and run communication with the kernel driver.
3. Theuserspace implementation 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-rs 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.

Except for a single setup (mount) function call and a final teardown (unmount) function call to libfuse, everything runs in Rust.

FUSE must be installed to build or run programs that use fuse-rs (i.e. kernel driver and libraries. Some platforms may also require userland utils likefusermount). A default installation of FUSE is usually sufficient.

To build fuse-rs or any program that depends on it,pkg-config needs to be installed as well.

FUSE for Linux is available in most Linux distributions and usually calledfuse. To install on a Debian based system:

sudo apt-get install fuse

Install on CentOS:

sudo yum install fuse

To build, FUSE libraries and headers are required. The package is usually calledlibfuse-dev orfuse-devel. Alsopkg-config is required for locating libraries and headers.

sudo apt-get install libfuse-dev pkg-config

sudo yum install fuse-devel pkgconfig

Installer packages can be downloaded from theFUSE for macOS homepage.

To install usingHomebrew:

brew cask install osxfuse

To installpkg-config (required for building only):

brew install pkg-config

Install packagesfusefs-libs andpkgconf.

pkg install fusefs-libs pkgconf

Put this in yourCargo.toml:

[dependencies]fuse ="0.4"

To create a new filesystem, implement the traitfuse::Filesystem. See thedocumentation for details or theexamples directory for some basic examples.

There's still a lot of stuff to be done. Feel free to contribute. See thelist of issues on GitHub and search the source files for comments containing "TODO" or "FIXME" to see what's still missing.

Developed and tested on macOS. Tested underLinux,macOS andFreeBSD using stable, beta and nightlyRust versions (seeCI for details).

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 theChangelog if your changes are relevant to the users.