rustdoc Command Line Arguments

Purpose and Scope

This page explains how to read the rustdoc command-line surface as a user-facing interface and how that surface is represented around the Rust repository. rustdoc is the documentation generator shipped with Rust. At the command line, it accepts a crate root or Markdown input and emits generated documentation, normally HTML assets under a documentation directory. The official rustdoc book presents the stable flags that users should rely on, while the repository also contains build-time shims and command wrappers that show how Rust’s own build system invokes rustdoc in controlled environments.

Sources: src/doc/rustdoc/src/command-line-arguments.md, src/bootstrap/src/bin/rustdoc.rs

The main distinction for readers is between direct rustdoc usage and repository-internal invocation. Direct usage is what most crate authors see: rustdoc src/lib.rs, optionally with flags such as --crate-name, --out-dir, --cfg, --extern, or --document-private-items. Repository-internal invocation happens during bootstrap, where Cargo is pointed at a shim named as rustdoc. That shim forwards user arguments, injects sysroot and environment configuration, and may add Rust-project-specific unstable documentation attributes for compiler crates. Those bootstrap details are useful for contributors, but they are not the same as the stable command-line contract documented for end users.

Sources: src/doc/rustdoc/src/command-line-arguments.md, src/bootstrap/src/bin/rustdoc.rs

Relevant Source Files

• src/doc/rustdoc/src/command-line-arguments.md — the rustdoc book chapter that lists stable command-line arguments, examples, and user-facing explanations for help, version, verbosity, output location, crate naming, privacy, dependency lookup, and configuration flags.
• src/doc/rustc/src/command-line-arguments.md — the rustc command-line reference used for shared compiler concepts such as --cfg, --check-cfg, library search paths, and dependency or linking terminology that rustdoc reuses when it drives compilation for documentation.
• src/doc/rustc/src/command-line-arguments/print-options.md — the rustc --print reference that explains compiler information queries such as crate names, sysroot, target libdir, host tuple, cfg values, targets, CPUs, features, relocation models, and related output behavior.
• compiler/rustc_codegen_ssa/src/back/command.rs — a backend command wrapper that records program arguments and environment settings before spawning a process, illustrating how compiler subsystems preserve and inspect constructed command lines.
• src/bootstrap/src/bin/rustdoc.rs — the bootstrap rustdoc shim that reads environment variables, forwards rustdoc arguments, injects sysroot and cfg flags, sets dynamic library paths, and optionally dumps the constructed command.
• src/build_helper/src/arg_file_command.rs — a build-helper wrapper around std::process::Command that stores arguments and switches to @argfile form when command lines approach platform limits.

User-Facing Command Surface

The rustdoc book starts with operational flags that answer basic questions: how to ask for help, how to identify the tool version, and how to make output more verbose. -h and --help print built-in help. The source notes an important nuance: some rustdoc flags are unstable, so the book page intentionally shows stable options, while --help may show more. -V and --version print version information, and -v or --verbose requests more output. When verbose mode is combined with version output, the example expands from a one-line version into details such as binary name, commit hash, host tuple, release, and LLVM version.

Sources: src/doc/rustdoc/src/command-line-arguments.md

$ rustdoc -h
$ rustdoc --help
$ rustdoc -V
$ rustdoc --verbose --version

The most common production-oriented flags affect where documentation goes and how the crate is named. -o and --out-dir redirect output away from the default doc directory in the current working directory. --crate-name overrides rustdoc’s default assumption that the crate name comes from the input file name. This matters because the crate name influences generated paths and page titles. A library documented as lib is often a sign that rustdoc was run directly against src/lib.rs without an explicit crate name, while Cargo-driven documentation normally supplies the package context for you.

Sources: src/doc/rustdoc/src/command-line-arguments.md

$ rustdoc src/lib.rs -o target/doc
$ rustdoc src/lib.rs --out-dir target/doc
$ rustdoc src/lib.rs --crate-name mycrate

Visibility is controlled by the --document-private-items flag. By default, rustdoc documents publicly reachable items, not every item present in the crate. The rustdoc documentation illustrates this with a public function that is documented and a private module containing a public function that is still unreachable and therefore omitted. With --document-private-items, rustdoc includes non-public items in generated documentation except items marked with #[doc(hidden)]; private items are shown with a lock icon. This flag is particularly useful for internal API review, compiler development, or workspace documentation where private module structure is part of the audience’s task.

