= 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.