---
title: Rust documentation
description: Cache Cargo's per-crate documentation and shared search index on Unix
---
Kache can cache Rust documentation on Linux and macOS with Cargo versions that split rustdoc
into per-crate and shared-index steps. This requires unstable Cargo flags.
Plain `cargo doc` runs through the real rustdoc without caching.
## Toolchain compatibility
Cargo 1.99 emits `--write-doc-meta-dir` and `--read-doc-meta-dir` for these
flags, and current nightly toolchains are newer than 1.99. Kache does not
support those arguments yet, so documentation passes through on Rust 1.99 and
on any newer toolchain that passes them. Only an older Cargo that still uses
`--merge=none` and `--merge=finalize` reaches the cached modes below. Check the
recorded result before assuming a documentation build was cached.
## Enable the rustdoc wrapper
Run `kache init` on Unix. It installs compiler shims and points Cargo's
`build.rustdoc` at the `rustdoc` shim in `~/.local/lib/kache/shims`. It does
this only when Cargo's `rustc-wrapper` is Kache and `build.rustdoc` is not set.
An existing value stays, and `kache init --no-shell` skips the step.
`kache doctor` reports the setting under "cargo doc". For Nix-managed shims or
manual setup, point `build.rustdoc` at the `rustdoc` shim yourself; see
[Installation](/docs/getting-started/installation#nix).
Then build documentation:
```bash
RUSTC_BOOTSTRAP=1 cargo doc -Z rustdoc-depinfo -Z rustdoc-mergeable-info
```
`RUSTC_BOOTSTRAP=1` enables the unstable flags on a stable toolchain for this
command. If you already use nightly, run:
```bash
cargo +nightly doc -Z rustdoc-depinfo -Z rustdoc-mergeable-info
```
These flags depend on your Cargo and rustdoc versions. If the toolchain rejects
them, use ordinary `cargo doc`; documentation still builds, without caching.
## Verify reuse
Use the same source, toolchain, and documentation options in a second worktree
with a fresh target directory. Inspect `kache stats --last-build` for rustdoc
hits. Cargo skipping documentation already present in its target directory is
not a cache hit. The [quick start](/docs/getting-started/quick-start) shows how
to create the two worktrees.
## What is cached
Compatible Cargo versions run rustdoc with `--merge=none` for each crate, then `--merge=finalize`
for the shared search index. Kache caches both as output archives. Other
rustdoc modes pass through.
Windows has no Kache compiler shim generator, so this setup does not cache
`cargo doc` there.