Cross-platform FUSE library for Go - Works on macOS, FreeBSD, NetBSD, OpenBSD, Linux, Windows
Switch branches/tags
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.

README.md

Cross-platform FUSE library for Go

CircleCI GoDoc

Cgofuse is a cross-platform FUSE library for Go. It is supported on multiple platforms and can be ported to any platform that has a FUSE implementation. It has cgo and !cgo ("nocgo") variants depending on the platform.

macOS
Travis CI
FreeBSD
PMCI
NetBSD
PMCI
OpenBSD
no CI
Linux
Travis CI
Windows
AppVeyor
cgo ✔️ ✔️1 ✔️2 ✔️2 ✔️ ✔️
!cgo ✔️1
  • 1: Requires Go 1.11.
  • 2: NetBSD and OpenBSD support is experimental. There are known issues that stem from the differences in the NetBSD librefuse and OpenBSD libfuse implementations from the reference libfuse implementation.
    • NetBSD and OpenBSD: Option parsing may fail because the fuse_opt_parse function is not fully compatible with the one in libfuse.
    • OpenBSD only: Signal handling is broken due to a bug in the OpenBSD implementation of fuse_set_signal_handlers.

How to build

macOS

FreeBSD

  • Prerequisites: fusefs-libs
  • Build:
    $ cd cgofuse
    $ go install -v ./fuse ./examples/memfs ./examples/passthrough
    
    # You may also need the following in order to run FUSE file systems.
    # Commands must be run as root.
    $ vi /boot/loader.conf                      # add: fuse_load="YES"
    $ sysctl vfs.usermount=1                    # allow user mounts
    $ pw usermod USERNAME -G operator           # allow user to open /dev/fuse
    

NetBSD

  • Prerequisites: NONE
  • Build:
    $ cd cgofuse
    $ go install -v ./fuse ./examples/memfs ./examples/passthrough
    
    # You may also need the following in order to run FUSE file systems.
    # Commands must be run as root.
    $ chmod go+rw /dev/puffs
    $ sysctl -w vfs.generic.usermount=1
    

OpenBSD

  • Prerequisites: NONE
  • Build:
    $ cd cgofuse
    $ go install -v ./fuse ./examples/memfs ./examples/passthrough
    
  • NOTE: OpenBSD 6 removed the kern.usermount option, which allowed non-root users to mount file systems [link]. Therefore you must be root in order to use FUSE and cgofuse.

Linux

  • Prerequisites: libfuse-dev, gcc
  • Build:
    $ cd cgofuse
    $ go install -v ./fuse ./examples/memfs ./examples/passthrough
    

Windows cgo

  • Prerequisites: WinFsp, gcc (e.g. from Mingw-builds)
  • Build:
    > cd cgofuse
    > set CPATH=C:\Program Files (x86)\WinFsp\inc\fuse
    > go install -v ./fuse ./examples/memfs
    

Windows !cgo

  • Prerequisites: WinFsp
  • Build:
    > cd cgofuse
    > set CGO_ENABLED=0
    > go install -v ./fuse ./examples/memfs
    

How to cross-compile your project using xgo

You can easily cross-compile your project using xgo and the billziss/xgo-cgofuse docker image.

  • Prerequisites: docker, xgo
  • Build:
    $ docker pull billziss/xgo-cgofuse
    $ go get -u github.com/karalabe/xgo
    $ cd YOUR-PROJECT-THAT-USES-CGOFUSE
    $ xgo --image=billziss/xgo-cgofuse \
        --targets=darwin/386,darwin/amd64,linux/386,linux/amd64,windows/386,windows/amd64 .
    

Cross-compilation only works for macOS, Linux and Windows.

How to use

User mode file systems are expected to implement fuse.FileSystemInterface. To make implementation simpler a file system can embed ("inherit") a fuse.FileSystemBase which provides default implementations for all operations. To mount a file system one must instantiate a fuse.FileSystemHost using fuse.NewFileSystemHost.

The full documentation is available at GoDoc.org: package fuse

There are currently three example file systems:

  • Hellofs is an extremely simple file system. Runs on all OS'es.
  • Memfs is an in memory file system. Runs on all OS'es.
  • Passthrough is a file system that passes all operations to the underlying file system. Runs on all OS'es except Windows.

How it is tested

Cgofuse is regularly built and tested on Travis CI, Poor Man's CI and AppVeyor. The following software is being used to test cgofuse.

macOS

FreeBSD

Linux

Windows (cgo and !cgo)

Contributors

  • Bill Zissimopoulos <billziss at navimatics.com>
  • Nick Craig-Wood <nick at craig-wood.com>