package fuse3

  1. Overview
  2. Docs

fuse3

fuse3 provides OCaml bindings for libfuse 3. It lets OCaml programs implement high-level FUSE filesystems while using Bigarray-backed buffers for read and write callbacks.

The public Dune and opam package is fuse3. The OCaml module remains Fuse.

Requirements

  • Linux
  • libfuse >= 3.10.0
  • pkg-config
  • OCaml >= 4.08.0
  • camlidl
  • Dune >= 3.7

On Debian and Ubuntu, install the FUSE development package with:

sudo apt install libfuse3-dev

Installation

The recommended installation path is opam:

opam install fuse3

For local development:

make
make install

To uninstall a local installation:

make uninstall

Building And Testing

Build the library and install metadata:

make

Build the examples:

make example

Run the unit and compile checks:

make test

Run the mounted smoke test:

make e2e-smoke-test

Run the full mounted end-to-end suite:

make e2e

Run the full mounted end-to-end suite in explicit single-threaded mode:

make e2e-single-threaded

Run the full mounted end-to-end suite in explicit multithreaded mode:

make e2e-multithreaded

The mounted tests require Linux, /dev/fuse access, and permission to mount FUSE filesystems. When FUSE access is unavailable, mounted e2e targets print SKIP and exit successfully. Set OCAMLFUSE_E2E_REQUIRE_FUSE=1 to make missing FUSE support a failure.

Examples

The examples are in example/:

  • hello.ml: a minimal read-only filesystem.
  • fusexmp.ml: a passthrough-style filesystem.

After make example, the executables are under _build/default/example/.

Example:

mkdir -p /tmp/fuse3-mnt
_build/default/example/hello.exe /tmp/fuse3-mnt -f -s

Unmount the filesystem from another shell when finished:

fusermount3 -u /tmp/fuse3-mnt

Some systems still provide the unmount command as fusermount.

API Notes

New code should use the native Fuse API. The native operation record exposes FUSE 3 concepts such as:

  • file_info values on callbacks that receive FUSE file information;
  • file_info_update results from fopen and opendir;
  • int64 file handles;
  • rename flags;
  • readdir flags and dir_entry values;
  • nanosecond utimens timestamps, including Now and Omit sentinels.

Fuse.Fuse_compat provides the old operation record shape as an upgrade aid. It runs on top of the FUSE 3 implementation, but it cannot represent every FUSE 3 feature. In particular, compatibility callbacks ignore new file-info parameters, reject unsupported rename flags with EINVAL, reject timestamp sentinels that old utime callbacks cannot represent, and convert file handles back to int with overflow checks.

The default FUSE loop uses libfuse's multithreaded loop. In that mode, libfuse owns worker threads and the binding registers those threads with the OCaml runtime before invoking OCaml callbacks. Users who need single-threaded execution can pass ~loop_mode:Single_threaded; FUSE -s also forces the single-threaded path.

Documentation

  • docs/bindings.md: binding architecture and maintenance notes.
  • docs/release-notes.md: release notes for the FUSE 3 package.
  • docs/plans/archived/fuse3/: completed FUSE 3 migration planning history.

History

This repository descends from the original OCamlFuse project hosted on SourceForge. It keeps the original GPL-licensed binding lineage while updating the build, package metadata, tests, and runtime integration for libfuse 3.

Original project page: https://sourceforge.net/projects/ocamlfuse/