shithub: fsgen

Clone

Last commit

adds example note to readme

About

fsgen - Plan 9 Filesystem Generator

This is a generator program that generates filesystem code based on a descriptive code file.
Its goal is to make it easy to write generic filesystems (read: not using 9pfile) that are
dynamic ("variables") and can be easily embedded into any program. The generated filesystems
should also have not many external dependencies.

- The generated filesystem code is a simple C file that can be compiled.
- The filesystem Srv* can be fetched by calling the getfs_...(void) function, with ... being
  the name of the description file.
- The generated code has #line directives to simplify debugging.
- Focus on your functionality, not boilerplate code.

NOTE: All commands in the description file must start at the first character of the line!
This applies to file routes '/', the handler functions 'r{' etc., comments, and everything
else. Blank lines /^$/ are ignored, except they are in a part that should be copied verbatim.


VARIABLES

Variables are transported to the filesystem code as char* strings. Their name is defined in
the path for each file route in curly braces {, }.


FILE ROUTE

Each file route is a named file that can be accessed in the filesystem hierarchy. Each route
has its own set of functions that reflect the standard filesystem operations. Instead of
writing one fsread function and doing the routing yourself, you write the read function for
your route, using variables and the standard Req*.

   void read(Req *r) → r{, but with variables.

Simple example:

   /path/{to}/my/{file}
   r{
      /* something */
      respond(r, nil);
   r}

is equivalent to a function like this, exclusive for a file accessed at /path/to/my/file:

   void read(Req *r, char *to, char *file)
   {
      /* something */
      respond(r, nil);
   }

File routes have to start with a / character, which is the root of the mountpoint.


HANDLER FUNCTIONS

Right now, the following handler functions are available:

- read: r{
- write: w{
- stat: s{
- read directory entry: ls{

While read, write, stat are easy to understand, ls is equivalent to a Dirgen function you
would usually give to dirread9p, however it receives the same variables as the other
functions.

All functions that get a Req* passed are supposed to respond to it, if they want.

The body of the handler functions is copied verbatim.


VERBATIM CODE

It is possible to inject custom code at any point in the description file, using the %{
%} pair. This can be used to add additional includes, for example.

   %{
   #include "dat.h"
   #include "fns.h"
   %}


COMMENTS

For now, comments can be written by starting the line with a # character.


EXAMPLE

The folder 'test' contains a fully working example. After building the program using 'mk',
you can just change into that directory and run 'mk' there.