6 cargo-doc - Build a package's documentation
10 `cargo doc` [_options_]
14 Build the documentation for the local package and all dependencies. The output
15 is placed in `target/doc` in rustdoc's usual format.
19 ### Documentation Options
23 <dt class="option-term" id="option-cargo-doc---open"><a class="option-anchor" href="#option-cargo-doc---open"></a><code>--open</code></dt>
24 <dd class="option-desc">Open the docs in a browser after building them. This will use your default
25 browser unless you define another one in the <code>BROWSER</code> environment variable.</dd>
28 <dt class="option-term" id="option-cargo-doc---no-deps"><a class="option-anchor" href="#option-cargo-doc---no-deps"></a><code>--no-deps</code></dt>
29 <dd class="option-desc">Do not build documentation for dependencies.</dd>
32 <dt class="option-term" id="option-cargo-doc---document-private-items"><a class="option-anchor" href="#option-cargo-doc---document-private-items"></a><code>--document-private-items</code></dt>
33 <dd class="option-desc">Include non-public items in the documentation.</dd>
40 By default, when no package selection options are given, the packages selected
41 depend on the selected manifest file (based on the current working directory if
42 `--manifest-path` is not given). If the manifest is the root of a workspace then
43 the workspaces default members are selected, otherwise only the package defined
44 by the manifest will be selected.
46 The default members of a workspace can be set explicitly with the
47 `workspace.default-members` key in the root manifest. If this is not set, a
48 virtual workspace will include all workspace members (equivalent to passing
49 `--workspace`), and a non-virtual workspace will include only the root crate itself.
53 <dt class="option-term" id="option-cargo-doc--p"><a class="option-anchor" href="#option-cargo-doc--p"></a><code>-p</code> <em>spec</em>...</dt>
54 <dt class="option-term" id="option-cargo-doc---package"><a class="option-anchor" href="#option-cargo-doc---package"></a><code>--package</code> <em>spec</em>...</dt>
55 <dd class="option-desc">Document only the specified packages. See <a href="https://doc.rust-lang.org/cargo/commands/cargo-pkgid.md">cargo-pkgid(1)</a> for the
56 SPEC format. This flag may be specified multiple times.</dd>
59 <dt class="option-term" id="option-cargo-doc---workspace"><a class="option-anchor" href="#option-cargo-doc---workspace"></a><code>--workspace</code></dt>
60 <dd class="option-desc">Document all members in the workspace.</dd>
64 <dt class="option-term" id="option-cargo-doc---all"><a class="option-anchor" href="#option-cargo-doc---all"></a><code>--all</code></dt>
65 <dd class="option-desc">Deprecated alias for <code>--workspace</code>.</dd>
69 <dt class="option-term" id="option-cargo-doc---exclude"><a class="option-anchor" href="#option-cargo-doc---exclude"></a><code>--exclude</code> <em>SPEC</em>...</dt>
70 <dd class="option-desc">Exclude the specified packages. Must be used in conjunction with the
71 <code>--workspace</code> flag. This flag may be specified multiple times.</dd>
79 When no target selection options are given, `cargo doc` will document all
80 binary and library targets of the selected package. The binary will be skipped
81 if its name is the same as the lib target. Binaries are skipped if they have
82 `required-features` that are missing.
84 The default behavior can be changed by setting `doc = false` for the target in
85 the manifest settings. Using target selection options will ignore the `doc`
86 flag and will always document the given target.
89 <dt class="option-term" id="option-cargo-doc---lib"><a class="option-anchor" href="#option-cargo-doc---lib"></a><code>--lib</code></dt>
90 <dd class="option-desc">Document the package's library.</dd>
93 <dt class="option-term" id="option-cargo-doc---bin"><a class="option-anchor" href="#option-cargo-doc---bin"></a><code>--bin</code> <em>name</em>...</dt>
94 <dd class="option-desc">Document the specified binary. This flag may be specified multiple times.</dd>
97 <dt class="option-term" id="option-cargo-doc---bins"><a class="option-anchor" href="#option-cargo-doc---bins"></a><code>--bins</code></dt>
98 <dd class="option-desc">Document all binary targets.</dd>
103 ### Feature Selection
105 The feature flags allow you to control the enabled features for the "current"
106 package. The "current" package is the package in the current directory, or the
107 one specified in `--manifest-path`. If running in the root of a virtual
108 workspace, then the default features are selected for all workspace members,
109 or all features if `--all-features` is specified.
111 When no feature options are given, the `default` feature is activated for
112 every selected package.
116 <dt class="option-term" id="option-cargo-doc---features"><a class="option-anchor" href="#option-cargo-doc---features"></a><code>--features</code> <em>features</em></dt>
117 <dd class="option-desc">Space or comma separated list of features to activate. These features only
118 apply to the current directory's package. Features of direct dependencies
119 may be enabled with <code><dep-name>/<feature-name></code> syntax. This flag may be
120 specified multiple times, which enables all specified features.</dd>
123 <dt class="option-term" id="option-cargo-doc---all-features"><a class="option-anchor" href="#option-cargo-doc---all-features"></a><code>--all-features</code></dt>
124 <dd class="option-desc">Activate all available features of all selected packages.</dd>
127 <dt class="option-term" id="option-cargo-doc---no-default-features"><a class="option-anchor" href="#option-cargo-doc---no-default-features"></a><code>--no-default-features</code></dt>
128 <dd class="option-desc">Do not activate the <code>default</code> feature of the current directory's package.</dd>
134 ### Compilation Options
138 <dt class="option-term" id="option-cargo-doc---target"><a class="option-anchor" href="#option-cargo-doc---target"></a><code>--target</code> <em>triple</em></dt>
139 <dd class="option-desc">Document for the given architecture. The default is the host
140 architecture. The general format of the triple is
141 <code><arch><sub>-<vendor>-<sys>-<abi></code>. Run <code>rustc --print target-list</code> for a
142 list of supported targets.</p>
143 <p>This may also be specified with the <code>build.target</code>
144 <a href="https://doc.rust-lang.org/cargo/reference/config.html">config value</a>.</p>
145 <p>Note that specifying this flag makes Cargo run in a different mode where the
146 target artifacts are placed in a separate directory. See the
147 <a href="https://doc.rust-lang.org/cargo/guide/build-cache.html">build cache</a> documentation for more details.</dd>
151 <dt class="option-term" id="option-cargo-doc---release"><a class="option-anchor" href="#option-cargo-doc---release"></a><code>--release</code></dt>
152 <dd class="option-desc">Document optimized artifacts with the <code>release</code> profile. See the
153 <a href="#profiles">PROFILES</a> section for details on how this affects profile
163 <dt class="option-term" id="option-cargo-doc---target-dir"><a class="option-anchor" href="#option-cargo-doc---target-dir"></a><code>--target-dir</code> <em>directory</em></dt>
164 <dd class="option-desc">Directory for all generated artifacts and intermediate files. May also be
165 specified with the <code>CARGO_TARGET_DIR</code> environment variable, or the
166 <code>build.target-dir</code> <a href="https://doc.rust-lang.org/cargo/reference/config.html">config value</a>. Defaults
167 to <code>target</code> in the root of the workspace.</dd>
175 <dt class="option-term" id="option-cargo-doc--v"><a class="option-anchor" href="#option-cargo-doc--v"></a><code>-v</code></dt>
176 <dt class="option-term" id="option-cargo-doc---verbose"><a class="option-anchor" href="#option-cargo-doc---verbose"></a><code>--verbose</code></dt>
177 <dd class="option-desc">Use verbose output. May be specified twice for "very verbose" output which
178 includes extra output such as dependency warnings and build script output.
179 May also be specified with the <code>term.verbose</code>
180 <a href="https://doc.rust-lang.org/cargo/reference/config.html">config value</a>.</dd>
183 <dt class="option-term" id="option-cargo-doc--q"><a class="option-anchor" href="#option-cargo-doc--q"></a><code>-q</code></dt>
184 <dt class="option-term" id="option-cargo-doc---quiet"><a class="option-anchor" href="#option-cargo-doc---quiet"></a><code>--quiet</code></dt>
185 <dd class="option-desc">No output printed to stdout.</dd>
188 <dt class="option-term" id="option-cargo-doc---color"><a class="option-anchor" href="#option-cargo-doc---color"></a><code>--color</code> <em>when</em></dt>
189 <dd class="option-desc">Control when colored output is used. Valid values:</p>
191 <li><code>auto</code> (default): Automatically detect if color support is available on the
193 <li><code>always</code>: Always display colors.</li>
194 <li><code>never</code>: Never display colors.</li>
196 <p>May also be specified with the <code>term.color</code>
197 <a href="https://doc.rust-lang.org/cargo/reference/config.html">config value</a>.</dd>
201 <dt class="option-term" id="option-cargo-doc---message-format"><a class="option-anchor" href="#option-cargo-doc---message-format"></a><code>--message-format</code> <em>fmt</em></dt>
202 <dd class="option-desc">The output format for diagnostic messages. Can be specified multiple times
203 and consists of comma-separated values. Valid values:</p>
205 <li><code>human</code> (default): Display in a human-readable text format.</li>
206 <li><code>short</code>: Emit shorter, human-readable text messages.</li>
207 <li><code>json</code>: Emit JSON messages to stdout. See
208 <a href="https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages">the reference</a>
209 for more details.</li>
210 <li><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains
211 the "short" rendering from rustc.</li>
212 <li><code>json-diagnostic-rendered-ansi</code>: Ensure the <code>rendered</code> field of JSON messages
213 contains embedded ANSI color codes for respecting rustc's default color
215 <li><code>json-render-diagnostics</code>: Instruct Cargo to not include rustc diagnostics in
216 in JSON messages printed, but instead Cargo itself should render the
217 JSON diagnostics coming from rustc. Cargo's own JSON diagnostics and others
218 coming from rustc are still emitted.</li>
227 <dt class="option-term" id="option-cargo-doc---manifest-path"><a class="option-anchor" href="#option-cargo-doc---manifest-path"></a><code>--manifest-path</code> <em>path</em></dt>
228 <dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the
229 <code>Cargo.toml</code> file in the current directory or any parent directory.</dd>
233 <dt class="option-term" id="option-cargo-doc---frozen"><a class="option-anchor" href="#option-cargo-doc---frozen"></a><code>--frozen</code></dt>
234 <dt class="option-term" id="option-cargo-doc---locked"><a class="option-anchor" href="#option-cargo-doc---locked"></a><code>--locked</code></dt>
235 <dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is
236 up-to-date. If the lock file is missing, or it needs to be updated, Cargo will
237 exit with an error. The <code>--frozen</code> flag also prevents Cargo from
238 attempting to access the network to determine if it is out-of-date.</p>
239 <p>These may be used in environments where you want to assert that the
240 <code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network
244 <dt class="option-term" id="option-cargo-doc---offline"><a class="option-anchor" href="#option-cargo-doc---offline"></a><code>--offline</code></dt>
245 <dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this
246 flag, Cargo will stop with an error if it needs to access the network and
247 the network is not available. With this flag, Cargo will attempt to
248 proceed without the network if possible.</p>
249 <p>Beware that this may result in different dependency resolution than online
250 mode. Cargo will restrict itself to crates that are downloaded locally, even
251 if there might be a newer version as indicated in the local copy of the index.
252 See the <a href="https://doc.rust-lang.org/cargo/commands/cargo-fetch.md">cargo-fetch(1)</a> command to download dependencies before going
254 <p>May also be specified with the <code>net.offline</code> <a href="https://doc.rust-lang.org/cargo/reference/config.html">config value</a>.</dd>
263 <dt class="option-term" id="option-cargo-doc-+toolchain"><a class="option-anchor" href="#option-cargo-doc-+toolchain"></a><code>+</code><em>toolchain</em></dt>
264 <dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code>
265 begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such
266 as <code>+stable</code> or <code>+nightly</code>).
267 See the <a href="https://github.com/rust-lang/rustup/">rustup documentation</a>
268 for more information about how toolchain overrides work.</dd>
271 <dt class="option-term" id="option-cargo-doc--h"><a class="option-anchor" href="#option-cargo-doc--h"></a><code>-h</code></dt>
272 <dt class="option-term" id="option-cargo-doc---help"><a class="option-anchor" href="#option-cargo-doc---help"></a><code>--help</code></dt>
273 <dd class="option-desc">Prints help information.</dd>
276 <dt class="option-term" id="option-cargo-doc--Z"><a class="option-anchor" href="#option-cargo-doc--Z"></a><code>-Z</code> <em>flag</em></dt>
277 <dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd>
283 ### Miscellaneous Options
286 <dt class="option-term" id="option-cargo-doc--j"><a class="option-anchor" href="#option-cargo-doc--j"></a><code>-j</code> <em>N</em></dt>
287 <dt class="option-term" id="option-cargo-doc---jobs"><a class="option-anchor" href="#option-cargo-doc---jobs"></a><code>--jobs</code> <em>N</em></dt>
288 <dd class="option-desc">Number of parallel jobs to run. May also be specified with the
289 <code>build.jobs</code> <a href="https://doc.rust-lang.org/cargo/reference/config.html">config value</a>. Defaults to
290 the number of CPUs.</dd>
297 Profiles may be used to configure compiler options such as optimization levels
298 and debug settings. See [the reference](../reference/profiles.html) for more
301 Profile selection depends on the target and crate being built. By default the
302 `dev` or `test` profiles are used. If the `--release` flag is given, then the
303 `release` or `bench` profiles are used.
305 Target | Default Profile | `--release` Profile
306 -------|-----------------|---------------------
307 lib, bin, example | `dev` | `release`
308 test, bench, or any target in "test" or "bench" mode | `test` | `bench`
310 Dependencies use the `dev`/`release` profiles.
315 See [the reference](../reference/environment-variables.html) for
316 details on environment variables that Cargo reads.
321 * `0`: Cargo succeeded.
322 * `101`: Cargo failed to complete.
327 1. Build the local package documentation and its dependencies and output to
333 [cargo(1)](cargo.md), [cargo-rustdoc(1)](cargo-rustdoc.md), [rustdoc(1)](https://doc.rust-lang.org/rustdoc/index.html)