= The Zilch Virtual Filesystem
:page-pagination:

In many places, it's necessary to build up a structure of files and
directories. These structures are a subset of e.g. a project's source code. To
make these, Zilch has a `vfs` record.

Core Zilch can create a VFS from two sources: an on-disk directory, as well as
a Nix store path:

[,scheme,line-comment=;]
----
(vfs-from-directory "/home/puck/example")
;; #<zilch.vfs#<vfs>>

(define example-vfs
 (vfs-from-store
  (zdir "zero" (zsymlink "/dev/zero")))
;; #<zilch.vfs#<vfs>>
----

These VFSes can be read out using `vfs-contents`:

[,scheme,line-comment=;]
----
(mapping->alist
 (vfs-contents example-vfs))
;; ((("" . "zero")
;;   . #<z-symlink -> "/dev/zero">))
----

VFS records store their contents as an SRFI 146 mapping, with a pair
`(dir . name)` as key, and the store path (or zexpr) to point at as its value.
Directories are indicated by the directory itself having a `'directory` symbol
as contents; these markers are used during serialization.

`(zilch vfs)` contains a series of helpers to make standard changes to the
filesystem; such as filtering, and reading subtrees.

== Serializing virtual filesystems to the store

When a virtual filesystem is written to the store using `vfs-to-store`, a
xref:generated:zilch.file.adoc[`(zilch file)`]-based structure is created,
which can then be ``zexp-unquote``d safely inside a `zexp`. An important caveat
to this, however, is that the created structure uses symlinks to every file in
the vfs, rather than copying. This is chosen to both limit the expense of
copying the contents of a large file to the store when many VFSes contain it,
and a logistical limitation in the way Zilch interacts with Nix. It's possible
this restriction will be lifted in the future.

== Language-specific

Zilch's Go support has a special handler that can create a VFS from a `go.sum`
line. See the xref:go/library.adoc#vfs[Go] documentation for this procedure.