| <h2 id="cargo_rustdoc_name">NAME</h2> |
| <div class="sectionbody"> |
| <p>cargo-rustdoc - Build a package's documentation, using specified custom flags</p> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_rustdoc_synopsis">SYNOPSIS</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p><code>cargo rustdoc [<em>OPTIONS</em>] [-- <em>ARGS</em>]</code></p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_rustdoc_description">DESCRIPTION</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>The specified target for the current package (or package specified by <code>-p</code> if |
| provided) will be documented with the specified <em>ARGS</em> being passed to the |
| final rustdoc invocation. Dependencies will not be documented as part of this |
| command. Note that rustdoc will still unconditionally receive arguments such |
| as <code>-L</code>, <code>--extern</code>, and <code>--crate-type</code>, and the specified <em>ARGS</em> will simply |
| be added to the rustdoc invocation.</p> |
| </div> |
| <div class="paragraph"> |
| <p>See <a href="https://doc.rust-lang.org/rustdoc/index.html" class="bare">https://doc.rust-lang.org/rustdoc/index.html</a> for documentation on rustdoc |
| flags.</p> |
| </div> |
| <div class="paragraph"> |
| <p>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 the filters of <code>--lib</code>, <code>--bin</code>, etc, must be used to select which |
| target is compiled. |
| To pass flags to all rustdoc processes spawned by Cargo, use the |
| <code>RUSTDOCFLAGS</code> environment variable or the <code>build.rustdocflags</code> configuration |
| option.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_rustdoc_options">OPTIONS</h2> |
| <div class="sectionbody"> |
| <div class="sect2"> |
| <h3 id="cargo_rustdoc_documentation_options">Documentation Options</h3> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><strong>--open</strong></dt> |
| <dd> |
| <p>Open the docs in a browser after building them.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="cargo_rustdoc_package_selection">Package Selection</h3> |
| <div class="paragraph"> |
| <p>By default, the package in the current working directory is selected. The <code>-p</code> |
| flag can be used to choose a different package in a workspace.</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><strong>-p</strong> <em>SPEC</em></dt> |
| <dt class="hdlist1"><strong>--package</strong> <em>SPEC</em></dt> |
| <dd> |
| <p>The package to document. See <a href="commands/cargo-pkgid.html">cargo-pkgid(1)</a> for |
| the SPEC format.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="cargo_rustdoc_target_selection">Target Selection</h3> |
| <div class="paragraph"> |
| <p>When no target selection options are given, <code>cargo rustdoc</code> 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 skipped if they have |
| <code>required-features</code> that are missing.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Passing target selection flags will document only the |
| specified targets.</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><strong>--lib</strong></dt> |
| <dd> |
| <p>Document the package’s library.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--bin</strong> <em>NAME</em>…​</dt> |
| <dd> |
| <p>Document the specified binary. This flag may be specified multiple times.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--bins</strong></dt> |
| <dd> |
| <p>Document all binary targets.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--example</strong> <em>NAME</em>…​</dt> |
| <dd> |
| <p>Document the specified example. This flag may be specified multiple times.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--examples</strong></dt> |
| <dd> |
| <p>Document all example targets.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--test</strong> <em>NAME</em>…​</dt> |
| <dd> |
| <p>Document the specified integration test. This flag may be specified multiple |
| times.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--tests</strong></dt> |
| <dd> |
| <p>Document all targets in test mode that have the <code>test = true</code> 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 <code>test</code> flag in the |
| manifest settings for the target.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--bench</strong> <em>NAME</em>…​</dt> |
| <dd> |
| <p>Document the specified benchmark. This flag may be specified multiple times.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--benches</strong></dt> |
| <dd> |
| <p>Document all targets in benchmark mode that have the <code>bench = true</code> |
| 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 <code>bench</code> flag in the |
| manifest settings for the target.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--all-targets</strong></dt> |
| <dd> |
| <p>Document all targets. This is equivalent to specifying <code>--lib --bins |
| --tests --benches --examples</code>.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="cargo_rustdoc_feature_selection">Feature Selection</h3> |
| <div class="paragraph"> |
| <p>When no feature options are given, the <code>default</code> feature is activated for |
| every selected package.</p> |
| </div> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><strong>--features</strong> <em>FEATURES</em></dt> |
| <dd> |
| <p>Space or comma separated list of features to activate. These features only |
| apply to the current directory’s package. Features of direct dependencies |
| may be enabled with <code><dep-name>/<feature-name></code> syntax.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--all-features</strong></dt> |
| <dd> |
| <p>Activate all available features of all selected packages.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--no-default-features</strong></dt> |
| <dd> |
| <p>Do not activate the <code>default</code> feature of the current directory’s |
| package.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="cargo_rustdoc_compilation_options">Compilation Options</h3> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><strong>--target</strong> <em>TRIPLE</em></dt> |
| <dd> |
| <p>Document for the given architecture. The default is the host |
| architecture. The general format of the triple is |
| <code><arch><sub>-<vendor>-<sys>-<abi></code>. Run <code>rustc --print target-list</code> for a |
| list of supported targets.</p> |
| <div class="paragraph"> |
| <p>This may also be specified with the <code>build.target</code> |
| <a href="reference/config.html">config value</a>.</p> |
| </div> |
| </dd> |
| <dt class="hdlist1"><strong>--release</strong></dt> |
| <dd> |
| <p>Document optimized artifacts with the <code>release</code> profile. See the |
| <a href="#cargo_rustdoc_profiles">PROFILES</a> section for details on how this affects profile selection.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="cargo_rustdoc_output_options">Output Options</h3> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><strong>--target-dir</strong> <em>DIRECTORY</em></dt> |
| <dd> |
| <p>Directory for all generated artifacts and intermediate files. May also be |
| specified with the <code>CARGO_TARGET_DIR</code> environment variable, or the |
| <code>build.target-dir</code> <a href="reference/config.html">config value</a>. Defaults |
| to <code>target</code> in the root of the workspace.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="cargo_rustdoc_display_options">Display Options</h3> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><strong>-v</strong></dt> |
| <dt class="hdlist1"><strong>--verbose</strong></dt> |
| <dd> |
| <p>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 <code>term.verbose</code> |
| <a href="reference/config.html">config value</a>.</p> |
| </dd> |
| <dt class="hdlist1"><strong>-q</strong></dt> |
| <dt class="hdlist1"><strong>--quiet</strong></dt> |
| <dd> |
| <p>No output printed to stdout.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--color</strong> <em>WHEN</em></dt> |
| <dd> |
| <p>Control when colored output is used. Valid values:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>auto</code> (default): Automatically detect if color support is available on the |
| terminal.</p> |
| </li> |
| <li> |
| <p><code>always</code>: Always display colors.</p> |
| </li> |
| <li> |
| <p><code>never</code>: Never display colors.</p> |
| </li> |
| </ul> |
| </div> |
| <div class="paragraph"> |
| <p>May also be specified with the <code>term.color</code> |
| <a href="reference/config.html">config value</a>.</p> |
| </div> |
| </dd> |
| <dt class="hdlist1"><strong>--message-format</strong> <em>FMT</em></dt> |
| <dd> |
| <p>The output format for diagnostic messages. Valid values:</p> |
| <div class="ulist"> |
| <ul> |
| <li> |
| <p><code>human</code> (default): Display in a human-readable text format.</p> |
| </li> |
| <li> |
| <p><code>json</code>: Emit JSON messages to stdout.</p> |
| </li> |
| <li> |
| <p><code>short</code>: Emit shorter, human-readable text messages.</p> |
| </li> |
| </ul> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="cargo_rustdoc_manifest_options">Manifest Options</h3> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><strong>--manifest-path</strong> <em>PATH</em></dt> |
| <dd> |
| <p>Path to the <code>Cargo.toml</code> file. By default, Cargo searches in the current |
| directory or any parent directory for the <code>Cargo.toml</code> file.</p> |
| </dd> |
| <dt class="hdlist1"><strong>--frozen</strong></dt> |
| <dt class="hdlist1"><strong>--locked</strong></dt> |
| <dd> |
| <p>Either of these flags requires that the <code>Cargo.lock</code> file is |
| up-to-date. If the lock file is missing, or it needs to be updated, Cargo will |
| exit with an error. The <code>--frozen</code> flag also prevents Cargo from |
| attempting to access the network to determine if it is out-of-date.</p> |
| <div class="paragraph"> |
| <p>These may be used in environments where you want to assert that the |
| <code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network |
| access.</p> |
| </div> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="cargo_rustdoc_common_options">Common Options</h3> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><strong>-h</strong></dt> |
| <dt class="hdlist1"><strong>--help</strong></dt> |
| <dd> |
| <p>Prints help information.</p> |
| </dd> |
| <dt class="hdlist1"><strong>-Z</strong> <em>FLAG</em>…​</dt> |
| <dd> |
| <p>Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for |
| details.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| <div class="sect2"> |
| <h3 id="cargo_rustdoc_miscellaneous_options">Miscellaneous Options</h3> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1"><strong>-j</strong> <em>N</em></dt> |
| <dt class="hdlist1"><strong>--jobs</strong> <em>N</em></dt> |
| <dd> |
| <p>Number of parallel jobs to run. May also be specified with the |
| <code>build.jobs</code> <a href="reference/config.html">config value</a>. Defaults to |
| the number of CPUs.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_rustdoc_profiles">PROFILES</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>Profiles may be used to configure compiler options such as optimization levels |
| and debug settings. See |
| <a href="reference/manifest.html#the-profile-sections">the reference</a> |
| for more details.</p> |
| </div> |
| <div class="paragraph"> |
| <p>Profile selection depends on the target and crate being built. By default the |
| <code>dev</code> or <code>test</code> profiles are used. If the <code>--release</code> flag is given, then the |
| <code>release</code> or <code>bench</code> profiles are used.</p> |
| </div> |
| <table class="tableblock frame-all grid-all fit-content"> |
| <colgroup> |
| <col> |
| <col> |
| <col> |
| </colgroup> |
| <thead> |
| <tr> |
| <th class="tableblock halign-left valign-top">Target</th> |
| <th class="tableblock halign-left valign-top">Default Profile</th> |
| <th class="tableblock halign-left valign-top"><code>--release</code> Profile</th> |
| </tr> |
| </thead> |
| <tbody> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">lib, bin, example</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>dev</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>release</code></p></td> |
| </tr> |
| <tr> |
| <td class="tableblock halign-left valign-top"><p class="tableblock">test, bench, or any target<br> |
| in "test" or "bench" mode</p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>test</code></p></td> |
| <td class="tableblock halign-left valign-top"><p class="tableblock"><code>bench</code></p></td> |
| </tr> |
| </tbody> |
| </table> |
| <div class="paragraph"> |
| <p>Dependencies use the <code>dev</code>/<code>release</code> profiles.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_rustdoc_environment">ENVIRONMENT</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p>See <a href="reference/environment-variables.html">the reference</a> for |
| details on environment variables that Cargo reads.</p> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_rustdoc_exit_status">Exit Status</h2> |
| <div class="sectionbody"> |
| <div class="dlist"> |
| <dl> |
| <dt class="hdlist1">0</dt> |
| <dd> |
| <p>Cargo succeeded.</p> |
| </dd> |
| <dt class="hdlist1">101</dt> |
| <dd> |
| <p>Cargo failed to complete.</p> |
| </dd> |
| </dl> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_rustdoc_examples">EXAMPLES</h2> |
| <div class="sectionbody"> |
| <div class="olist arabic"> |
| <ol class="arabic"> |
| <li> |
| <p>Build documentation with custom CSS included from a given file:</p> |
| <div class="literalblock"> |
| <div class="content"> |
| <pre>cargo rustdoc --lib -- --extend-css extra.css</pre> |
| </div> |
| </div> |
| </li> |
| </ol> |
| </div> |
| </div> |
| </div> |
| <div class="sect1"> |
| <h2 id="cargo_rustdoc_see_also">SEE ALSO</h2> |
| <div class="sectionbody"> |
| <div class="paragraph"> |
| <p><a href="commands/index.html">cargo(1)</a>, <a href="commands/cargo-doc.html">cargo-doc(1)</a>, <a href="https://doc.rust-lang.org/rustdoc/index.html">rustdoc(1)</a></p> |
| </div> |
| </div> |
| </div> |