rclone/xgo-cgofuse repository overview

⁠Cross-platform FUSE library for Go

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.

• 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

• Prerequisites: FUSE for macOS⁠, command line tools⁠
• Build:

  $ cd cgofuse
  $ go install -v ./fuse ./examples/memfs ./examples/passthrough
  

  Copy

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
  

  Copy

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
  

  Copy

OpenBSD

• Prerequisites: NONE
• Build:

  $ cd cgofuse
  $ go install -v ./fuse ./examples/memfs ./examples/passthrough
  

  Copy
• 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
  

  Copy

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
  

  Copy

Windows !cgo

• Prerequisites: WinFsp⁠
• Build:

  > cd cgofuse
  > set CGO_ENABLED=0
  > go install -v ./fuse ./examples/memfs
  

  Copy

⁠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 .
  

  Copy

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

• fstest⁠
• fsx⁠

FreeBSD

• fsx⁠

Linux

• fstest⁠
• fsx⁠

Windows (cgo and !cgo)

• winfsp-tests⁠
• fsx⁠

⁠Contributors

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