puck/zilch
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

docs: add example usage to the Go page.

Browse source
This commit is contained in:
puck 2024-10-04 03:55:46 +00:00
parent 144702f70c
commit cf5c770252
1 changed files with 34 additions and 3 deletions
Download patch file Download diff file Expand all files Collapse all files

37
docs/modules/ROOT/pages/go.adoc
View file

@ -1,7 +1,8 @@
= Go
Currently, the primary binary produced by the `zilch` repository is a tool to
generate content-addressed derivations from a Go project, called `zilch-cli-go`.
generate content-addressed derivations to incrementally build any Go project,
called `zilch-cli-go`.
It requires the `ca-derivations` and `impure-derivations` experimental features
to be enabled on the Nix daemon, and a Nix daemon to be available at the
@ -9,9 +10,39 @@ default store path. It also requires the daemon to be able to run
`x86_64-linux` derivations, right now.
Once run, it will use Zilch to build a series of derivations, and output a
`.drv` for each executable package in the module.
`.drv` for each executable package in the module. These derivations will then
incrementally build the source code: if a package's changes do not impact its
compatibility with the packages that depend on it, it will quickly notice and
skip building dependents, thanks to Nix.
The help page:
== Example usage
[source]
----
$ git clone https://github.com/tailscale/tailscale # tailscale.com
$ git clone https://go.googlesource.com/net x-net # golang.org/x/net
# build tailscale, but with the golang.org/x/net dependency replaced
# with the local checkout. this might take a few minutes, as it pulls in
# all dependencies one by one.
$ zilch-cli-go -m tailscale -r x-net tailscale.com/cmd/tailscaled
# use `--option substitute false', as there are a lot of paths to check
# against the binary cache otherwise
$ nix-build --option substitute false /nix/store/qj0dh4pdgldxkb798pj1f3fs5n1nwnx3-tailscale.com_cmd_tailscaled.drv
[.. change e.g. `GODEBUG` to `GODEBUG2` in `x-net/http2/http2.go` ..]
$ zilch-cli-go --module-dir tailscale --replace x-net tailscale.com/cmd/tailscaled
$ nix-build --option substitute false /nix/store/nm2ycs5zb7v2wdlwgy913apnd22gs4pn-tailscale.com_cmd_tailscaled.drv
----
Once `zilch-cli-go` returns, it returns a `.drv`, which, when built, will
incrementally build the changed modules. If a package has been changed without
impacting the exported functions too much, only it will be rebuilt, with all
packages that depend on it staying the same, and being skipped.
== Help page
[source]
----