docs: More samples.

Change-Id: Ibcab3b04ae1650cd213a5a0915b7c6056a6a6964

docs/modules/ROOT/pages/samples/2-rust.adoc

@@ -0,0 +1,67 @@
+= 2: Rust
+:page-pagination:
+
+This sample assumes you've tried the Go example, as the Rust implementation of
+these concepts work identically. This example dives into the details of the
+overrides, which are necessary to run Rust builds in a minimal sandbox.
+
+Most Rust projects depend on external dependencies, written in e.g. C, and
+cannot be compiled with purely `rustc` inside a sandbox. To allow for this,
+Zilch's Rust support has been designed with this fact in mind.
+
+If we try to compile the example in this directory as-is, it fails, as the
+crate depends on `pyo3`, which depends on a working Python interpreter:
+
+[,console]
+----
+$ zilch-cli-rust -m examples/rust
+…
+Error: (error Error 0 builder for '/nix/store/n5l4w8m3fj3m1s06p75r0pqj8s9l8cmf-build.rs-run.drv' failed with exit code 101;
+last 17 log lines:
+> error: no Python 3.x interpreter found
+
+…
+> Package: pyo3-build-config
+> note: run with `RUST_BACKTRACE=1` environment variable to display a backtrace
+----
+
+To fix this, we'll need to write an override file. This file describes to Zilch
+how to override the Rust environment. There's three override points, as described
+in xref:rust/usage.adoc[the more direct usage file]. We'll only use `buildScript`
+here, as `pyo3` is simple. Looking at the code, it seems that it expects a `python3`
+on `PATH`. To do this, we just need to write a fragment for that. Zilch knows how
+to append to these variables, so all we need is a file that contains the following:
+
+.zilch-override.json
+[,json]
+----
+{
+  "pyo3-build-config": {
+    "buildScript": {
+      "PATH": "${pkgs.python3}/bin"
+    }
+  }
+}
+----
+
+Now, when the `build.rs` for `pyo3-build-config` is run, it will have `python3`
+available to it. The output that this build script generates, which is stored
+in the Nix store, also has references to the parts of `python3` that the build
+script used, ensuring that it is properly passed through to the crates that, in
+turn, depend on this build script; and the final binary has references to not
+just libc, but also python3:
+
+[,console]
+----
+$ zilch-cli-rust -m examples/rust -z override.json
+zilch-pyo3-example      zilch_pyo3_example      bin     /nix/store/vqpj68dgswf8v64sq45banq6vn0fshnz-rustc-bin-zilch_pyo3_example-link
+
+$ nix-store -qR /nix/store/vqpj68dgswf8v64sq45banq6vn0fshnz-rustc-bin-zilch_pyo3_example-link | grep python
+/nix/store/cfapjd2rvqrpry4grb0kljnp8bvnvfxz-python3-3.13.8
+
+# hooray!
+----
+
+Zilch ships with a series of overrides, primarily around what I (the developer)
+have come across. Some of these also use a helper that Zilch provides, which
+sets up `pkg-config` based packages recursively, the same way Nixpkgs does.