| ... | ... | @@ -20,8 +20,7 @@ The wizard will also ask if you'd like it setup any additional metadata files su |
| 20 | 20 | --- |
| 21 | 21 | ## Understanding `zigmod.yml` |
| 22 | 22 | |
| 23 | | Running [`zigmod init`](./commands/init.md) will ask if You want to create an application or a |
| 24 | | library. Based on You answer the resulting `zigmod.yml` file have two types. |
| 23 | Running [`zigmod init`](./commands/init.md) will ask if You want to create an application or a library. Based on You answer the resulting `zigmod.yml` file have two types. |
| 25 | 24 | |
| 26 | 25 | ### `zigmod.yml` for an application (`id` is omitted) |
| 27 | 26 | |
| ... | ... | @@ -46,23 +45,15 @@ dependencies: |
| 46 | 45 | - src: git https://github.com/jecolon/ziglyph |
| 47 | 46 | ``` |
| 48 | 47 | |
| 49 | | Here I assume that You initialized Your project with `zig init-exe` or |
| 50 | | `zig init-lib`, so Your `build.zig` the `addExecutable()` or |
| 51 | | `addStaticLibrary()` call points to `src/main.zig`. |
| 48 | Here I assume that You initialized Your project with `zig init-exe` or `zig init-lib`, so Your `build.zig` the `addExecutable()` or `addStaticLibrary()` call points to `src/main.zig`. |
| 52 | 49 | |
| 53 | | In this case You can `@import("ziglyph")` in `src/lib.zig`, but not in |
| 54 | | `src/main.zig`. However You can `@import("my-package")` in `src/main.zig`. |
| 50 | In this case You can `@import("ziglyph")` in `src/lib.zig`, but not in `src/main.zig`. However You can `@import("my-package")` in `src/main.zig`. |
| 55 | 51 | |
| 56 | | Please note, that using `zig init-exe` or `zig init-lib` for creating a project |
| 57 | | does not mean that You have to use `zigmod init` in application or library mode. |
| 58 | | Creating a `zigmod.yml` file with proper `name` and `main` only makes Your package |
| 59 | | importable by other projects. This is usually not needed with applications, but |
| 60 | | quite useful in case of libraries; hence the name. |
| 52 | Please note, that using `zig init-exe` or `zig init-lib` for creating a project does not mean that You have to use `zigmod init` in application or library mode. Creating a `zigmod.yml` file with proper `name` and `main` only makes Your package importable by other projects. This is usually not needed with applications, but quite useful in case of libraries; hence the name. |
| 61 | 53 | |
| 62 | 54 | ### Zig and Zigmod package handling explained |
| 63 | 55 | |
| 64 | | Zig packages can only `@import` **direct** children. The include tree is |
| 65 | | something like this: |
| 56 | Zig packages can only `@import` **direct** children. The include tree is something like this: |
| 66 | 57 | |
| 67 | 58 | ``` |
| 68 | 59 | root |
| ... | ... | @@ -73,9 +64,7 @@ root |
| 73 | 64 | E |
| 74 | 65 | ``` |
| 75 | 66 | |
| 76 | | `root` can `@import` `A`, `B` and `D`, but `E` can be imported only from `D`. |
| 77 | | `B` can not import anything. |
| 78 | | (Everybody can import relative files, this limitation is only for packages.) |
| 67 | `root` can `@import` `A`, `B` and `D`, but `E` can be imported only from `D`. `B` can not import anything. (Everybody can import relative files, this limitation is only for packages.) |
| 79 | 68 | |
| 80 | 69 | In library `zigmod.yml` example the tree looks like this: |
| 81 | 70 | |
| ... | ... | @@ -85,20 +74,13 @@ root (src/main.zig) |
| 85 | 74 | ziglyph (separate package) |
| 86 | 75 | ``` |
| 87 | 76 | |
| 88 | | `root` is always set in `build.zig` using `addExecutable()` or |
| 89 | | `addStaticLibrary()` calls. |
| 77 | `root` is always set in `build.zig` using `addExecutable()` or `addStaticLibrary()` calls. |
| 90 | 78 | |
| 91 | | It is very important to understand, that `my-package` is _below_ `root`, as |
| 92 | | `name/main` in `zigmod.yml` will create a separate package (it will not be chained to |
| 93 | | `root`). |
| 79 | It is very important to understand, that `my-package` is _below_ `root`, as `name/main` in `zigmod.yml` will create a separate package (it will not be chained to `root`). |
| 94 | 80 | |
| 95 | | If You want to use the dependencies from `root`, then make sure that Your |
| 96 | | `zigmod.yml` does _not_ contain a `main` line **and** use `root_dependencies` |
| 97 | | instead of `dependencies`. This is what `zigmod init` does in application mode. |
| 81 | If You want to use the dependencies from `root`, then make sure that Your `zigmod.yml` does _not_ contain a `main` line **and** use `root_dependencies` instead of `dependencies`. This is what `zigmod init` does in application mode. |
| 98 | 82 | |
| 99 | | On the other hand using `root_dependencies` and `dependencies` is not mutually |
| 100 | | exclusive, You can take advantage of using both, like zigmod does. Using |
| 101 | | `dependencies` requires a proper `main` field in Your `zigmod.yml`. |
| 83 | On the other hand using `root_dependencies` and `dependencies` is not mutually exclusive, You can take advantage of using both, like zigmod does. Using `dependencies` requires a proper `main` field in Your `zigmod.yml`. |
| 102 | 84 | |
| 103 | 85 | ## Running `zigmod fetch` |
| 104 | 86 | This command will inspect your `zigmod.yml` and download any new dependencies as well as pulling updates for any ones already download. It will recursively do this for your entire tree until it is full constructed which will culminate in the generation of two output files: `deps.zig` and `zigmod.lock`. |
| ... | ... | @@ -129,8 +111,7 @@ Add `--no-update` if you do want it to fetch remote updates and only regenerate |
| 129 | 111 | exe.install(); |
| 130 | 112 | ``` |
| 131 | 113 | |
| 132 | | > Note: If You would like to use the external dependencies in tests, do not |
| 133 | | forget to add `deps.addAllTo(main_tests)` after the `addTest()` call. |
| 114 | > Note: If You would like to use the external dependencies in tests, do not forget to add `deps.addAllTo(main_tests)` after the `addTest()` call. |
| 134 | 115 | |
| 135 | 116 | --- |
| 136 | 117 | ## Adding a dependency |
Meghan Denny <hello@nektro.net> 2022-04-17 21:47:42 -07:00