authorgravatar for hello@nektro.netMeghan Denny <hello@nektro.net> 2021-08-20 21:00:53 -07:00
committergravatar for hello@nektro.netMeghan Denny <hello@nektro.net> 2021-08-20 21:00:53 -07:00
logb3ea5586def0e49c3d65a45c27441f0700dc6808
treec099b54adc57ec8468f57006cd5a6bdbe854680f
parentc807a3c56dcefdd8cfa50dbaa8ed8620e839ee35

docs/tutorial- add more sections

1 files changed, 120 insertions(+), 1 deletions(-)

docs/tutorial.md+120-1
...@@ -3,7 +3,7 @@...@@ -3,7 +3,7 @@
3This guide will go over the various common workflows done while using Zigmod as well as how its design goals fit into them.3This guide will go over the various common workflows done while using Zigmod as well as how its design goals fit into them.
44
5## Initialize a new project5## Initialize a new project
6To get started you'll want to run through these commands.6To get started you'll want to navigate to a new folder and run these commands.
77
8```8```
9git init9git init
...@@ -16,3 +16,122 @@ Zigmod's init wizard will ask you if the current project is an application or a...@@ -16,3 +16,122 @@ Zigmod's init wizard will ask you if the current project is an application or a
16The wizard will also ask if you'd like it setup any additional metadata files such as `.gitignore` or `LICENSE` for you.16The wizard will also ask if you'd like it setup any additional metadata files such as `.gitignore` or `LICENSE` for you.
1717
18> Ref: See [`zigmod init`](./commands/init.md) for more info.18> Ref: See [`zigmod init`](./commands/init.md) for more info.
19
20---
21## Running `zigmod fetch`
22This command will inspect your `zig.mod` 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
24`deps.zig` we will use in the next step integrating with the [Zig Build System](https://ziglang.org/documentation/master/#Zig-Build-System). [Learn more](./deps.zig.md).
25
26`zigmod.lock` is a way to enable [Reproducible builds](https://reproducible-builds.org/) and often used in CI environments. [Learn more](./commands/ci.md).
27
28Add `--no-update` if you do want it to fetch remote updates and only regenerate `deps.zig`.
29
30> Ref: See [`zigmod fetch`](commands/fetch.md) reference for more info.
31
32---
33## Integrating with `build.zig`
34```diff
35 const std = @import("std");
36+const deps = @import("./deps.zig");
37
38 pub fn build(b: *std.build.Builder) void {
39 const target = b.standardTargetOptions(.{});
40
41 const mode = b.standardReleaseOptions();
42
43 const exe = b.addExecutable("hello", "src/main.zig");
44 exe.setTarget(target);
45 exe.setBuildMode(mode);
46+ deps.addAllTo(exe);
47 exe.install();
48```
49
50---
51## Adding a dependency
52The core of expandability, it is possible to add dependencies to your project. How exactly, depends on where you're sourcing the information from.
53
54- Aquila
55 - One place packages can be sourced from is https://aquila.red/. In order to add them to your project, you will obtain its ID in the form `1/truemedian/hzzp` and then run `zigmod aq add <package>`.
56
57- ZPM
58 - https://zig.pm/ is another supported pacakge index. You may add packages from ZPM with `zigmod zpm add <pacakge>`.
59
60- Other/Git
61 - Zigmod supports adding any Git repository as a dependency. This is done by manually editing your `zig.mod` and adding a line under either the `dependencies` or `dev_dependencies` keys. For example, adding a line with this contents would add `apple_pie` to your project: ` - src: git https://github.com/Luukdegram/apple_pie`. The URL field may be any valid Git url that you would pass to `git clone`.
62
63- Other/System Library
64 - System libraries are similar to Git dependencies, but instead of `git <url>` it is `system_lib <name>`.
65
66- Other/HTTP
67 - Http tarballs are also allowed and follow a similar pattern as Git dependencies but use the `http` type. One thing to note is that it is recomended to add a hash verification after your tarball URL so that zigmod may assert whether or not it has been downloaded already to prevent unnecessary trips to the network. Hash verification versions are placed after the URL and in the form `type-string` such as `sha256-8ff0b79fd9118af7a760f1f6a98cac3e69daed325c8f9f0a581ecb62f797fd64`. They may also be placed in their own `version` key instead of `src`. The available hash algorithms are `blake3`, `sha256`, `sha512`.
68
69- Other/Mercurial
70 - Mercurial follows the same rules as Git dependencies and uses the `hg` Dep type.
71
72---
73## Using build-time dependencies in `build.zig`
74Dependencies that are added to `dev_dependencies` will additionally be exposed in `deps.zig` generation under the `imports` namesapce. https://github.com/Snektron/vulkan-zig is a common example of a package that can be used with Zigmod as a build-time dependency.
75
76```zig
77const deps = @import("./deps.zig");
78const vkgen = deps.imports.vulkan_zig;
79
80pub fn build(b: *Builder) void {
81
82 const exe = b.addExecutable("my-executable", "src/main.zig");
83
84 const gen = vkgen.VkGenerateStep.init(b, "path/to/vk.xml", "vk.zig");
85
86 exe.addPackage(gen.package);
87}
88```
89
90---
91## Contributing to dependency upstream\
92When using Git dependencies, Zigmod streamlines the process of contributing back fixes and improvements to your upstream. This is due to the fact that Zigmod will preserve the `.git` folder when cloning so that you may work with it.
93
94Suppose we have the package https://github.com/octocat/zig-hello.
95
96Zigmod will `git clone` its contents to `.zigmod/deps/git/github.com/octocat/zig-hello`. If we find a bug or want to contribute a new feature we may navigate to this directory, edit any files we choose and make commits.
97
98Then fork the repository on `github.com` or wherever it is hosted and add a local remote so that you have something to push to. `git remote add fork https://github.com/you/zig-hello`.
99
100Then push your local changes with `git push origin master` and create your pull request.
101
102---
103## Using Zigmod in Github Actions
104```yml
105- uses: nektro/actions-setup-zigmod
106```
107
108This will allow your Github Action task to use the various Zigmod commands. `zigmod ci` is recommended for this use case as it is similar to `zigmod fetch` but will fetch the versions only listed in your `zigmod.lock`.
109
110---
111## Publishing your project on Aquila
112https://github.com/nektro/aquila is a package index software and CI system designed to work in conjunction with Zigmod.
113
114> Note: I, @nektro, host a public instance at https://aquila.red/ available for anyone to use. However Aquila can be self hosted and the only difference in the following instructions will be the domain name.
115
116Navigating to https://aquila.red/ will show you the homepage with recent pacakges and most starred ones.
117
118Clicking the "Login" button will bring you to https://aquila.red/dashboard which will show you a list of your currently imported pacakges. The login screen will prompt you to authorize with an identity provider and ask you for webhook permissions. This is so that aquila can listen for new updates and automatically test them for the CI.
119
120The main nav will contain a link to https://aquila.red/import. Listed will be all of your not-imported Zig projects. Clicking "Select" will not immediately navigate the page in most browsers as the server will attempt to clone and verify your repository. Please be patient while it loads.
121
122Once it brings you to the package page it will now be available for discovery and be automatically included for testing.
123
124---
125## Auditing your project's licenses
126This can come in handy for users and organizations alike. The `zigmod license` command will show you a list of the licenses involved in a project (deeply) and present them nicely grouping similar licenses together and providing a link to the license test for any projects that use a valid SPDX license identifier.
127
128Given the project https://github.com/kristoff-it/bork, at the time of writing that output would look like the following:
129
130![image](https://user-images.githubusercontent.com/5464072/130309694-180da454-553d-4136-a7ac-0f4f3f5ecf3d.png)
131
132> Ref: See [`zigmod license`](commands/license_.md) reference for more info.
133
134---
135## Verifying dependency integrity
136
137> Ref: See [`zigmod sum`](commands/sum.md) reference for more info.