README

   1 Fuse perl bindings
   2 ==================
   3
   4 Fuse is combination of Linux kernel module and user space library which
   5 enables you to write user-space filesystems. This module enables you to
   6 write filesystems using perl.
   7
   8 Additional file-systems using Fuse module are released on CPAN using Fuse::
   9 namespace. Currently that includes only Fuse::DBI which allows you to mount
  10 database as file system, but there will be more.
  11
  12 This is a pre-production release.  It seems to work quite well.  In fact, I
  13 can't find any problems with it whatsoever.  If you do, I want to know.
  14
  15 INSTALLATION
  16
  17 To install this module type the standard commands as root:
  18
  19    perl Makefile.PL
  20    make
  21    make test
  22    make install
  23
  24
  25 DEPENDENCIES
  26
  27 This module requires the FUSE C library and the FUSE kernel module.
  28 See http://fuse.sourceforge.net/
  29
  30 If you intend to use FUSE in threaded mode, you need a version of Perl which
  31 has been compiled with USE_ITHREADS.  Then, you need to use threads and
  32 threads::shared.
  33
  34
  35 COPYRIGHT AND LICENCE
  36
  37 This is contributed to the FUSE project by Mark Glines <mark@glines.org>,
  38 and is therefore subject to the same license and copyright as FUSE itself.
  39 Please see the AUTHORS and COPYING files from the FUSE distribution for
  40 more information.
  41
  42
  43 EXAMPLES
  44
  45 There are a few example scripts.  You can find them in the examples/
  46 subdirectory.  These are:
  47
  48 * example.pl, a simple "Hello world" type of script
  49
  50 * loopback.pl, a filesystem loopback-device.  like fusexmp from
  51                the main FUSE dist, it simply recurses file operations
  52                into the real filesystem.  Unlike fusexmp, it only
  53                re-shares files under the /tmp/test directory.
  54
  55 * rmount.pl, an NFS-workalike which tunnels through SSH.  It requires
  56              an account on some ssh server (obviously), with public-key
  57              authentication enabled.  (if you have to type in a password,
  58              you don't have this.  man ssh_keygen.).  Copy rmount_remote.pl
  59              to your home directory on the remote machine, and create a
  60              subdir somewhere, and then run it like:
  61              ./rmount.pl host /remote/dir /local/dir
  62
  63 * rmount_remote.pl, a ripoff of loopback.pl meant to be used as a backend
  64                     for rmount.pl.
  65
  66
  67 BUGS
  68
  69 At time of writing, Perl (5.8.7) did not support shared subroutine references.
  70 Symptoms include a cryptic error message like "Invalid value for shared scalar"
  71 from Fuse.pm.  Until this is fixed, if you use threaded mode, you need to use
  72 symbolic references (i.e. passing "main::cb" instead of \&cb).  This doesn't
  73 allow things like closures, lexical subs and that sort of thing, but it does
  74 work for me.
  75
  76 The current test framework seems to work well, but the underlying mount/
  77 unmount infrastructure is a crock.  I am not pleased with that code.
  78
  79 While most things work, I do still have a TODO list:
  80 * need to sort out cleaner mount semantics for the test framework
  81 * determine why getattr() test on OS X/Darwin is very slow; succeeds, but
  82   very slowly
  83
  84 Currently tests have been attempted and succeeded on:
  85   * Ubuntu 10.10/amd64
  86   * Ubuntu 11.04/amd64
  87   * Debian 5.0/powerpc
  88   * CentOS 5.6/amd64
  89   * NetBSD 5.1/i386
  90   * NetBSD 5.1/amd64
  91   * FreeBSD 8.2/i386
  92   * FreeBSD 8.2/amd64
  93   * MacOS X 10.6.7
  94
  95 Note that on NetBSD, there are several bugs in libpuffs and librefuse
  96 which prevent some tests from succeeding. There are fixes in NetBSD's
  97 MAIN branch, specifically revisions 1.26 and 1.27 on src/lib/libpuffs/subr.c,
  98 which correct the issues that cause the test failures. However, there is
  99 still a bug in librefuse that causes readdir() to only be called once.
 100 We will be addressing this with the appropriate developers in the near
 101 future.
 102
 103 Also note that on NetBSD and FreeBSD, extended attributes do not work. These
 104 are specifics related to the FUSE implementations on those platforms.