CARGO-RUSTDOC(1)

📦 version 1.76.0, in ubuntu jammy, ubuntu noble

💖 CARGO-RUSTDOC — the cargo subcommand that builds your docs 💖

okay bestie, welcome to cargo-rustdoc, straight out of the General Commands Manual. this is the cargo command that builds a package's documentation, using specified custom flags ✨. she's the doc-building queen and she's about to spill everything, no gatekeeping 🫶

✨ SYNOPSIS ✨

cargo rustdoc [options] [-- args]

like, that's the whole vibe. options go before, and then -- args is where you slide in your custom rustdoc flags 🎀

🌸 DESCRIPTION 🌸

so here's the tea, bestie. the target you pick for the current package — or the package you point at with -p if you gave one — gets documented, and the args you specify get passed straight into the final rustdoc invocation. it's giving "you have the aux cord" 🎧

Important though: dependencies will not be documented as part of this command. only the target you selected. periodt.

and like, don't worry — rustdoc still unconditionally receives arguments such as -L, --extern, and --crate-type no matter what. your specified args are just simply added on top of the rustdoc invocation 💅

want the full rundown on rustdoc flags? it's all here: <https://doc.rust-lang.org/rustdoc/index.html> 📚

also lowkey crucial: this command requires that only one target is being compiled when additional arguments are provided. if more than one target is available for the current package, you gotta use the filters --lib, --bin, etc. to select which target is compiled. no multitasking here, one target at a time 👑

and if you want to pass flags to all rustdoc processes spawned by Cargo (not just this one), use the RUSTDOCFLAGS environment variable <https://doc.rust-lang.org/cargo/reference/environment-variables.html> or the build.rustdocflags config value <https://doc.rust-lang.org/cargo/reference/config.html>. that's the "apply to everyone" button fr fr 🌈

💅 OPTIONS 💅

📖 Documentation Options

  • --open — open the docs in a browser after building them. this uses your default browser unless you define another one in the BROWSER environment variable or use the doc.browser <https://doc.rust-lang.org/cargo/reference/config.html#docbrowser> configuration option. it's giving "build it and immediately show it off" 🦋

🎀 Package Selection

by default, the package in the current working directory is selected. the -p flag can be used to choose a different package in a workspace. main character energy for whichever package you point at ✨

  • -p spec, --package spec — the package to document. see cargo-pkgid(1) for the SPEC format. iykyk 👑

🎯 Target Selection

when no target selection options are given, cargo rustdoc will document all binary and library targets of the selected package. the binary will be skipped if its name is the same as the lib target. binaries are also skipped if they have required-features that are missing. so like, she curates for you automatically 💖

passing target selection flags will document only the specified targets.

⚠️ heads up bestie: --bin, --example, --test and --bench flags also support common Unix glob patterns like *, ? and []. BUT — to avoid your shell accidentally expanding glob patterns before Cargo handles them, you must use single quotes or double quotes around each glob pattern. otherwise your shell will eat them and cargo never even sees them 😭 no cap.
  • --lib — document the package's library. the classic 📚
  • --bin *name*… — document the specified binary. this flag may be specified multiple times and supports common Unix glob patterns. 🔥
  • --bins — document all binary targets. all of them, collectively, slay 💅
  • --example *name*… — document the specified example. this flag may be specified multiple times and supports common Unix glob patterns. ✨
  • --examples — document all example targets. every single one 🌸
  • --test *name*… — document the specified integration test. this flag may be specified multiple times and supports common Unix glob patterns. 🧚
  • --tests — document all targets in test mode that have the test = true manifest flag set. by default this includes the library and binaries built as unittests, and integration tests. be aware that this will also build any required dependencies, so the lib target may be built twice (once as a unittest, and once as a dependency for binaries, integration tests, etc.). targets may be enabled or disabled by setting the test flag in the manifest settings for the target. double the build, double the drama 🙈
  • --bench *name*… — document the specified benchmark. this flag may be specified multiple times and supports common Unix glob patterns. ⭐
  • --benches — document all targets in benchmark mode that have the bench = true manifest flag set. by default this includes the library and binaries built as benchmarks, and bench targets. be aware that this will also build any required dependencies, so the lib target may be built twice (once as a benchmark, and once as a dependency for binaries, benchmarks, etc.). targets may be enabled or disabled by setting the bench flag in the manifest settings for the target. same double-build situation, we love a consistent queen 💀
  • --all-targets — document all targets. this is equivalent to specifying --lib --bins --tests --benches --examples. the "everything, all at once" option 👑

