Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/bcle/fuse4js

FUSE bindings for Javascript and node.js
https://github.com/bcle/fuse4js

Last synced: about 1 month ago
JSON representation

FUSE bindings for Javascript and node.js

Awesome Lists containing this project

README 

        
Fuse4js

=======



Fuse4js provides Javascript bindings to the [FUSE](http://fuse.sourceforge.net/) subsystem of Linux. It enables you to develop user-space file systems with node.js.



Requirements

------------

Linux:

* Fuse4js has been tested on Ubuntu 10.04, Ubuntu 12.04  and CentOS 5.x (all 32-bit).

* GNU Compiler toolchain, including gcc and g++

    * On Ubuntu: `sudo apt-get install g++`

* FUSE library and header files.

    * On Ubuntu: `sudo apt-get install libfuse-dev`

    * On CentOS / RedHat: `yum install fuse-devel`

* pkg-config tool (typically included out-of-the-box with the OS)

* node.js 0.8.7 or later



OSX:

* install [osxfuse](http://osxfuse.github.com/)



Tutorial

--------



This tutorial explains how to install and use fuse4js.



* Ensure your system meets the software requirements listed above.

* Create a /tmp/tutorial directory.

* cd to the directory you created.

* Create a mnt/ subdirectory. It will be used as the mount point for testing FUSE file systems.

* Download the fuse4js/ source directory:

`git clone git://github.com/vmware/fuse4js.git`

* Compile the source code to create the fuse4js add-on in a local node_modules/ subdirectory:  

`npm install fuse4js`

* Run the sample jsonFS file system:  

`node fuse4js/example/jsonFS.js fuse4js/example/sample.json /tmp/tutorial/mnt`  

This mounts the JSON file as a file system. In a another shell, you can browse and make changes to the file system under /tmp/tutorial/mnt. You can view, edit, create, and move files and directories.

* To dismount, make sure no processes remain under the file system path, and then type:

`fusermount -u /tmp/tutorial/mnt`

* Changes to the file system are discarded. If you want to save the modified data to a new JSON file, add the `-o outputJsonFilePath` option when starting the program.



Once you are comfortable with the sample program, you can move on to the second example, *mirrorFS.js*. It is equivalent to the fusexmp.c sample program that ships with the FUSE source code. As its name indicates, it maps an existing file system subtree to a mount point of your choice. It demonstrates more advanced features such as file handles. The syntax is:

`node fuse4js/example/mirrorFS.js  `



Global installation

-------------------

The tutorial used a local installation of fuse4js that is private to the /tmp/tutorial directory. To install fuse4js globally on your system:



* Log in as root, or use sudo

* Download the source code into a `fuse4js/` subdirectory

* Install by typing: `npm install -g --unsafe-perm fuse4js`  

The `--unsafe-perm` option seems to be necessary to work around an interference between the node-gyp compilation process and npm's downgrading of permissions when running a package's installation script (you may get an EACCES error without it)

* At this point, the add-on should be installed under `/usr/local/lib/node_modules`. To use it in your programs using a statement such as `fuse4js = require("fuse4js")`, include `/usr/local/lib/node_modules` in your NODE_PATH environment variable. By default, node.js doesn't look in there for some reason, despite the fact that npm uses that directory as the default global installation location. Example:

`export NODE_PATH=/usr/local/lib/node_modules`



Installation from NPM registry

-------------------

As of September 17, 2012, fuse4js has been added to the NPM registry, so you can skip the git download step and install it directly by typing:  

`npm install fuse4js`  

This will put the module under a local node_modules/ subdirectory.



API Documentation

----------------- 

Fuse4js currently implements a subset of all FUSE file operations. More will be added over time, but the initial set is sufficient to implement a basic read/write file system.



You implement a file system by registering Javascript handler functions with fuse4js. Each handler handles a particular FUSE operation. While the arguments passed to a handler vary depending on the requested operation, the last argument is always a callback function that you invoke when you are finished servicing the request. The arguments to the callback typically include an error code, followed by zero or more additional arguments depending on the FUSE operation. Following FUSE conventions, the error code is set to a negated 'errno' value to indicate error, and zero or a positive value (for read/write operations) to indicate success.



We currently don't have a separate document describing the Javascript interface corresponding to each FUSE operation. Instead, the API is documented in the comments for each handler in the `mirrorFS.js` sample program, so use that as the reference for now.



How it Works

------------

The FUSE event loop runs in its own thread, and communicates with the node.js main thread using an RPC mechanism based on a libuv async object and a semaphore. There are a couple of context switches per FUSE system call. Read/Write operations also involve a copy operation via a node.js Buffer object.



ToDo List

---------

* Automated tests

* Support for more FUSE operations, such as hard link management.

* Improve performance (try to reduce context switches and copy operations)



License

-------

Fuse4js is released under the terms of the MIT license. See the LICENSE.txt file for details.



Contributing

------------

If you wish to submit code changes to this repository, please request a contribution agreement form from the maintainer (VMware legal requires it).



Contact

-------

Feel free to send bug reports and constructive feedback to the maintainer: [email protected]