1## `zigmod.yml` Reference
2
3`zigmod.yml` is the main manifest that Zigmod will read to learn all about your application or package.
4
5`zig.mod` is a valid legacy alternative.
6
7### `id`
8- Type: `string`
9- Required
10`id` is a randomly generated string used to identify your package coming from multiple sources. Sources here meaning various git repositories, http archive downloads, etc.
11
12### `name`
13- Type: `string`
14- Required
15This is the value that users of your package will [`@import`](https://ziglang.org/documentation/master/#import) you by.
16
17### `main`
18- Type: `string`
19The is the local path to the entry point of your package and the file that will be returned when users run [`@import`](https://ziglang.org/documentation/master/#import) on your package.
20
21### `license`
22- Type: `string`
23This is an optional field that may be set to specify the license that your package code is covered by. This field is read by the [`zigmod license`](commands/license_.md) command to show the licenses used by all of a project's dependencies. If the value of `license` is set to a [SPDX Identifier](https://spdx.org/licenses/) then a link to the license will also be printed for the user to learn more about it. Check the command reference for more info.
24
25### `c_include_dirs`
26- Type: `[]string`
27This is a list of relative paths to folders which are a root search path for `.h` files when compiling C code in a project.
28
29### `c_source_flags`
30- Type: `[]string`
31This is a list of [`clang`](https://clang.llvm.org/docs/UsersManual.html#command-line-options) C source flags that will be passed to all of the C files listed under the `c_source_files` for this project.
32
33### `c_source_files`
34- Type: `[]string`
35This is a list of relative paths to C source files to compile along with this project. This will be required if you use Zig's [`@cImport`](https://ziglang.org/documentation/master/#cImport), `extern`, etc.
36
37### `files`
38- Type: `[]string`
39This accepts a list of local directories to embed static assets. These files will be provided through a `files.zig` files in the module root. It generates a list of `@embedFile` calls.
40
41### `root_files`
42- Type: `[]string`
43This accepts a list of local directories to embed static assets. These files will be provided through a `files.zig` files in the package root. It generates a list of `@embedFile` calls.
44
45### `dependencies`
46- Type: `[]Dep`
47This is a list of `Dep` objects. `Dep` objects are how you include the other people's code in your project. See the `Dep` documentation below to learn more about the attributes available here.
48
49### `root_dependencies`
50- Type: `[]Dep`
51Similar to `dependencies` but will only get added to the project if the current `zigmod.yml` is the root module.
52
53### `build_dependencies`
54- Type: `[]Dep`
55Similar to `dependencies` but will only get added to the project if the current `zigmod.yml` is the root module. Exposed in `deps.zig` through the `deps.imports` decl.
56
57### `min_zig_version`
58- Type: `string`
59Parsed as a `std.SemanticVersion`, this attribute refers to the minimum compatible Zig version for this package/application and will cause `zig build` to panic if violated.
60
61### `min_zigmod_version`
62- Type: `string`
63This attribute refers to the minimum compatible Zigmod version for this package/application and will cause `zigmod fetch`, `zigmod ci`, and others to exit with an error.
64While rare, this is most useful to provide a nice error message to the user when your `zigmod.yml` uses a new feature that may not be available in previous versions of Zigmod.
65
66----
67
68### Dep Object
69This is the object used in the top-level `dependencies` attribute and used to add external code to your project.
70
71#### Dep `src`
72- Type: `type path ?version`
73- Example: `git https://github.com/Hejsil/zig-clap`
74- Required
75This is the base attribute used to reference external code for use in your project. `type` is an enum and only allows certain values. `path` is the URL or other identifier used to locate the contents of this package based on the `type`.
76
77The available `type`s are:
78- `local`
79- `system_lib`
80- `framework`
81- `git`
82- `hg`
83- `http`
84
85For the full details on `Dep` types, you can check out the source where the enum is defined: https://github.com/nektro/zigmod/blob/master/src/util/dep_type.zig.
86
87> Note: the `local` type modifies the input behavior to be shorthand for `<name> <main>` rather than `path version` since the latter fields don't make sense for local files.
88
89#### Dep `version`
90- Type: `string-string`
91- Example: `commit-2c21764`
92- Example: `sha256-8ff0b79fd9118af7a760f1f6a98cac3e69daed325c8f9f0a581ecb62f797fd64`
93This attribute is used to reference the `type`/`path` combo by a specific revision, specific to the `type`. Specifying a `version` is ideal when possible because it ensures the immutability of the package contents being referenced, and thus Zigmod can skip going to the network if the package is already located on disk.
94
95Version types available to each Dep type:
96- `system_lib`
97 - Not affected by `version`.
98- `framework`
99 - Not affected by `version`.
100- `git`
101 - `commit`
102 - `tag`
103 - `branch`
104- `hg`
105 - Not currently affected by `version`.
106- `http`
107 - `blake3`
108 - `sha256`
109 - `sha512`
110
111#### Dep `only_os`
112- Type: `comma-split string[]`
113- Example: `windows`
114- Example: `macos,tvos,ios`
115This attribute specifies a way to filter when the dependency will be generated into the contents of `deps.zig`. `only_os` is an inclusive filter in which the dependency will only be in the output if the host target operating system is in the list specified or if this field is omitted.
116
117#### Dep `except_os`
118- Type: `comma-split string[]`
119- Example: `linux`
120This attribute specifies a way to filter when the dependency will be generated into the contents of `deps.zig`. `except_os` is an exclusive filter in which the dependency will only be in the output if the host target operating is \*not\* in the list specified or if the field is omitted.
121
122#### Dep `keep`
123- Type: `string`
124- Example: `true`|any
125This attribute is a manual override for having an external repo that contains no Zig or C code but other files be managed through Zigmod and `deps.zig`. `true` is the only value that will enable this flag.
126
127#### Dep Overrides
128There are a number of fields you can add to a `Dep` object that will override it's top-level value. This is most useful in the case where a project you want to use does not have a `zigmod.yml` manifest. You can then use overrides to define the values for them. The only top-level value you can not override is `dependencies`.