🌈 Feature Selection

the feature flags let you control which features are enabled. when no feature options are given, the default feature is activated for every selected package. defaults are cute like that 💖

see the features documentation <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options> for more details.

  • -F features, --features features — space or comma separated list of features to activate. features of workspace members may be enabled with package-name/feature-name syntax. this flag may be specified multiple times, which enables all specified features. stack 'em up 🎀
  • --all-features — activate all available features of all selected packages. go big or go home 🔥
  • --no-default-features — do not activate the default feature of the selected packages. we're going rogue, no defaults today 💅

🛠️ Compilation Options

  • --target triple — document for the given architecture. the default is the host architecture. the general format of the triple is <arch><sub>-<vendor>-<sys>-<abi>. run rustc --print target-list for a list of supported targets. this flag may be specified multiple times.

this may also be specified with the build.target config value <https://doc.rust-lang.org/cargo/reference/config.html>.

note that specifying this flag makes Cargo run in a different mode where the target artifacts are placed in a separate directory. see the build cache <https://doc.rust-lang.org/cargo/guide/build-cache.html> documentation for more details. different directory, different vibe 🦋
  • -r, --release — document optimized artifacts with the release profile. see also the --profile option for choosing a specific profile by name. optimized and iconic ✨
  • --profile name — document with the given profile. see the reference <https://doc.rust-lang.org/cargo/reference/profiles.html> for more details on profiles. pick your fighter 🥊
  • --ignore-rust-version — document the target even if the selected Rust compiler is older than the required Rust version as configured in the project's rust-version field. ignoring the rules, living dangerously 😭
  • --timings=fmts — output information how long each compilation takes, and track concurrency information over time. accepts an optional comma-separated list of output formats; --timings without an argument will default to --timings=html. specifying an output format (rather than the default) is unstable and requires -Zunstable-options. valid output formats:
    • html (unstable, requires -Zunstable-options): write a human-readable file cargo-timing.html to the target/cargo-timings directory with a report of the compilation. also write a report to the same directory with a timestamp in the filename if you want to look at older runs. HTML output is suitable for human consumption only, and does not provide machine-readable timing data. pretty colors for the humans only 💅
    • json (unstable, requires -Zunstable-options): emit machine-readable JSON information about timing information. for the robots 🤖

📦 Output Options

  • --target-dir directory — directory for all generated artifacts and intermediate files. may also be specified with the CARGO_TARGET_DIR environment variable, or the build.target-dir config value <https://doc.rust-lang.org/cargo/reference/config.html>. defaults to target in the root of the workspace. home sweet home 🏠

🗣️ Display Options

  • -v, --verbose — use verbose output. may be specified twice for "very verbose" output which includes extra output such as dependency warnings and build script output. may also be specified with the term.verbose config value <https://doc.rust-lang.org/cargo/reference/config.html>. the way that twice = extra chatty 😭
  • -q, --quiet — do not print cargo log messages. may also be specified with the term.quiet config value <https://doc.rust-lang.org/cargo/reference/config.html>. shhh, silence 🤫
  • --color when — control when colored output is used. valid values:
    • auto (default): automatically detect if color support is available on the terminal. 🎨
    • always: always display colors. rainbow mode on 🌈
    • never: never display colors. monochrome era 🖤

may also be specified with the term.color config value <https://doc.rust-lang.org/cargo/reference/config.html>.

  • --message-format fmt — the output format for diagnostic messages. can be specified multiple times and consists of comma-separated values. valid values:
    • human (default): display in a human-readable text format. conflicts with short and json. 👩💻
    • short: emit shorter, human-readable text messages. conflicts with human and json. ✂️
    • json: emit JSON messages to stdout. see the reference <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages> for more details. conflicts with human and short. 🤖
    • json-diagnostic-short: ensure the rendered field of JSON messages contains the "short" rendering from rustc. cannot be used with human or short. 📏
    • json-diagnostic-rendered-ansi: ensure the rendered field of JSON messages contains embedded ANSI color codes for respecting rustc's default color scheme. cannot be used with human or short. 🌈
    • json-render-diagnostics: instruct Cargo to not include rustc diagnostics in JSON messages printed, but instead Cargo itself should render the JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others coming from rustc are still emitted. cannot be used with human or short. the "cargo takes the wheel" option 🚗

