From cf5c770252d25b377271032e565ef0a39812e3c3 Mon Sep 17 00:00:00 2001 From: Puck Meerburg Date: Fri, 4 Oct 2024 03:55:46 +0000 Subject: [PATCH] docs: add example usage to the Go page. --- docs/modules/ROOT/pages/go.adoc | 37 ++++++++++++++++++++++++++++++--- 1 file changed, 34 insertions(+), 3 deletions(-) diff --git a/docs/modules/ROOT/pages/go.adoc b/docs/modules/ROOT/pages/go.adoc index aed0576..213b01e 100644 --- a/docs/modules/ROOT/pages/go.adoc +++ b/docs/modules/ROOT/pages/go.adoc @@ -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] ----