| ... | ... | @@ -1,27 +1,88 @@ |
| 1 | 1 | ## `zig.mod` Reference |
| 2 | | | Name | Type | Note | Description | |
| 3 | | |------|------|------|-------------| |
| 4 | | | `name` | `string` | required | The value users will put into `@import` | |
| 5 | | | `main` | `string` | required | The `.zig` entry point into your package | |
| 6 | | | `c_include_dirs` | `[]string` | | A list of relative paths to directories with `.h` files | |
| 7 | | | `c_source_flags` | `[]string` | | A list of clang flags to pass to each of the `.c` files in `c_source_files` | |
| 8 | | | `c_source_files` | `[]string` | | A list of relative paths to `.c` files to compile along with project | |
| 9 | | | `license` | `string` | | A SPDX License Identifier specifying the license covering the code in this package. | |
| 10 | | | `dependencies` | `[]Dep` | | An array of dependency objects | |
| 11 | | |
| 12 | | ### Dep object |
| 13 | | | Name | Type | Note | Description | |
| 14 | | |------|------|------|-------------| |
| 15 | | | `type` | `string` | required, enum | One of `system_lib`, `git`, `hg`, `http` | |
| 16 | | | `path` | `string` | required | URL/path to this dependency. depends on the type | |
| 17 | | | `src` | `string` | Shorthand for the format `type path`. | |
| 18 | | | `version` | `string` | only on some types | pin this dependency at a specific version | |
| 19 | | | `only_os` | `string` | | comma separated list of OS names to add this Dep to | |
| 20 | | | `except_os` | `string` | | comma separated list of OS names to exclude this Dep from | |
| 21 | | |
| 22 | | Note: |
| 23 | | - `name`, `main`, `c_include_dirs`, `c_source_flags`, `c_source_files`, can be overwritten as well. |
| 24 | | |
| 25 | | ### Versioning |
| 26 | | - `type.git` supports version pinning by `branch-XX`, `tag-XX`, and `commit-XX`. |
| 27 | | - `type.http` supports version checking by `blake3-XX`, `sha256-XX`, and `sha512-XX`. |
| 2 | |
| 3 | ### `id` |
| 4 | - Type: `string` |
| 5 | - Required |
| 6 | `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. |
| 7 | |
| 8 | ### `name` |
| 9 | - Type: `string` |
| 10 | - Required |
| 11 | This is the value that users of your package will [`@import`](https://ziglang.org/documentation/master/#import) you by. |
| 12 | |
| 13 | ### `main` |
| 14 | - Type: `string` |
| 15 | The 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. |
| 16 | |
| 17 | ### `license` |
| 18 | - Type: `string` |
| 19 | This 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. |
| 20 | |
| 21 | ### `c_include_dirs` |
| 22 | - Type: `[]string` |
| 23 | This is a list of relative paths to folders which are a root search path for `.h` files when compiling C code in a project. |
| 24 | |
| 25 | ### `c_source_flags` |
| 26 | - Type: `[]string` |
| 27 | This 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. |
| 28 | |
| 29 | ### `c_source_files` |
| 30 | - Type: `[]string` |
| 31 | This 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. |
| 32 | |
| 33 | ### `dependencies` |
| 34 | - Type: `[]Dep` |
| 35 | This 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. |
| 36 | |
| 37 | ---- |
| 38 | |
| 39 | ### Dep Object |
| 40 | This is the object used in the top-level `dependencies` attribute and used to add external code to your project. |
| 41 | |
| 42 | #### Dep `src` |
| 43 | - Type: `type path` |
| 44 | - Example: `git https://github.com/Hejsil/zig-clap` |
| 45 | - Required |
| 46 | This 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`. |
| 47 | |
| 48 | The available `type`s are: |
| 49 | - `system_lib` |
| 50 | - `git` |
| 51 | - `hg` |
| 52 | - `http` |
| 53 | |
| 54 | For 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. |
| 55 | |
| 56 | #### Dep `version` |
| 57 | - Type: `string-string` |
| 58 | - Example: `commit-2c21764` |
| 59 | - Example: `sha256-8ff0b79fd9118af7a760f1f6a98cac3e69daed325c8f9f0a581ecb62f797fd64` |
| 60 | This 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. |
| 61 | |
| 62 | Version types available to each Dep type: |
| 63 | - `system_lib` |
| 64 | - Not affected by `version`. |
| 65 | - `git` |
| 66 | - `commit` |
| 67 | - `tag` |
| 68 | - `branch` |
| 69 | - `hg` |
| 70 | - Not currently affected by `version`. |
| 71 | - `http` |
| 72 | - `blake3` |
| 73 | - `sha256` |
| 74 | - `sha512` |
| 75 | |
| 76 | #### Dep `only_os` |
| 77 | - Type: `comma-split string[]` |
| 78 | - Example: `windows` |
| 79 | - Example: `macos,tvos,ios` |
| 80 | This 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 ommitted. |
| 81 | |
| 82 | #### Dep `except_os` |
| 83 | - Type: `comma-split string[]` |
| 84 | - Example: `linux` |
| 85 | This attribute specifies a way to filter when the dependency will be generated into the contents of `deps.zig`. `except_os` is an exlusive 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 ommitted. |
| 86 | |
| 87 | #### Dep Overrides |
| 88 | There 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 `zig.mod` manifest. You can then use overrides to define the values for them. The only top-level value you can not override is `dependencies`. |
Meghan Denny <hello@nektro.net> 2021-02-26 11:33:40 -08:00