Sources: src/doc/rustdoc/src/command-line-arguments.md

Dependency and configuration flags are where rustdoc’s relationship to rustc becomes visible. -L or --library-path gives rustdoc directories to search for dependencies. --extern specifies an exact dependency location, rather than only a search directory. --cfg passes conditional compilation values using the same values as rustc --cfg, and --check-cfg uses the same checking model as rustc --check-cfg. The rustc reference clarifies that --cfg activates configuration settings, while --check-cfg configures compile-time checking of expected configuration names and values so typos or stale conditions can be detected.

Sources: src/doc/rustdoc/src/command-line-arguments.md, src/doc/rustc/src/command-line-arguments.md

$ rustdoc src/lib.rs -L target/debug/deps
$ rustdoc src/lib.rs --extern lazy-static=/path/to/lazy-static
$ rustdoc src/lib.rs --cfg feature="foo"
$ rustdoc src/lib.rs --check-cfg='cfg(my_cfg, values("foo", "bar"))'

Shared rustc Concepts

Although rustdoc is a documentation tool, it still needs compiler concepts because it analyzes Rust crates. The rustc command-line reference documents --cfg as a way to configure conditional compilation and gives examples such as a bare identifier or a key-value form like feature="serde". It documents --check-cfg as expected-configuration checking rather than activation. That distinction is important when troubleshooting documentation builds: a missing --cfg can hide code from rustdoc, while a missing --check-cfg expectation can produce warnings about names or values that the build intended to allow.

Sources: src/doc/rustc/src/command-line-arguments.md

Library search behavior also comes from the compiler side. The rustc reference describes -L as adding a directory to the library search path and supports optional search-path kinds such as dependency, crate, native, framework, and all. The rustdoc page presents its stable -L and --library-path forms from the documentation user’s perspective: rustdoc needs to know where dependencies are. When diagnosing a rustdoc run that succeeds under Cargo but fails when invoked manually, compare the library paths and --extern entries Cargo would have supplied with the direct command you typed.

Sources: src/doc/rustdoc/src/command-line-arguments.md, src/doc/rustc/src/command-line-arguments.md

The rustc --print reference is not a rustdoc command-line page, but it explains information queries that often appear when tooling computes the environment for compiler-like commands. It documents outputs such as crate-name, sysroot, target-libdir, host-tuple, cfg, target-list, target-cpus, target-features, relocation models, code models, TLS models, and native static libraries. These are useful adjacent concepts when a build system prepares rustdoc inputs for a specific target or sysroot, because documentation generation must resolve the same crate graph and target configuration as compilation.

Sources: src/doc/rustc/src/command-line-arguments/print-options.md

Bootstrap rustdoc Invocation

Inside the Rust repository, src/bootstrap/src/bin/rustdoc.rs is a shim passed to Cargo as the rustdoc executable during bootstrap. It reads the original arguments with env::args_os().skip(1), then obtains stage and verbosity using shared helper functions. It requires environment variables named RUSTDOC_REAL, RUSTDOC_LIBDIR, and RUSTC_SYSROOT. The real rustdoc executable is wrapped in an ArgFileCommand, so the shim can accumulate arguments before deciding how to spawn the process. This design lets bootstrap add repository-specific context without changing every Cargo invocation by hand.

Sources: src/bootstrap/src/bin/rustdoc.rs, src/build_helper/src/arg_file_command.rs

The shim treats --target as a signal that the rustdoc invocation is target-oriented rather than host-build-script-oriented. If a target is present, it ensures --sysroot is passed unless one is already present. If no target is present, it may read host flags from RUSTC_HOST_FLAGS and append them. In both cases, the original rustdoc arguments are forwarded afterward. This ordering matters because bootstrap wants to supply necessary defaults while still respecting explicit user or Cargo-provided arguments, especially for sysroot-sensitive documentation builds.

Sources: src/bootstrap/src/bin/rustdoc.rs