📜 Manifest Options

  • --manifest-path path — path to the Cargo.toml file. by default, Cargo searches for the Cargo.toml file in the current directory or any parent directory. it'll find it, she's thorough 🔍
  • --frozen, --locked — either of these flags requires that the Cargo.lock file is up-to-date. if the lock file is missing, or it needs to be updated, Cargo will exit with an error. the --frozen flag also prevents Cargo from attempting to access the network to determine if it is out-of-date.

these may be used in environments where you want to assert that the Cargo.lock file is up-to-date (such as a CI build) or want to avoid network access. CI besties, this one's for you 🫶

  • --offline — prevents Cargo from accessing the network for any reason. without this flag, Cargo will stop with an error if it needs to access the network and the network is not available. with this flag, Cargo will attempt to proceed without the network if possible. airplane mode but make it cargo ✈️

to be continued, bestie — part 2 is coming 💖

Beware, bestie — this can give you different dependency resolution than online mode does. Cargo will restrict itself to crates that are already downloaded locally, even if there might be a newer version as indicated in the local copy of the index. So if you wanna go offline and still have everything you need, hit up the cargo-fetch(1) command first to download your dependencies. Prep work, periodt. 💅

You can also set this with the net.offline config value: https://doc.rust-lang.org/cargo/reference/config.html

🫶 Common Options 🫶

  • +toolchain — okay so if Cargo got installed with rustup, and the first argument to cargo starts with +, it gets read as a rustup toolchain name (think +stable or +nightly, iconic). Peep the rustup documentation for the whole story on how toolchain overrides work: https://rust-lang.github.io/rustup/overrides.html
  • --config KEY=VALUE or PATH — overrides a Cargo config value, slay. The argument should be in TOML syntax of KEY=VALUE, or you can hand it a path to an extra configuration file instead. This flag may be specified multiple times (stack 'em up, she's flexible ✨). More deets in the command-line overrides section: https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides
  • -C PATH — changes the current working directory before executing any specified operations. This affects things like where cargo looks by default for the project manifest (Cargo.toml), plus the directories searched for discovering .cargo/config.toml, for example. Heads up: this option must appear before the command name, like this:
cargo -C path/to/my-project build
Lowkey important: this one's only available on the nightly channel (https://doc.rust-lang.org/book/appendix-07-nightly-rust.html) and needs the -Z unstable-options flag to turn on (see #10098, https://github.com/rust-lang/cargo/issues/10098). No stable crumbs for this one, sorry babe. 😭
  • -h, --help — prints help information. The classic. 🫶
  • -Z flag — unstable (nightly-only) flags to Cargo. Run cargo -Z help for the full rundown, iykyk.

🌈 Miscellaneous Options 🌈

  • -j N, --jobs N — number of parallel jobs to run. You can also set this with the build.jobs config value: https://doc.rust-lang.org/cargo/reference/config.html. Defaults to the number of logical CPUs. If it's negative, it sets the maximum number of parallel jobs to the number of logical CPUs plus whatever value you provided. If a string default is provided, it sets the value back to defaults. And listen — it should not be 0. Not even once. 🙈
  • --keep-going — build as many crates in the dependency graph as possible, rather than aborting the build on the first one that fails to build. Main character energy: she does not stop for the drama. 👑

For example, if the current package depends on dependencies fails and works, one of which fails to build, cargo rustdoc -j1 may or may not build the one that succeeds (depending on which one of the two builds Cargo picked to run first), whereas cargo rustdoc -j1 --keep-going would definitely run both builds, even if the one run first fails. Consistency, we love to see it. ✨

🌸 ENVIRONMENT 🌸

See the reference for details on environment variables that Cargo reads: https://doc.rust-lang.org/cargo/reference/environment-variables.html

💖 EXIT STATUS 💖

  • 0: Cargo succeeded. 🎉 (the good ending)
  • 101: Cargo failed to complete. 💀 (the other ending)

✨ EXAMPLES ✨

  1. Build documentation with custom CSS included from a given file:
cargo rustdoc --lib -- --extend-css extra.css

🦋 SEE ALSO 🦋

cargo(1), cargo-doc(1), rustdoc(1)

And that's the whole page, bestie — you officially know cargo-rustdoc(1) now, no cap. 🎀 This one lives in the Cargo manual alongside all her sisters, so go be nosy in cargo(1) too. Go forth and document your crates, queen — you ate. 💅✨👑

📦 where this page comes from