1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
|
# 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`
Enum literal. Required.
This is the default name used by packages depending on this one. For example,
when a user runs `zig fetch --save <url>`, this field is used as the key in the
`dependencies` table. Although the user can choose a different name, most users
will stick with this provided value.
It is redundant to include "zig" in this name because it is already within the
Zig package namespace.
Must be a valid bare Zig identifier (don't `@` me), limited to 32 bytes.
Together with `fingerprint`, this represents a globally unique package identifier.
### `fingerprint`
Together with `name`, this represents a globally unique package identifier. This
field is auto-initialized by the toolchain when the package is first created,
and then *never changes*. This allows Zig to unambiguously detect when one
package is an updated version of another.
When forking a Zig project, this fingerprint should be regenerated if the upstream
project is still maintained. Otherwise, the fork is *hostile*, attempting to
take control over the original project's identity. The fingerprint can be regenerated
by deleting the field and running `zig build`.
This 64-bit integer is the combination of a 32-bit id component and a 32-bit
checksum.
The id component within the fingerprint has these restrictions:
`0x00000000` is reserved for legacy packages.
`0xffffffff` is reserved to represent "naked" packages.
The checksum is computed from `name` and serves to protect Zig users from
accidental id collisions.
### `version`
String. Required.
[semver](https://semver.org/)
Limited to 32 bytes.
### `minimum_zig_version`
String. Optional.
[semver](https://semver.org/)
This is currently advisory only; the compiler does not yet do anything
with this version.
### `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. If the contents of a URL change this will result in a hash mismatch
which will prevent zig from using it.
#### `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 a `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. This field and `url` are mutually exclusive.
#### `lazy`
Boolean.
When this is set to `true`, a package is declared to be lazily fetched. This
makes the dependency only get fetched if it is actually used.
### `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`.
|
