ref: 7e63a4bdcc41ca93bc1d203c8d15de913bb09f22
parent: 74dc57b5fcfa1c98de646674040741f543d358ec
author: sirjofri <sirjofri@sirjofri.de>
date: Tue Dec 16 16:53:49 EST 2025
adds readme
--- /dev/null
+++ b/README
@@ -1,0 +1,84 @@
+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.
--
⑨