(zilch lang rust): document

Change-Id: I6a6a6964c8aaff8d5f3e18bc5c7486746b5a2952

docs/modules/ROOT/pages/rust/usage.adoc

@@ -0,0 +1,76 @@
+= Usage
+:page-pagination: next
+
+Using `zilch-cli-rust`, you can compile Rust code incrementally crate-by-crate:
+
+[,console]
+----
+$ git clone https://github.com/BurntSushi/ripgrep
+
+$ zilch-cli-rust --crate-dir ripgrep/ <1>
+…
+ripgrep rg      bin     /nix/store/pxvqbn65lv2f4r3x1cszv5pr5l5mjwh9-rustc-bin-rg-link
+grep    grep    lib     not a binary
+grep-cli        grep_cli        lib     not a binary
+globset globset lib     not a binary
+…
+
+$ zilch-cli-rust --crate-dir ripgrep/ rg <2>
+…
+ripgrep rg      bin     /nix/store/pxvqbn65lv2f4r3x1cszv5pr5l5mjwh9-rustc-bin-rg-link
+----
+<1> Building all binary targets in a crate
+<2> Building a specifically targeted target in a crate
+
+Right now, the daemon has to be able to build `x86_64-linux` derivations, and
+only the `x86_64-unknown-linux-gnu` Rust target is supported.
+
+== Replacing dependencies
+As part of Zilch, it's also possible to quickly build a crate with one of its
+(transitive) dependencies replaced:
+
+[,console]
+----
+$ git clone https://github.com/BurntSushi/bstr
+$ zilch-cli-rust --crate-dir ripgrep/ --replace bstr/ rg
+…
+ripgrep rg      bin     /nix/store/6rf4r69sp8ijg2xrdglbnx8smphfg6fr-rustc-bin-rg-link
+----
+
+After editing a file any of the replaced dependencies, if this crate is used in
+the final build, Zilch will apply early-cutoff where possible.
+
+[IMPORTANT]
+.Limitations in dependency selection
+====
+Zilch will never select dependencies that aren't found in the lockfile of the
+primary crate. If there is no lockfile, or the dependencies have changed, it is
+necessary to manually run `cargo generate-lockfile` to make sure all
+dependencies can be found. See xref:./library.adoc#limits[The resolver's limitations] for more info.
+====
+
+== Build script overrides
+Many Rust projects use build scripts that require external dependencies. To add
+support for these, you can use a JSON file.
+
+This file consists of a JSON object, where the key is the name of a crate, and
+the value is an object with the following keys:
+
+- `buildScript`: Overrides to apply when executing the build script for this
+  crate
+- `buildScriptDependency`: Overrides to apply when executing the build script
+  for any crate that depends on this crate.
+- `rustc`: Environment variables to add to the `rustc` invocation for this
+  crate.
+
+Each of these keys contains a map of key to a Nix expression evaluated inside
+`nixpkgs`. If multiple overrides apply to a single crate, each value is
+concatenated, separated with a `:`. Zilch's runner supports `_zilch_pkgconfig`
+as an environment variable as special case to add both `lib/pkgconfig` and
+`share/pkgconfig`, as well as the paths inside all the `propagated-build-inputs`
+of each store path, making `pkg-config` work. See
+https://puck.moe/git/zilch/tree/cli/overrides.json[the default overrides] for
+more examples on real-life crates.
+
+If this mechanism is not expressive enough, it's possible to use Zilch's Rust
+support directly, as a Scheme library.