authorgravatar for hello@nektro.netMeghan Denny <hello@nektro.net> 2022-04-17 21:47:42 -07:00
committergravatar for hello@nektro.netMeghan Denny <hello@nektro.net> 2022-04-17 21:47:42 -07:00
logb3017a7cdce9cb7d00623435d8f692d1fa128b28
treeb471970c2d6be0170ccd2b23b37a3c051b3d81ad
parent1536392219e0c818ba2ff6d77a3f3bf7f4ad0027

docs/tutorial.md- use word wrap instead of multiple lines

1 files changed, 11 insertions(+), 30 deletions(-)

docs/tutorial.md+11-30
...@@ -20,8 +20,7 @@ The wizard will also ask if you'd like it setup any additional metadata files su...@@ -20,8 +20,7 @@ The wizard will also ask if you'd like it setup any additional metadata files su
20---20---
21## Understanding `zigmod.yml`21## Understanding `zigmod.yml`
2222
23Running [`zigmod init`](./commands/init.md) will ask if You want to create an application or a23Running [`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.
24library. Based on You answer the resulting `zigmod.yml` file have two types.
2524
26### `zigmod.yml` for an application (`id` is omitted)25### `zigmod.yml` for an application (`id` is omitted)
2726
...@@ -46,23 +45,15 @@ dependencies:...@@ -46,23 +45,15 @@ dependencies:
46 - src: git https://github.com/jecolon/ziglyph45 - src: git https://github.com/jecolon/ziglyph
47```46```
4847
49Here I assume that You initialized Your project with `zig init-exe` or48Here 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`.
50`zig init-lib`, so Your `build.zig` the `addExecutable()` or
51`addStaticLibrary()` call points to `src/main.zig`.
5249
53In this case You can `@import("ziglyph")` in `src/lib.zig`, but not in50In 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`.
54`src/main.zig`. However You can `@import("my-package")` in `src/main.zig`.
5551
56Please note, that using `zig init-exe` or `zig init-lib` for creating a project52Please 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.
57does not mean that You have to use `zigmod init` in application or library mode.
58Creating a `zigmod.yml` file with proper `name` and `main` only makes Your package
59importable by other projects. This is usually not needed with applications, but
60quite useful in case of libraries; hence the name.
6153
62### Zig and Zigmod package handling explained54### Zig and Zigmod package handling explained
6355
64Zig packages can only `@import` **direct** children. The include tree is56Zig packages can only `@import` **direct** children. The include tree is something like this:
65something like this:
6657
67```58```
68root59root
...@@ -73,9 +64,7 @@ root...@@ -73,9 +64,7 @@ root
73 E64 E
74```65```
7566
76`root` can `@import` `A`, `B` and `D`, but `E` can be imported only from `D`.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.)
77`B` can not import anything.
78(Everybody can import relative files, this limitation is only for packages.)
7968
80In library `zigmod.yml` example the tree looks like this:69In library `zigmod.yml` example the tree looks like this:
8170
...@@ -85,20 +74,13 @@ root (src/main.zig)...@@ -85,20 +74,13 @@ root (src/main.zig)
85 ziglyph (separate package)74 ziglyph (separate package)
86```75```
8776
88`root` is always set in `build.zig` using `addExecutable()` or77`root` is always set in `build.zig` using `addExecutable()` or `addStaticLibrary()` calls.
89`addStaticLibrary()` calls.
9078
91It is very important to understand, that `my-package` is _below_ `root`, as79It 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`).
92`name/main` in `zigmod.yml` will create a separate package (it will not be chained to
93`root`).
9480
95If You want to use the dependencies from `root`, then make sure that Your81If 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.
96`zigmod.yml` does _not_ contain a `main` line **and** use `root_dependencies`
97instead of `dependencies`. This is what `zigmod init` does in application mode.
9882
99On the other hand using `root_dependencies` and `dependencies` is not mutually83On 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`.
100exclusive, You can take advantage of using both, like zigmod does. Using
101`dependencies` requires a proper `main` field in Your `zigmod.yml`.
10284
103## Running `zigmod fetch`85## Running `zigmod fetch`
104This 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`.86This 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,8 +111,7 @@ Add `--no-update` if you do want it to fetch remote updates and only regenerate
129 exe.install();111 exe.install();
130```112```
131113
132> Note: If You would like to use the external dependencies in tests, do not114> 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.
133forget to add `deps.addAllTo(main_tests)` after the `addTest()` call.
134115
135---116---
136## Adding a dependency117## Adding a dependency