glenux/fuse3.cr
1
0
Fork 0
Code Issues Projects 1 Releases Packages Wiki Activity
Crystal bindings for libfuse3.
50 commits 2 branches 0 tags 297 KiB
Find a file
Exact
Glenn Y. Rolland 2e06a136d3 docs: move runnable examples section from README to EXAMPLES.md 
Move the detailed “Examples” documentation out of `README.md` into a
dedicated `EXAMPLES.md` to keep the README focused and easier to scan.

* Added `EXAMPLES.md` containing the full runnable examples overview:
  * Notes on where examples live (`src/examples/`) and the recommended
    starting point (`simple_ro_fs.cr`).
  * Licensing note for sample code (MPL-2, with pointer to
    `src/examples/LICENSE`).
  * Sections for **Simple**, **RW**, **Passthrough**, **Tar** (with “How
    to try” commands), and **Ext2** (with “How to try” commands).
* Updated `README.md` “Examples” section to a single pointer: `See
  EXAMPLES.md`.

* Keeps `README.md` concise while still making example usage discoverable.
* Gives examples a stable, dedicated home where we can expand content
  without bloating the README.
2026-01-02 01:57:25 +01:00
scripts Add make targets and libfuse preflight check 2026-01-01 13:07:21 +01:00
spec api: introduce Fuse::FS::Base, Mount helper, and Types aliases; update docs/examples 2026-01-02 01:53:53 +01:00
src api: introduce Fuse::FS::Base, Mount helper, and Types aliases; update docs/examples 2026-01-02 01:53:53 +01:00
.drone.yml Add Linux CI for FUSE tests 2026-01-02 01:24:13 +01:00
.gitignore api: introduce Fuse::FS::Base, Mount helper, and Types aliases; update docs/examples 2026-01-02 01:53:53 +01:00
.travis.yml Initial commit 2017-01-05 20:33:07 +01:00
CONTRIBUTING.md api: introduce Fuse::FS::Base, Mount helper, and Types aliases; update docs/examples 2026-01-02 01:53:53 +01:00
EXAMPLES.md docs: move runnable examples section from README to EXAMPLES.md 2026-01-02 01:57:25 +01:00
LICENSE Initial commit 2017-01-05 20:33:07 +01:00
Makefile Document public API and add docs tooling 2026-01-02 01:24:13 +01:00
README.md docs: move runnable examples section from README to EXAMPLES.md 2026-01-02 01:57:25 +01:00
shard.yml Build and document new samples 2026-01-01 20:54:00 +01:00

README.md

fuse3.cr

Crystal bindings for libfuse3. This project started as a mirror of https://github.com/Papierkorb/fuse (libfuse era) and is now evolving into https://code.apps.glenux.net/glenux/fuse3.cr to track modern FUSE3 APIs.

Status

The bindings are usable for basic filesystem operations and samples, but the API surface is still being aligned with libfuse3. Expect some rough edges.

Requirements

  • Crystal (use a recent compiler compatible with this repo)
  • libfuse3 development and runtime packages
    • Debian/Ubuntu: libfuse3-dev
    • Fedora: fuse3-devel

Installation

Add this to your application's shard.yml:

dependencies:
  fuse:
    git: https://code.apps.glenux.net/glenux/fuse3.cr

Then install dependencies:

shards install

Examples

See EXAMPLES.md.

Usage

To build the examples:

make

Mount Options and Capabilities

This binding follows libfuse3 behavior. Common options and patterns:

  • -f runs in the foreground (recommended for debugging).
  • -d enables debug logging to stderr.
  • -s forces single-threaded operation.
  • -o default_permissions lets the kernel enforce POSIX permissions and skips the userspace access callback.
  • -o allow_other exposes the mount to other users (requires user_allow_other in /etc/fuse.conf).
  • -o fsname=NAME sets the filesystem name shown by tools like mount.
  • -o subtype=NAME sets the FUSE subtype (visible in /proc/mounts).
  • -o ro mounts read-only (samples that already enforce RO still accept it).

Capabilities exposed via the API depend on the filesystem implementation:

  • Fuse::FS::Base#access is used unless -o default_permissions is set.
  • Fuse::FS::Base#readdir + #opendir can enable readdir caching via fi.cache_readdir = true.
  • Fuse::FS::Base#open can set fi.keep_cache = true to avoid cache drops.

To run the simple example in the foreground (recommended for debugging):

mkdir -p ~/mnt/test
./bin/simple_ro_fs -f -d ~/mnt/test

The sample implements access. If you pass -o default_permissions, the kernel performs permission checks and skips the userspace access callback.

To unmount (prefers fusermount3 if installed):

fusermount3 -u ~/mnt/test || fusermount -u ~/mnt/test

If the mount hangs, check it with mountpoint -q and retry unmount:

mountpoint -q ~/mnt/test && fusermount3 -u ~/mnt/test || fusermount -u ~/mnt/test

Testing

The spec suite exercises the sample binaries. The tar and ext2 integration specs require fixture files; generate them before running tests:

spec/scripts/build-tar-fixture.sh
spec/scripts/build-ext2-fixture.sh

If a fixture is missing, the corresponding spec will fail with a message reminding you to run the script.

You can also use the shell scripts under spec/scripts/ to exercise common operations against a mounted filesystem:

spec/scripts.sh ~/mnt/test

Documentation

Generate the API documentation with:

crystal docs

The output is written under docs/.

Public API namespaces

New aliases are provided for clarity while keeping existing APIs:

  • Fuse::FS::Base is the filesystem base class.
  • Fuse::FS::Mount.run(fs) wraps fs.run!.
  • Fuse::Types re-exports ABI structs/enums from Fuse::Binding.

Contributing

License

MIT (see LICENSE).

Credits

  • Glenn Y. Rolland (@glenux), current developer/maintainer
  • Stefan Merettig (@Papierkorb), original project and early bindings