virtualfs_fuse

FUSE adapter for virtualfs: expose a VirtualFs::Vfs merged tree, regular directories, .vpak archives, remote mounts — as a real directory in the host OS.

Backends per platform:

Installation

dependencies:
  virtualfs_fuse:
    github: naqvis/virtualfs_fuse

shards install

Usage

require "virtualfs_fuse"

vfs = VirtualFs::Vfs.new
vfs.mount("game.vpak", "/", priority: 0)          # archive
vfs.mount("/path/to/dir", "/", priority: 10)     # overlaid patches
vfs.mount_watch("/path/to/dir", "/")             # live-reloaded overlay

VirtualFs::Fuse.mount(vfs, "/mnt/game", read_only: true)

Fuse.mount blocks until the filesystem is unmounted. Options: read_only: (default true), allow_other: (POSIX only), foreground:.

• POSIX: unmount with umount /mnt/game or Ctrl-C.
• Windows: mountpoint is a drive letter ("Z:") or a directory; unmount via Explorer eject / net use Z: /delete.

Only one mount per process; the mount runs single-threaded, so the underlying Vfs does not need to be thread-safe.

CLI / example

shards install
crystal run examples/mount.cr -- game.vpak /mnt/game
shards build --release

The CLI doubles as a FUSE mount helper: it accepts <source> <mountpoint> [-o ro,rw,allow_other,...] and unwraps fstab-style vfs_mount#/path sources. -f does a dry run, --help/-V print usage/version.

On Windows, build against the WinFsp SDK and run with a drive letter or directory mount point. The shard calls WinFsp's bundled FUSE 2.8 layer from winfsp-x64.lib / winfsp-a64.lib; it does not maintain a second native callback implementation:

shards build --release
bin\vfs_mount.exe game.vpak Z:

Mounting with the system mount command (Linux)

A FUSE filesystem is a userspace daemon, so the "plugin" is an executable the system mount invokes — no kernel module. Two ways to use the standard tools:

Via the generic libfuse helper (no extra files; vfs_mount just needs to be in PATH, e.g. /usr/local/bin):

mount -t fuse.vfs_mount game.vpak /mnt/game -o ro,allow_other
umount /mnt/game

Via a dedicated mount.vfs helper for the shorter type name:

install -m 755 examples/mount.vfs /usr/local/sbin/mount.vfs
mount -t vfs game.vpak /mnt/game -o ro

fstab (mounts at boot or with mount /mnt/game):

vfs_mount#/path/game.vpak  /mnt/game  fuse  ro,allow_other  0 0

Notes:

• allow_other as a non-root user requires user_allow_other in /etc/fuse.conf; root works without it.
• ro (the default here) makes the mount read-only; rw allows write attempts, which still fail unless the Vfs has a writable backing store configured (vfs.write_dir=).
• This model is Linux-specific. On macOS, run vfs_mount directly (no mount.<type> helpers exist); on Windows, WinFsp has its own launcher/service model.

License

MIT — see LICENSE.

Contributing

1. Fork it (https://github.com/naqvis/virtualfs_fuse/fork)
2. Create your feature branch (git checkout -b my-new-feature)
3. Commit your changes (git commit -am 'Add some feature')
4. Push to the branch (git push origin my-new-feature)
5. Create a new Pull Request

Contributors

• Ali Naqvi - creator and maintainer