The same shim configures dynamic library lookup by prepending RUSTDOC_LIBDIR to the dynamic library path and storing it in the platform-specific path variable. It also handles Rust-repository-specific behavior: if RUSTC_FORCE_UNSTABLE is set, it appends -Z force-unstable-if-unmarked; if the stage is zero, it appends --cfg=bootstrap. For crates whose name starts with rustc_, it adds crate attributes for the Rust logo, nightly compiler documentation root URL, and, except for rustc_proc_macro, the rustdoc_internals feature. These are bootstrap implementation details, not general stable rustdoc flags.

Sources: src/bootstrap/src/bin/rustdoc.rs

When verbosity is high, the bootstrap shim prints the constructed rustdoc command, the dynamic library path setting, the sysroot, and the libdir before spawning the command. It then exits with the child status code or panics if spawning fails. For contributors, this is the practical debugging hook: increase bootstrap verbosity and inspect the exact rustdoc command after all shim additions. That is often clearer than guessing which layer supplied a flag, because the shim is the point where Cargo’s rustdoc arguments, bootstrap host flags, sysroot injection, dynamic library paths, and Rust-specific crate attributes come together.

Sources: src/bootstrap/src/bin/rustdoc.rs

Command Construction and Argument Files

The build helper ArgFileCommand exists because very long command lines can hit operating-system limits, especially on Windows. It deliberately resembles std::process::Command: callers can add arg, args, environment variables, removed environment variables, current directory, and stdin. The wrapper stores arguments separately until build() is called. If the total argument length is below the platform threshold, it appends them directly to the underlying command. If the arguments are too long, it writes them to a temporary file and passes a single @path argument instead.

Sources: src/build_helper/src/arg_file_command.rs

The thresholds are platform-specific. On Windows, the helper cuts off at roughly 30 KB, leaving room below the hard command-line limit. On Unix, it reads ARG_MAX from the environment when available and otherwise uses a one-megabyte default. The helper also validates arg-file contents: arguments must be valid UTF-8 and cannot contain newlines, because each argument is written on its own line. The returned temporary file is kept alive by the caller until after the command runs; the bootstrap rustdoc shim explicitly drops it only after spawning completes.

Sources: src/build_helper/src/arg_file_command.rs, src/bootstrap/src/bin/rustdoc.rs

A related compiler-side pattern appears in compiler/rustc_codegen_ssa/src/back/command.rs. That module wraps std::process::Command so compiler backends can build a command while retaining access to accumulated arguments. It supports normal programs, command scripts, and LLD invocations with an inserted -flavor argument. It stores arguments, environment additions, environment removals, and an environment-clear flag, then materializes a real process command. The wrapper’s get_args and take_args methods show why retaining the argument list is useful: diagnostics and spawn-limit handling often need to inspect the command before execution.

Sources: compiler/rustc_codegen_ssa/src/back/command.rs

Compact Reference

Practical Workflow

For ordinary crate documentation, start with Cargo when possible because Cargo supplies crate names, dependency paths, and extern mappings automatically. Use direct rustdoc invocation when you need to inspect a single crate root, document a Markdown file, or reproduce a documentation issue outside Cargo. Add --crate-name when generated paths or titles matter, add --out-dir when the default doc directory is not appropriate, and add --document-private-items only when the intended audience needs internal APIs. If cfg-dependent code is missing or unexpectedly included, compare the --cfg and --check-cfg values used for compilation and documentation.

Sources: src/doc/rustdoc/src/command-line-arguments.md, src/doc/rustc/src/command-line-arguments.md

For Rust repository contributors, inspect the bootstrap layer before assuming a rustdoc bug. The shim may inject sysroot, bootstrap cfg, host flags, dynamic library paths, unstable flags, and rustc crate documentation attributes. At high verbosity it prints the final command, which is the best evidence for reproducing failures. If the command is extremely long, remember that ArgFileCommand may replace the visible argument list with an @argfile; the file exists only while the command is being run. Next, read the rustdoc overview for generation concepts, the rustc command-line page for shared compiler flags, and the bootstrap build documentation for source-tree build behavior.

Sources: src/bootstrap/src/bin/rustdoc.rs, src/build_helper/src/arg_file_command.rs