Commit 437cf37bd4bec7588ac25d4d54833f4809b8a9ff | zigmod

author	Meghan Denny <hello@nektro.net> 2021-02-20 21:11:28 -08:00
committer	Meghan Denny <hello@nektro.net> 2021-02-20 21:11:28 -08:00
log	437cf37bd4bec7588ac25d4d54833f4809b8a9ff
tree	eec7bad374f48cb6fa1bdfae793523657139a7e0
parent	a3417656f02017e3210f20da0529879631505d41

move docs out of README to docs folder

11 files changed, 195 insertions(+), 83 deletions(-)

README.md+1-83

...	...	@@ -35,89 +35,7 @@ $ ./zig-cache/bin/zigmod
35	35	```
36	36
37	37	## Usage
38
39		### `init` command
40		```
41		zigmod init [name] [entry_file]
42		```
43
44		- `[name]` defaults to the name of the folder you run the program in. It will also remove `zig-` from the start of the directory name by default if is prefixed by that.
45		- `[entry_file]` defaults to `src/main.zig`
46		- This command will create a `zig.mod` file in the root of your project. It is in yaml syntax.
47
48		### `fetch` command
49		```
50		zigmod fetch
51		```
52
53		- This command takes no parameters and will generate a `deps.zig` in the root of your project.
54		- `deps.zig` should not be checked into your source control.
55
56		### `sum` command
57		```
58		zigmod sum
59		```
60
61		- This will generate a `zig.sum` file with the blake3 hashes of your modules.
62		<!-- - Place that hash in the `hash: blake-<hash>` property of a dependency to be able to check it with `verify`. -->
63
64		### Adding `deps.zig` to `build.zig`
65		```diff
66		const std = @import("std");
67		const Builder = std.build.Builder;
68		+const deps = @import("./deps.zig");
69
70		pub fn build(b: *Builder) void {
71		const target = b.standardTargetOptions(.{});
72
73		const mode = b.standardReleaseOptions();
74
75		const exe = b.addExecutable("zigmod", "src/main.zig");
76		exe.setTarget(target);
77		exe.setBuildMode(mode);
78		+ deps.addAllTo(exe);
79		exe.install();
80		```
81
82		### Example
83		```yml
84		id: t5ch3nfmdaa25ndlch7ucz7yztq8n1iaanv2d7iwiw4q5n65
85		name: my_app
86		main: src/main.zig
87		dependencies:
88		- src: git https://github.com/Hejsil/zig-clap
89		- src: git https://github.com/alexnask/ctregex.zig
90		# ctregex.zig doesn't have a zig.mod file so we can manually
91		# define its entry point. this can also be used generally to
92		# override any attribute we want in this dependency.
93		name: ctregex
94		main: ctregex.zig
95		```
96
97		### `zig.mod` Reference
98		\| Name \| Type \| Note \| Description \|
99		\|------\|------\|------\|-------------\|
100		\| `name` \| `string` \| required \| The value users will put into `@import` \|
101		\| `main` \| `string` \| required \| The `.zig` entry point into your package \|
102		\| `c_include_dirs` \| `[]string` \| \| A list of relative paths to directories with `.h` files \|
103		\| `c_source_flags` \| `[]string` \| \| A list of clang flags to pass to each of the `.c` files in `c_source_files` \|
104		\| `c_source_files` \| `[]string` \| \| A list of relative paths to `.c` files to compile along with project \|
105		\| `license` \| `string` \| \| A SPDX License Identifier specifying the license covering the code in this package. \|
106		\| `dependencies` \| `[]Dep` \| \| An array of dependency objects \|
107
108		#### Dep object
109		\| Name \| Type \| Note \| Description \|
110		\|------\|------\|------\|-------------\|
111		\| `type` \| `string` \| required, enum \| One of `system_lib`, `git`, `hg`, `http` \|
112		\| `path` \| `string` \| required \| URL/path to this dependency. depends on the type \|
113		\| `src` \| `string` \| Shorthand for the format `type path`. \|
114		\| `version` \| `string` \| only on some types \| pin this dependency at a specific version \|
115		\| `only_os` \| `string` \| \| comma separated list of OS names to add this Dep to \|
116		\| `except_os` \| `string` \| \| comma separated list of OS names to exclude this Dep from \|
117
118		- `name`, `main`, `c_include_dirs`, `c_source_flags`, `c_source_files`, can be overwritten as well.
119		- `type.git` supports version pinning by `branch-XX`, `tag-XX`, and `commit-XX`.
120		- `type.http` supports version checking by `blake3-XX`, `sha256-XX`, and `sha512-XX`.
	38	Check out our [docs](docs/) or the website: https://nektro.github.io/zigmod/.
121	39
122	40	## Prior Art
123	41	- https://golang.org/ref/mod#go-mod-file

docs/README.md created+26

...	...	@@ -0,0 +1,26 @@
	1	# `zigmod` Documentation
	2
	3	Zigmod is a prototype package manager for the Zig programming language.
	4
	5	You can learn more about Zig here:
	6	- https://ziglang.org/
	7	- https://github.com/ziglang/zig
	8
	9	The rest of this documentation will assume you already have Zig installed.
	10
	11	As Zig is still in development itself, if you plan to contribute to Zigmod you will need a master download of Zig. Those can be obtained from https://ziglang.org/download/#release-master. The most recent release Zigmod was verified to work with is `0.8.0-dev.1127+6a5a6386c`.
	12
	13	## Getting Started
	14
	15	For a full command reference you can check [here](./commands/).
	16
	17	### A new project
	18	Create a new directory for your project and run these commands to get started:
	19	```
	20	$ git init
	21	$ zig init-exe
	22	$ zigmod init
	23	```
	24
	25	## Principles
	26	Zigmod is but a prototype and not the official Zig package manager. As such I wanted to lay out some of the guiding principles learned/used when making the project. You can find that documen [here](./principles.md).

docs/commands/README.md created+10

...	...	@@ -0,0 +1,10 @@
	1	## Commands
	2	Listed below is all of the commands available in Zigmod. All are meant to be run in the build root of your project.
	3
	4	- [`init`](init.md)
	5	- [`fetch`](fetch.md)
	6	- [`license`](license.md)
	7	- [`sum`](sum.md)
	8
	9	- [`zpm`](zpm.md)
	10	- [`zpm add`](zpm_add.md)

docs/commands/fetch.md created+25

...	...	@@ -0,0 +1,25 @@
	1	## `fetch` command
	2	```
	3	zigmod fetch
	4	```
	5
	6	- This command takes no parameters and will generate a `deps.zig` in the root of your project.
	7	- `deps.zig` is not typically checked into your source control.
	8
	9	### Adding `deps.zig` to your `build.zig`
	10	```diff
	11	const std = @import("std");
	12	const Builder = std.build.Builder;
	13	+const deps = @import("./deps.zig");
	14
	15	pub fn build(b: *Builder) void {
	16	const target = b.standardTargetOptions(.{});
	17
	18	const mode = b.standardReleaseOptions();
	19
	20	const exe = b.addExecutable("hello", "src/main.zig");
	21	exe.setTarget(target);
	22	exe.setBuildMode(mode);
	23	+ deps.addAllTo(exe);
	24	exe.install();
	25	```

docs/commands/init.md created+24

...	...	@@ -0,0 +1,24 @@
	1	## `init` command
	2	```
	3	zigmod init [name] [entry_point]
	4	```
	5
	6	This command will generate a `zig.mod` file and place it in the current directory. `[name]` and `[entry_point]` can be used to override the default values. `[name]` defaults to the name of the current directory, optionally removing a `zig-` prefix from it. `[entry_point]` defaults to either `src/lib.zig` or `src/main.zig` in that order.
	7
	8	The resulting file will look something like this:
	9
	10	```yml
	11	id: e8bx53yvuyhaudzhvoh16bov9ond5a5tp1zk76aflwtwsea7
	12	name: hello
	13	main: src/main.zig
	14	dependencies:
	15	```
	16
	17	- `id` is a randomly generated identifier that will uniquely identify your project coming from different versions or sources.
	18	- `name` is the string other developers will `@import` your package with.
	19	- `main` is the root Zig file of your package.
	20	- `dependencies` is a list that we'll add to later.
	21
	22	Check out the [`zig.mod` reference](./../zig.mod.md) for more info.
	23
	24	Also check out `zigmod`'s own `zig.mod` for a useful example: https://github.com/nektro/zigmod/blob/master/zig.mod.

docs/commands/license.md created+21

...	...	@@ -0,0 +1,21 @@
	1	## `license` command
	2	```
	3	zigmod license
	4	```
	5
	6	This will print a listing of all of your dependencies (deeply)' licenses. Any code is valid for the `license` field in `zig.mod` but should it match a valid SPDX identifier, a URL to learn more about the license will also be printed so the user can learn more about it.
	7
	8	Should one of your dependencies not have a `license` field in their `zig.mod` manifest, an `Unspecified:` list will appear at the bottom of the output.
	9
	10	Running this command on Zigmod itself (as of this writing) produces such output:
	11	```
	12	MIT:
	13	= https://opensource.org/licenses/MIT
	14	- This
	15	- v/git/github.com/yaml/libyaml/tag-0.2.5
	16	- v/git/github.com/nektro/zig-ansi/commit-25039ca
	17	- v/git/github.com/ziglibs/known-folders/commit-f0f4188
	18	- v/git/github.com/Vexu/zuri/commit-41bcd78
	19	- v/git/github.com/alexnask/iguanaTLS/commit-58f72f6
	20	- v/git/github.com/nektro/zig-licenses/commit-a15ef9b
	21	```

docs/commands/sum.md created+18

...	...	@@ -0,0 +1,18 @@
	1	## `sum` command
	2	```
	3	zigmod sum
	4	```
	5
	6	- This will generate a `zig.sum` file with the blake3 hashes of your modules.
	7
	8	`zig.sum` may be checked into source control and there are plans to integrate it into the other commands in the future.
	9
	10	Running it on Zigmod (as of this writing) itself yields:
	11	```
	12	blake3-22472b867734926b202c055892fb0abb03f91556cd88998e2fe77addb003b1dd v/git/github.com/yaml/libyaml/tag-0.2.5
	13	blake3-c9f1cfe1c2bc8f0f7886a29458985491ea15f74c78275c28ce2276007f94d492 v/git/github.com/nektro/zig-ansi/commit-25039ca
	14	blake3-74924ab693ea7730d53839a45805584561fdfc99872f8c307121089070ef6283 v/git/github.com/ziglibs/known-folders/commit-f0f4188
	15	blake3-35adb816bfc0db5e1cc156a2dc61de9b9f15a6e64879cbd0dc962e3c99601850 v/git/github.com/Vexu/zuri/commit-41bcd78
	16	blake3-9bc6fdab07a606e3a99c9480e15e62aacc0cf078f3b233bdbb54d4e16acbb942 v/git/github.com/alexnask/iguanaTLS/commit-58f72f6
	17	blake3-87a1481d3affd6b70f4d20c69096a36f3fc55859ec6ed2e93df3c3913a86640f v/git/github.com/nektro/zig-licenses/commit-a15ef9b
	18	```

docs/commands/zpm.md created+11

...	...	@@ -0,0 +1,11 @@
	1	## `zpm` command
	2	```
	3	zigmod zpm
	4	```
	5
	6	This is a stub subcommand for parenting all subcommands that interfact with instances of https://github.com/zigtools/zpm-server and currently only displays help text.
	7
	8	The default remote is https://zpm.random-projects.net/.
	9
	10	The subcommands available are:
	11	- [`add`](zpm_add.md)

docs/commands/zpm_add.md created+14

...	...	@@ -0,0 +1,14 @@
	1	## `zpm add` command
	2	```
	3	zigmod zpm add <name>
	4	```
	5
	6	- `<name>` is required and will pull the corresponding package from https://zpm.random-projects.net/ and add it to your `zig.mod`.
	7	- Since zpm is not native to Zigmod is will also manually define the `name` and `main` attributes based on the zpm data. Normally, if the source you reference contains a `zig.mod` file in its root, those fields are not required to defined by the dependent.
	8
	9	For example running `zigmod zpm add apple_pie` will append the following to your `zig.mod`:
	10	```yml
	11	- src: git https://github.com/Luukdegram/apple_pie
	12	name: apple_pie
	13	main: src/apple_pie.zig
	14	```

docs/principles.md created+18

...	...	@@ -0,0 +1,18 @@
	1	## Zigmod Principles
	2	Zigmod is a prototype package manager for Zig. An official one will eventually be made so I wanted to add this page to the docs to go over some of the guiding principles used in this project. Some are general good practice for app development but there will be added context in how they apply to making a package manager.
	3
	4	### 1. Be declarative
	5	`zig.mod` is a static Yaml file that does not contain any Zig code. This was intentional to not allow packages to run arbitrary code on the developer's machine. A maintainer's computer is an arguably much more high risk attack surface so the trust of code should be kept to a minimum. Given that the environment may contain API/ssh/etc keys that provide access to things far wider than just the user's computer.
	6
	7	### 2. Be Immutable/Avoid the network as much as possible
	8	The network is slow and unreliable. So we should cache only what we need and avoid fetching unchanged data. This is achieved from a user's perspective by using versions on your dependencies that dont change. For example tags or commits when using git, or specifying a hash when using http.
	9
	10	### 3. Keep debugging easy
	11	Dependencies are stored based on the path they were downloaded from (as opposed to a hash or their random package ID).
	12
	13	Example: `.zigmod/deps/v/git/github.com/Hejsil/zig-clap/commit-e00e902/clap.zig`.
	14
	15	This ensures that stack traces are still readable.
	16
	17	### 4. Follow the Zen
	18	https://ziglang.org/documentation/master/#Zen

docs/zig.mod.md created+27

...	...	@@ -0,0 +1,27 @@
	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`.