doc/packages/fuse.section.md

   1 # FUSE {#sec-fuse}
   2
   3 Some packages rely on
   4 [FUSE](https://www.kernel.org/doc/html/latest/filesystems/fuse.html) to provide
   5 support for additional filesystems not supported by the kernel.
   6
   7 In general, FUSE software are primarily developed for Linux but many of them can
   8 also run on macOS. Nixpkgs supports FUSE packages on macOS, but it requires
   9 [macFUSE](https://osxfuse.github.io) to be installed outside of Nix. macFUSE
  10 currently isn't packaged in Nixpkgs mainly because it includes a kernel
  11 extension, which isn't supported by Nix outside of NixOS.
  12
  13 If a package fails to run on macOS with an error message similar to the
  14 following, it's a likely sign that you need to have macFUSE installed.
  15
  16     dyld: Library not loaded: /usr/local/lib/libfuse.2.dylib
  17     Referenced from: /nix/store/w8bi72bssv0bnxhwfw3xr1mvn7myf37x-sshfs-fuse-2.10/bin/sshfs
  18     Reason: image not found
  19     [1]    92299 abort      /nix/store/w8bi72bssv0bnxhwfw3xr1mvn7myf37x-sshfs-fuse-2.10/bin/sshfs
  20
  21 Package maintainers may often encounter the following error when building FUSE
  22 packages on macOS:
  23
  24     checking for fuse.h... no
  25     configure: error: No fuse.h found.
  26
  27 This happens on autoconf based projects that use `AC_CHECK_HEADERS` or
  28 `AC_CHECK_LIBS` to detect libfuse, and will occur even when the `fuse` package
  29 is included in `buildInputs`. It happens because libfuse headers throw an error
  30 on macOS if the `FUSE_USE_VERSION` macro is undefined. Many projects do define
  31 `FUSE_USE_VERSION`, but only inside C source files. This results in the above
  32 error at configure time because the configure script would attempt to compile
  33 sample FUSE programs without defining `FUSE_USE_VERSION`.
  34
  35 There are two possible solutions for this problem in Nixpkgs:
  36
  37 1. Pass `FUSE_USE_VERSION` to the configure script by adding
  38    `CFLAGS=-DFUSE_USE_VERSION=25` in `configureFlags`. The actual value would
  39    have to match the definition used in the upstream source code.
  40 2. Remove `AC_CHECK_HEADERS` / `AC_CHECK_LIBS` for libfuse.
  41
  42 However, a better solution might be to fix the build script upstream to use
  43 `PKG_CHECK_MODULES` instead. This approach wouldn't suffer from the problem that
  44 `AC_CHECK_HEADERS`/`AC_CHECK_LIBS` has at the price of introducing a dependency
  45 on pkg-config.