= Go

Currently, the primary binary produced by the `zilch` repository is a tool to
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
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. 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.

== 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]
----
Usage: zilch-cli-go [OPTION] [PACKAGE...]
Process the given module (or the current directory, if unspecified) and
output derivations for each package given on the command line (or all
executables in the module, if unspecified)

  -h, --help              Print this help message.
  -b, --build             Build the store paths, rather than show their
                          derivations.
  -L, --print-build-logs  Print derivation logs as they come in.
  -m, --module-dir DIR    The directory to use as root module.
  -r, --replace DIR       Replace the module specified by the go.mod
                          with this source directory, rather than using
                          the upstream module. Can be specified more
                          than once.

   --debug                Crash on the first error, rather than
                          continuing with the next package.
----