mirage / mirage-fs

Filesystem and block libraries for Mirage

mirage-fs — MirageOS signatures for filesystem devices

mirage-fs provides the [Mirage_fs.S][fs] signature the MirageOS filesystem devices should implement.

Installation

mirage-fs can be installed with opam:

opam install mirage-fs

If you don't use opam consult the opam file for build instructions.

Documentation

The documentation and API reference is generated from the source interfaces. It can be consulted online or via odig doc mirage-fs.

License

mirage-fs is distributed under the ISC license, see the LICENSE.md file for its text.

mirage-fs's Issues

API discussion

I looked through the API (various points apply as well for mirage-kv, which imho mirage-fs should extend, rather than having similar functions defined multiple times (such as read / mem / size / error), and have various thoughts (I can see some room for improvement):

1. path is currently a string, which basically means each implementation needs to do with normalisation on their own. we should consider to use Fpath.t from https://github.com/dbuenzli/fpath
2. the page aligned bits are imho not necessary here
3. read requires both offset and length, which should be optional (and int64, as done in mirage-kv)
4. read also returns a Cstruct.t list, which should be a Cstruct.t
5. provide readv and writev for Cstruct.t list
6. write requires an offset atm, should be optional
7. semantics of write: add padding bytes if writing at some offset? maybe some options such as append and truncate will be useful?
8. error semantics (and specification): e.g. fail hard in read if specified offset and length are inappropriate (-1 or bigger than file), specify which errors are to be returned in which cases
9. remove create, it's the same as write with Cstruct.empty

maybe it would be worth to specify a nice interface for the user, and then another one which implementations needs to satisfy. the bounds checks and other common code could then be implemented within this library, rather than in each implementation.

---

What do you think? And who is maintaining any implementations of this interface? mirage-fs-unix and fat-filesystem come to mind, git-mirage as well.

Beware of String.escape

crunch.ml uses String.escape to write the binary content of a string to an OCaml constant. One should note that String.escape writes latin1 characters as is so you really have to make sure the resulting text files are never converted to another encoding.

I just lost time with similar code on my side because I was caught by a spurious UTF-8 translation made by my editor --- I embedded the file with the constant in another one that had UTF-8 characters via M-x insert-file so the inserted constant was translated to UTF-8 thus breaking the binary sequence.

On my side I now prefer to stick to a more robust US-ASCII encoding with something like:

Printf.printf "\"";
for i = 0 to String.length s - 1 do 
  Printf.printf "\\x%02X" (Char.code s.[i])
done;
Printf.printf "\""