feat(web/website): init
This adds a new Website/Docs for Snix, using Thulite / Doks, which is mostly hugo and a bit of npm. Change-Id: Iea10d4068fa783ec0ddd6bcaba5c8d92b1a1168f
This commit is contained in:
Florian Klink
parent
2705517e6d
commit
91d8b86b39
55 changed files with 6205 additions and 0 deletions
10
web/content/docs/guides/_index.md
Normal file
10
web/content/docs/guides/_index.md
Normal file
|
|
@ -0,0 +1,10 @@
|
|||
---
|
||||
title: "Guides"
|
||||
description: ""
|
||||
summary: ""
|
||||
date: 2023-09-07T16:06:50+02:00
|
||||
lastmod: 2023-09-07T16:06:50+02:00
|
||||
draft: false
|
||||
weight: 10
|
||||
toc: true
|
||||
---
|
||||
73
web/content/docs/guides/building.md
Normal file
73
web/content/docs/guides/building.md
Normal file
|
|
@ -0,0 +1,73 @@
|
|||
---
|
||||
title: "Building Snix"
|
||||
slug: building
|
||||
description: ""
|
||||
summary: ""
|
||||
date: 2025-03-14T14:14:35+01:00
|
||||
lastmod: 2025-03-14T14:14:35+01:00
|
||||
draft: false
|
||||
weight: 11
|
||||
toc: true
|
||||
---
|
||||
|
||||
This document describes how to build the project locally, both for interactive
|
||||
development as well as referring to it from Nix code (for example, to run one of
|
||||
its binaries on your machine).
|
||||
|
||||
{{<callout>}}
|
||||
Please check the [Contribution Guide]({{< relref "contributing" >}}) on how to
|
||||
contribute after following this guide.
|
||||
{{</callout>}}
|
||||
|
||||
### Requirements
|
||||
- Ensure you have [Direnv][] installed and [hooked into your shell][direnv-inst].
|
||||
- Ensure you have [Nix][] installed.
|
||||
|
||||
### Getting the sources
|
||||
Snix is hosted in its own Forgejo instance, hosted on [git.snix.dev](https://git.snix.dev/snix/snix), and a
|
||||
(read-only) mirror on [GitHub](https://github.com/snix-project/snix).
|
||||
|
||||
Check out the source code as follows:
|
||||
|
||||
```console
|
||||
$ git clone https://git.snix.dev/snix-project/snix.git
|
||||
```
|
||||
|
||||
### Interactive development
|
||||
```console
|
||||
$ direnv allow
|
||||
$ mg shell //snix:shell
|
||||
```
|
||||
|
||||
This provides all the necessary tools and dependencies to interactively build
|
||||
the source code, using `cargo build` etc.
|
||||
|
||||
### Building only
|
||||
|
||||
It is also possible to build the different Snix crates with Nix,
|
||||
in which you don't need to enter the shell.
|
||||
From the root of the repository, you can build as follows:
|
||||
|
||||
```console
|
||||
$ nix-build -A snix.cli
|
||||
```
|
||||
|
||||
Alternatively, you can use the `mg` wrapper from anywhere in the repository (requires the direnv setup from above):
|
||||
|
||||
```console
|
||||
$ mg build //snix:cli
|
||||
```
|
||||
|
||||
This uses [crate2nix][] to build each crate dependency individually.
|
||||
|
||||
Checkout the [Component Overview]({{< ref "/docs/components/overview" >}})
|
||||
to learn more about the project structure.
|
||||
|
||||
|
||||
[Direnv]: https://direnv.net
|
||||
[direnv-inst]: https://direnv.net/docs/installation.html
|
||||
[Nix]: https://nixos.org/nix/
|
||||
[mg]: https://code.tvl.fyi/tree/tools/magrathea
|
||||
[crate2nix]: https://github.com/nix-community/crate2nix/
|
||||
|
||||
|
||||
127
web/content/docs/guides/contributing.md
Normal file
127
web/content/docs/guides/contributing.md
Normal file
|
|
@ -0,0 +1,127 @@
|
|||
---
|
||||
title: "Contributing"
|
||||
description: ""
|
||||
summary: ""
|
||||
date: 2025-03-14T14:14:35+01:00
|
||||
lastmod: 2025-03-14T14:14:35+01:00
|
||||
draft: false
|
||||
weight: 12
|
||||
toc: true
|
||||
---
|
||||
|
||||
You want to start contributing? Nice!
|
||||
|
||||
We do use [Gerrit](https://www.gerritcodereview.com) for Code Review.
|
||||
It allows a more granular review (per-commit granularity rather than PR
|
||||
granularity), as well as keeping track as how commits change over time.
|
||||
It greatly simplifies the review process, and leads to overall more high-quality
|
||||
contributions.
|
||||
|
||||
While it might initially look a bit intimidating, you hopefully will spend less
|
||||
time learning its workflow than writing actual Snix code.
|
||||
<svg xmlns="http://www.w3.org/2000/svg" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" class="icon icon-tabler icons-tabler-outline icon-tabler-mood-wink-2"><path stroke="none" d="M0 0h24v24H0z" fill="none"/><path d="M12 21a9 9 0 1 1 0 -18a9 9 0 0 1 0 18z" /><path d="M9 10h-.01" /><path d="M14.5 15a3.5 3.5 0 0 1 -5 0" /><path d="M15.5 8.5l-1.5 1.5l1.5 1.5" /></svg>
|
||||
|
||||
{{<callout>}}
|
||||
This assumes you have the repo already cloned and the necessary tools installed
|
||||
as described in [Building Snix]({{< relref "./building" >}}), so make sure you
|
||||
went through these instructions first.
|
||||
{{</callout>}}
|
||||
|
||||
### Creating a Gerrit account
|
||||
- Navigate to [our Gerrit instance][snix-gerrit]. Hit the "Sign in" button
|
||||
(which allows SSO with a GitHub account) [^1]
|
||||
- In the User settings, paste an SSH public key and hit the "Add New SSH key"
|
||||
button. [^2]
|
||||
- Alternatively, you can also create "HTTP Credentials" (though saving the HTTP
|
||||
password is messy).
|
||||
|
||||
### Update your git remote URL
|
||||
Instead of trying to push to Forgejo, reconfigure your git remote URL to
|
||||
interact with Gerrit directly.
|
||||
|
||||
Replace `$USER` with your `Username` shown in the Gerrit settings.
|
||||
|
||||
#### If using SSH authentication:
|
||||
```console
|
||||
$ git remote set-url origin "ssh://$USER@cl.snix.dev:29418/snix"
|
||||
```
|
||||
|
||||
|
||||
#### If using HTTP authentication:
|
||||
```console
|
||||
$ git remote set-url origin "https://$USER@cl.snix.dev/a/snix"
|
||||
```
|
||||
|
||||
<!-- TODO: fix replication to include refs/changes/… etc, and ensure it
|
||||
replicates fast enough, then update to --push only -->
|
||||
|
||||
### Install the commit-msg hook
|
||||
Gerrit uses a `commit-msg` hook to add a `Change-Id: …` field to each commit
|
||||
message if not present already. This allows Gerrit to identify new revisions /
|
||||
updates of old commits, and track them as new revisions of the same "CL" [^3].
|
||||
|
||||
To install the commit-msg hook, run the following from the repo root:
|
||||
|
||||
```console
|
||||
mkdir -p .git/hooks
|
||||
curl -Lo .git/hooks/commit-msg https://cl.snix.dev/tools/hooks/commit-msg
|
||||
chmod +x .git/hooks/commit-msg
|
||||
```
|
||||
|
||||
{{< callout context="tip" title="Did you know?" icon="outline/rocket" >}}
|
||||
Gerrit refuses receiving commits without these `Change-Id: …` fields.
|
||||
|
||||
If you already have some local commits without `Change-Id` field, `git commit
|
||||
--amend` them after installing the `commit-msg` hook to add them.
|
||||
{{< /callout >}}
|
||||
|
||||
### Push your changes
|
||||
Do some local changes, and push them to Gerrit as follows:
|
||||
|
||||
```console
|
||||
$ git push origin HEAD:refs/for/canon
|
||||
```
|
||||
|
||||
Gerrit will print links to newly created CLs to your terminal.
|
||||
|
||||
If you want to update/edit your CL, simply squash these changes into your local
|
||||
commit and push again.
|
||||
|
||||
### The Gerrit model
|
||||
If do not have experience with the Gerrit, consider reading the
|
||||
[<cite>Working with Gerrit: An example</cite>][Gerrit Walkthrough] or
|
||||
[<cite>Basic Gerrit Walkthrough — For GitHub Users</cite>][gerrit-for-github-users].
|
||||
|
||||
Some more tips:
|
||||
|
||||
* Assign a reviewer to review your changes.
|
||||
* React on comments and mark them as resolved once you did.
|
||||
* Comments are only "Drafts" (stored server-side) until you send them off.
|
||||
This can be done by the `Reply` button on the top, for example.
|
||||
* Once CI is green, it's up to the *Author* of the CL to submit, not the
|
||||
reviewer.
|
||||
If you want a bot to automatically submit in this case, you can add the
|
||||
`Autosubmit+1` label.
|
||||
* Rebase on `origin/canon` regularly. You cannot push if you still have an old
|
||||
version of a now-submitted CL in your git log.
|
||||
|
||||
{{< callout context="tip" title="Did you know?" icon="outline/rocket" >}}
|
||||
You can immediately assign reviewers and other fields while pushing a
|
||||
new/updated change, by adding it to the push URL.
|
||||
|
||||
```console
|
||||
$ git push origin HEAD:refs/for/canon%r=alice,cc=bob,l=Autosubmit+1,publish-comments
|
||||
```
|
||||
* will set `alice` as a reviewer
|
||||
* will set `bob` as CC
|
||||
* adds the `Autosubmit+1` label
|
||||
* publishes any outstanding draft comments
|
||||
{{< /callout >}}
|
||||
|
||||
|
||||
[snix-gerrit]: https://cl.snix.dev
|
||||
[Gerrit walkthrough]: https://gerrit-review.googlesource.com/Documentation/intro-gerrit-walkthrough.html
|
||||
[gerrit-for-github-users]: https://gerrit.wikimedia.org/r/Documentation/intro-gerrit-walkthrough-github.html
|
||||
[^1]: more SSO providers to come
|
||||
[^2]: currently, `ssh-*-sk` keytypes are not supported, so use an `ssh-ed25519` key.
|
||||
[^3]: abbreviation for "change list", and the review unit in Gerrit.
|
||||
37
web/content/docs/guides/use-as-library.md
Normal file
37
web/content/docs/guides/use-as-library.md
Normal file
|
|
@ -0,0 +1,37 @@
|
|||
---
|
||||
title: "Use as a library"
|
||||
slug: use-as-library
|
||||
description: ""
|
||||
summary: ""
|
||||
date: 2025-03-14T14:14:35+01:00
|
||||
lastmod: 2025-03-14T14:14:35+01:00
|
||||
draft: false
|
||||
weight: 13
|
||||
toc: true
|
||||
---
|
||||
|
||||
If you want to use (parts of) Snix in your own project, you can simply refer to
|
||||
it using cargo and specifying the git sources. `cargo` will pin the exact rev
|
||||
in `Cargo.lock`. See [The Cargo Book](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#specifying-dependencies-from-git-repositories) for details.
|
||||
|
||||
We do not publish to crates.io yet, due to the interfaces still being a bit
|
||||
in flux.
|
||||
|
||||
For example, to add `nix-compat`, exposing a lot of Nix data types and formats,
|
||||
add the following line to your `Cargo.toml`'s `[dependencies]`':
|
||||
|
||||
|
||||
```toml
|
||||
nix-compat = { git = "https://git.snix.dev/snix/snix.git" }
|
||||
```
|
||||
|
||||
|
||||
{{<callout>}}
|
||||
Keep in mind some crates have additional requirements on their environment.
|
||||
|
||||
For example, `snix-castore` and `snix-store` need to have access to a `protobuf`
|
||||
compiler and the proto defintions (setting `PROTO_ROOT` usually).
|
||||
`tvix-build` wants `TVIX_BUILD_SANDBOX_SHELL` to be set, etc.
|
||||
|
||||
Check each crates' `build.rs` scripts for details.
|
||||
{{</callout>}}
|
||||
Loading…
Add table
Add a link
Reference in a new issue