add basic build.zig.zon documentation

doc/build.zig.zon.md

@@ -0,0 +1,65 @@
+# build.zig.zon Documentation
+
+This is the manifest file for build.zig scripts. It is named build.zig.zon in
+order to make it clear that it is metadata specifically pertaining to
+build.zig.
+
+- **build root** - the directory that contains `build.zig`
+
+## Top-Level Fields
+
+### `name`
+
+String. Required.
+
+### `version`
+
+String. Required.
+
+[semver](https://semver.org/)
+
+### `dependencies`
+
+Struct.
+
+Each dependency must either provide a `url` and `hash`, or a `path`.
+
+#### `url`
+
+String. 
+
+When updating this field to a new URL, be sure to delete the corresponding
+`hash`, otherwise you are communicating that you expect to find the old hash at
+the new URL.
+
+#### `hash`
+
+String. 
+
+[multihash](https://multiformats.io/multihash/)
+
+This is computed from the file contents of the directory of files that is
+obtained after fetching `url` and applying the inclusion rules given by
+`paths`.
+
+This field is the source of truth; packages do not come from an `url`; they
+come from a `hash`. `url` is just one of many possible mirrors for how to
+obtain a package matching this `hash`.
+
+#### `path`
+
+String.
+
+When this is provided, the package is found in a directory relative to the
+build root. In this case the package's hash is irrelevant and therefore not
+computed.
+
+### `paths`
+
+List. Required.
+
+Specifies the set of files and directories that are included in this package.
+Paths are relative to the build root. Use the empty string (`""`) to refer to
+the build root itself.
+
+Only files included in the package are used to compute a package's `hash`.