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

(zilch lang go): document

Browse source 
Change-Id: I6a6a6964558b4fe2f96d78120b2e899f91d48c22
This commit is contained in:
puck 2025-06-23 12:22:20 +00:00
parent f0ce185d5c
commit 18f2887eba
13 changed files with 457 additions and 96 deletions
Download patch file Download diff file Expand all files Collapse all files

49
docs/modules/ROOT/pages/go/usage.adoc Normal file
View file

@ -0,0 +1,49 @@
= Usage
:page-pagination: next
Zilch supports compiling any Go code incrementally using `zilch-cli-go`, with
no special configuration needed on the part of the Go module being built:
[,console]
----
$ git clone https://github.com/tailscale/tailscale
$ zilch-cli-go --module-dir tailscale/ <1>
tailscale.com/client/tailscale/example/servetls /nix/store/727ci6sssga0pbi4aqb08vnhfvmh9nl0-tailscale.com_client_tailscale_example_servetls
tailscale.com/cmd/addlicense /nix/store/ckc5bx4s0c29sancd05asvhz0dy43xj7-tailscale.com_cmd_addlicense
…
tailscale.com/cmd/xdpderper /nix/store/8wn9w91mjipw1dzks4p3kcmkwcn18jp7-tailscale.com_cmd_xdpderper
$ zilch-cli-go --module-dir tailscale/ \
> tailscale.com/cmd/tailscaled <2>
tailscale.com/cmd/tailscaled /nix/store/hqrm0f8sd8sx54am921na25w8za67p3m-tailscale.com_cmd_tailscaled
----
<1> Building all binary packages in a module
<2> Building a specifically targeted package
Right now, the daemon has to be able to build `x86_64-linux` derivations,
and `zilch-cli-go` will only output statically linked amd64 binaries as well.
While running, all processing of the Go module, its dependencies, etc, are done
inside of Nix. Once all dependencies have been resolved, a series of Nix
derivations will be used to then build the requested packages. If any source
file's changes do not affect the way dependent packages use it, those packages
will not need rebuilding; only the final result will have to be re-linked.
== Replacing dependencies
As part of Zilch, it's also possible to quickly build a module with one of its
(transitive) dependencies replaced. This keeps the same guarantees as before:
Any changes made that do not involve the output changing will only need
relinking of the resulting binary. This is also very simple:
[,console]
----
$ git clone https://go.googlesource.com/net x-net # golang.org/x/net
$ zilch-cli-go --module-dir tailscale --replace x-net/ tailscale.com/cmd/tailscaled
…
tailscale.com/cmd/tailscaled /nix/store/hqrm0f8sd8sx54am921na25w8za67p3m-tailscale.com_cmd_tailscaled
----
After editing a file any of the replaced dependencies, if this package is used
in the final build, Zilch will apply early-cutoff where possible.