Commit 1536392219e0c818ba2ff6d77a3f3bf7f4ad0027 | zigmod

author	voroskoi <60064214+voroskoi@users.noreply.github.com> 2022-04-18 04:06:30 +02:00
committer	GitHub <noreply@github.com> 2022-04-17 19:06:30 -07:00
log	1536392219e0c818ba2ff6d77a3f3bf7f4ad0027
tree	bf26e6916d87531281edb0308f0803bf5ad24f5a
parent	a6628cf1f529c85a4f2e561bd056764d4dcb58b4
signature	Signed by PGP key 4AEE18F83AFDEB23

[skip ci] docs: explain zigmod.yml dependency handling (#62)

1 files changed, 85 insertions(+), 0 deletions(-)

docs/tutorial.md+85

...	@@ -18,6 +18,88 @@ The wizard will also ask if you'd like it setup any additional metadata files su	...	@@ -18,6 +18,88 @@ The wizard will also ask if you'd like it setup any additional metadata files su
18	> Ref: See [`zigmod init`](./commands/init.md) for more info.	18	> Ref: See [`zigmod init`](./commands/init.md) for more info.
19		19
20	---	20	---
		21	## Understanding `zigmod.yml`
		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.
		25
		26	### `zigmod.yml` for an application (`id` is omitted)
		27
		28	```yaml
		29	name: my-package
		30	license: None
		31	description: None
		32	root_dependencies:
		33	- src: git https://github.com/jecolon/ziglyph
		34	```
		35
		36	In this case You can use `@import("ziglyph")` to import the package and use it.
		37
		38	### `zigmod.yml` for a library (`id` is omitted)
		39
		40	```yaml
		41	name: my-package
		42	main: src/lib.zig
		43	license: None
		44	description: None
		45	dependencies:
		46	- src: git https://github.com/jecolon/ziglyph
		47	```
		48
		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`.
		52
		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`.
		55
		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.
		61
		62	### Zig and Zigmod package handling explained
		63
		64	Zig packages can only `@import` direct children. The include tree is
		65	something like this:
		66
		67	```
		68	root
		69	A
		70	C
		71	B
		72	D
		73	E
		74	```
		75
		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.)
		79
		80	In library `zigmod.yml` example the tree looks like this:
		81
		82	```
		83	root (src/main.zig)
		84	my-package (src/lib.zig)
		85	ziglyph (separate package)
		86	```
		87
		88	`root` is always set in `build.zig` using `addExecutable()` or
		89	`addStaticLibrary()` calls.
		90
		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`).
		94
		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.
		98
		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`.
		102
21	## Running `zigmod fetch`	103	## Running `zigmod fetch`
22	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`.	104	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`.
23		105
...	@@ -47,6 +129,9 @@ Add `--no-update` if you do want it to fetch remote updates and only regenerate	...	@@ -47,6 +129,9 @@ Add `--no-update` if you do want it to fetch remote updates and only regenerate
47	exe.install();	129	exe.install();
48	```	130	```
49		131
		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.
		134
50	---	135	---
51	## Adding a dependency	136	## Adding a dependency
52	The core of expandability, it is possible to add dependencies to your project. How exactly, depends on where you're sourcing the information from.	137	The core of expandability, it is possible to add dependencies to your project. How exactly, depends on where you're sourcing the information from.