]>
Commit | Line | Data |
---|---|---|
0a29b90c FG |
1 | # cargo-doc(1) |
2 | ||
0a29b90c FG |
3 | ## NAME |
4 | ||
5 | cargo-doc --- Build a package's documentation | |
6 | ||
7 | ## SYNOPSIS | |
8 | ||
9 | `cargo doc` [_options_] | |
10 | ||
11 | ## DESCRIPTION | |
12 | ||
13 | Build the documentation for the local package and all dependencies. The output | |
14 | is placed in `target/doc` in rustdoc's usual format. | |
15 | ||
16 | ## OPTIONS | |
17 | ||
18 | ### Documentation Options | |
19 | ||
20 | <dl> | |
21 | ||
22 | <dt class="option-term" id="option-cargo-doc---open"><a class="option-anchor" href="#option-cargo-doc---open"></a><code>--open</code></dt> | |
23 | <dd class="option-desc">Open the docs in a browser after building them. This will use your default | |
24 | browser unless you define another one in the <code>BROWSER</code> environment variable | |
25 | or use the <a href="../reference/config.html#docbrowser"><code>doc.browser</code></a> configuration | |
26 | option.</dd> | |
27 | ||
28 | ||
29 | <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> | |
30 | <dd class="option-desc">Do not build documentation for dependencies.</dd> | |
31 | ||
32 | ||
33 | <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> | |
34 | <dd class="option-desc">Include non-public items in the documentation. This will be enabled by default if documenting a binary target.</dd> | |
35 | ||
36 | ||
37 | </dl> | |
38 | ||
39 | ### Package Selection | |
40 | ||
41 | By default, when no package selection options are given, the packages selected | |
42 | depend on the selected manifest file (based on the current working directory if | |
43 | `--manifest-path` is not given). If the manifest is the root of a workspace then | |
44 | the workspaces default members are selected, otherwise only the package defined | |
45 | by the manifest will be selected. | |
46 | ||
47 | The default members of a workspace can be set explicitly with the | |
48 | `workspace.default-members` key in the root manifest. If this is not set, a | |
49 | virtual workspace will include all workspace members (equivalent to passing | |
50 | `--workspace`), and a non-virtual workspace will include only the root crate itself. | |
51 | ||
52 | <dl> | |
53 | ||
54 | <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> | |
55 | <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> | |
56 | <dd class="option-desc">Document only the specified packages. See <a href="cargo-pkgid.html">cargo-pkgid(1)</a> for the | |
57 | SPEC format. This flag may be specified multiple times and supports common Unix | |
58 | glob patterns like <code>*</code>, <code>?</code> and <code>[]</code>. However, to avoid your shell accidentally | |
59 | expanding glob patterns before Cargo handles them, you must use single quotes or | |
60 | double quotes around each pattern.</dd> | |
61 | ||
62 | ||
63 | <dt class="option-term" id="option-cargo-doc---workspace"><a class="option-anchor" href="#option-cargo-doc---workspace"></a><code>--workspace</code></dt> | |
64 | <dd class="option-desc">Document all members in the workspace.</dd> | |
65 | ||
66 | ||
67 | ||
68 | <dt class="option-term" id="option-cargo-doc---all"><a class="option-anchor" href="#option-cargo-doc---all"></a><code>--all</code></dt> | |
69 | <dd class="option-desc">Deprecated alias for <code>--workspace</code>.</dd> | |
70 | ||
71 | ||
72 | ||
73 | <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> | |
74 | <dd class="option-desc">Exclude the specified packages. Must be used in conjunction with the | |
75 | <code>--workspace</code> flag. This flag may be specified multiple times and supports | |
76 | common Unix glob patterns like <code>*</code>, <code>?</code> and <code>[]</code>. However, to avoid your shell | |
77 | accidentally expanding glob patterns before Cargo handles them, you must use | |
78 | single quotes or double quotes around each pattern.</dd> | |
79 | ||
80 | ||
81 | </dl> | |
82 | ||
83 | ||
84 | ### Target Selection | |
85 | ||
86 | When no target selection options are given, `cargo doc` will document all | |
87 | binary and library targets of the selected package. The binary will be skipped | |
88 | if its name is the same as the lib target. Binaries are skipped if they have | |
89 | `required-features` that are missing. | |
90 | ||
91 | The default behavior can be changed by setting `doc = false` for the target in | |
92 | the manifest settings. Using target selection options will ignore the `doc` | |
93 | flag and will always document the given target. | |
94 | ||
95 | <dl> | |
96 | <dt class="option-term" id="option-cargo-doc---lib"><a class="option-anchor" href="#option-cargo-doc---lib"></a><code>--lib</code></dt> | |
97 | <dd class="option-desc">Document the package’s library.</dd> | |
98 | ||
99 | ||
100 | <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> | |
101 | <dd class="option-desc">Document the specified binary. This flag may be specified multiple times | |
102 | and supports common Unix glob patterns.</dd> | |
103 | ||
104 | ||
105 | <dt class="option-term" id="option-cargo-doc---bins"><a class="option-anchor" href="#option-cargo-doc---bins"></a><code>--bins</code></dt> | |
106 | <dd class="option-desc">Document all binary targets.</dd> | |
107 | ||
108 | ||
109 | ||
110 | <dt class="option-term" id="option-cargo-doc---example"><a class="option-anchor" href="#option-cargo-doc---example"></a><code>--example</code> <em>name</em>…</dt> | |
111 | <dd class="option-desc">Document the specified example. This flag may be specified multiple times | |
112 | and supports common Unix glob patterns.</dd> | |
113 | ||
114 | ||
115 | <dt class="option-term" id="option-cargo-doc---examples"><a class="option-anchor" href="#option-cargo-doc---examples"></a><code>--examples</code></dt> | |
116 | <dd class="option-desc">Document all example targets.</dd> | |
117 | ||
118 | ||
119 | </dl> | |
120 | ||
121 | ### Feature Selection | |
122 | ||
123 | The feature flags allow you to control which features are enabled. When no | |
124 | feature options are given, the `default` feature is activated for every | |
125 | selected package. | |
126 | ||
127 | See [the features documentation](../reference/features.html#command-line-feature-options) | |
128 | for more details. | |
129 | ||
130 | <dl> | |
131 | ||
132 | <dt class="option-term" id="option-cargo-doc--F"><a class="option-anchor" href="#option-cargo-doc--F"></a><code>-F</code> <em>features</em></dt> | |
133 | <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> | |
134 | <dd class="option-desc">Space or comma separated list of features to activate. Features of workspace | |
135 | members may be enabled with <code>package-name/feature-name</code> syntax. This flag may | |
136 | be specified multiple times, which enables all specified features.</dd> | |
137 | ||
138 | ||
139 | <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> | |
140 | <dd class="option-desc">Activate all available features of all selected packages.</dd> | |
141 | ||
142 | ||
143 | <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> | |
144 | <dd class="option-desc">Do not activate the <code>default</code> feature of the selected packages.</dd> | |
145 | ||
146 | ||
147 | </dl> | |
148 | ||
149 | ||
150 | ### Compilation Options | |
151 | ||
152 | <dl> | |
153 | ||
154 | <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> | |
155 | <dd class="option-desc">Document for the given architecture. The default is the host architecture. The general format of the triple is | |
156 | <code><arch><sub>-<vendor>-<sys>-<abi></code>. Run <code>rustc --print target-list</code> for a | |
157 | list of supported targets. This flag may be specified multiple times.</p> | |
158 | <p>This may also be specified with the <code>build.target</code> | |
159 | <a href="../reference/config.html">config value</a>.</p> | |
160 | <p>Note that specifying this flag makes Cargo run in a different mode where the | |
161 | target artifacts are placed in a separate directory. See the | |
162 | <a href="../guide/build-cache.html">build cache</a> documentation for more details.</dd> | |
163 | ||
164 | ||
165 | ||
166 | <dt class="option-term" id="option-cargo-doc--r"><a class="option-anchor" href="#option-cargo-doc--r"></a><code>-r</code></dt> | |
167 | <dt class="option-term" id="option-cargo-doc---release"><a class="option-anchor" href="#option-cargo-doc---release"></a><code>--release</code></dt> | |
168 | <dd class="option-desc">Document optimized artifacts with the <code>release</code> profile. | |
169 | See also the <code>--profile</code> option for choosing a specific profile by name.</dd> | |
170 | ||
171 | ||
172 | ||
173 | <dt class="option-term" id="option-cargo-doc---profile"><a class="option-anchor" href="#option-cargo-doc---profile"></a><code>--profile</code> <em>name</em></dt> | |
174 | <dd class="option-desc">Document with the given profile. | |
175 | See the <a href="../reference/profiles.html">the reference</a> for more details on profiles.</dd> | |
176 | ||
177 | ||
178 | ||
179 | <dt class="option-term" id="option-cargo-doc---ignore-rust-version"><a class="option-anchor" href="#option-cargo-doc---ignore-rust-version"></a><code>--ignore-rust-version</code></dt> | |
180 | <dd class="option-desc">Document the target even if the selected Rust compiler is older than the | |
181 | required Rust version as configured in the project’s <code>rust-version</code> field.</dd> | |
182 | ||
183 | ||
184 | ||
185 | <dt class="option-term" id="option-cargo-doc---timings=fmts"><a class="option-anchor" href="#option-cargo-doc---timings=fmts"></a><code>--timings=</code><em>fmts</em></dt> | |
186 | <dd class="option-desc">Output information how long each compilation takes, and track concurrency | |
187 | information over time. Accepts an optional comma-separated list of output | |
188 | formats; <code>--timings</code> without an argument will default to <code>--timings=html</code>. | |
189 | Specifying an output format (rather than the default) is unstable and requires | |
190 | <code>-Zunstable-options</code>. Valid output formats:</p> | |
191 | <ul> | |
192 | <li><code>html</code> (unstable, requires <code>-Zunstable-options</code>): Write a human-readable file <code>cargo-timing.html</code> to the | |
193 | <code>target/cargo-timings</code> directory with a report of the compilation. Also write | |
194 | a report to the same directory with a timestamp in the filename if you want | |
195 | to look at older runs. HTML output is suitable for human consumption only, | |
196 | and does not provide machine-readable timing data.</li> | |
197 | <li><code>json</code> (unstable, requires <code>-Zunstable-options</code>): Emit machine-readable JSON | |
198 | information about timing information.</li> | |
199 | </ul></dd> | |
200 | ||
201 | ||
202 | ||
203 | ||
204 | </dl> | |
205 | ||
206 | ### Output Options | |
207 | ||
208 | <dl> | |
209 | <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> | |
210 | <dd class="option-desc">Directory for all generated artifacts and intermediate files. May also be | |
211 | specified with the <code>CARGO_TARGET_DIR</code> environment variable, or the | |
212 | <code>build.target-dir</code> <a href="../reference/config.html">config value</a>. | |
213 | Defaults to <code>target</code> in the root of the workspace.</dd> | |
214 | ||
215 | ||
216 | </dl> | |
217 | ||
218 | ### Display Options | |
219 | ||
220 | <dl> | |
221 | <dt class="option-term" id="option-cargo-doc--v"><a class="option-anchor" href="#option-cargo-doc--v"></a><code>-v</code></dt> | |
222 | <dt class="option-term" id="option-cargo-doc---verbose"><a class="option-anchor" href="#option-cargo-doc---verbose"></a><code>--verbose</code></dt> | |
223 | <dd class="option-desc">Use verbose output. May be specified twice for “very verbose” output which | |
224 | includes extra output such as dependency warnings and build script output. | |
225 | May also be specified with the <code>term.verbose</code> | |
226 | <a href="../reference/config.html">config value</a>.</dd> | |
227 | ||
228 | ||
229 | <dt class="option-term" id="option-cargo-doc--q"><a class="option-anchor" href="#option-cargo-doc--q"></a><code>-q</code></dt> | |
230 | <dt class="option-term" id="option-cargo-doc---quiet"><a class="option-anchor" href="#option-cargo-doc---quiet"></a><code>--quiet</code></dt> | |
231 | <dd class="option-desc">Do not print cargo log messages. | |
232 | May also be specified with the <code>term.quiet</code> | |
233 | <a href="../reference/config.html">config value</a>.</dd> | |
234 | ||
235 | ||
236 | <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> | |
237 | <dd class="option-desc">Control when colored output is used. Valid values:</p> | |
238 | <ul> | |
239 | <li><code>auto</code> (default): Automatically detect if color support is available on the | |
240 | terminal.</li> | |
241 | <li><code>always</code>: Always display colors.</li> | |
242 | <li><code>never</code>: Never display colors.</li> | |
243 | </ul> | |
244 | <p>May also be specified with the <code>term.color</code> | |
245 | <a href="../reference/config.html">config value</a>.</dd> | |
246 | ||
247 | ||
248 | ||
249 | <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> | |
250 | <dd class="option-desc">The output format for diagnostic messages. Can be specified multiple times | |
251 | and consists of comma-separated values. Valid values:</p> | |
252 | <ul> | |
253 | <li><code>human</code> (default): Display in a human-readable text format. Conflicts with | |
254 | <code>short</code> and <code>json</code>.</li> | |
255 | <li><code>short</code>: Emit shorter, human-readable text messages. Conflicts with <code>human</code> | |
256 | and <code>json</code>.</li> | |
257 | <li><code>json</code>: Emit JSON messages to stdout. See | |
258 | <a href="../reference/external-tools.html#json-messages">the reference</a> | |
259 | for more details. Conflicts with <code>human</code> and <code>short</code>.</li> | |
260 | <li><code>json-diagnostic-short</code>: Ensure the <code>rendered</code> field of JSON messages contains | |
261 | the “short” rendering from rustc. Cannot be used with <code>human</code> or <code>short</code>.</li> | |
262 | <li><code>json-diagnostic-rendered-ansi</code>: Ensure the <code>rendered</code> field of JSON messages | |
263 | contains embedded ANSI color codes for respecting rustc’s default color | |
264 | scheme. Cannot be used with <code>human</code> or <code>short</code>.</li> | |
265 | <li><code>json-render-diagnostics</code>: Instruct Cargo to not include rustc diagnostics | |
266 | in JSON messages printed, but instead Cargo itself should render the | |
267 | JSON diagnostics coming from rustc. Cargo’s own JSON diagnostics and others | |
268 | coming from rustc are still emitted. Cannot be used with <code>human</code> or <code>short</code>.</li> | |
269 | </ul></dd> | |
270 | ||
271 | ||
272 | </dl> | |
273 | ||
274 | ### Manifest Options | |
275 | ||
276 | <dl> | |
277 | <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> | |
278 | <dd class="option-desc">Path to the <code>Cargo.toml</code> file. By default, Cargo searches for the | |
279 | <code>Cargo.toml</code> file in the current directory or any parent directory.</dd> | |
280 | ||
281 | ||
282 | ||
283 | <dt class="option-term" id="option-cargo-doc---frozen"><a class="option-anchor" href="#option-cargo-doc---frozen"></a><code>--frozen</code></dt> | |
284 | <dt class="option-term" id="option-cargo-doc---locked"><a class="option-anchor" href="#option-cargo-doc---locked"></a><code>--locked</code></dt> | |
285 | <dd class="option-desc">Either of these flags requires that the <code>Cargo.lock</code> file is | |
286 | up-to-date. If the lock file is missing, or it needs to be updated, Cargo will | |
287 | exit with an error. The <code>--frozen</code> flag also prevents Cargo from | |
288 | attempting to access the network to determine if it is out-of-date.</p> | |
289 | <p>These may be used in environments where you want to assert that the | |
290 | <code>Cargo.lock</code> file is up-to-date (such as a CI build) or want to avoid network | |
291 | access.</dd> | |
292 | ||
293 | ||
294 | <dt class="option-term" id="option-cargo-doc---offline"><a class="option-anchor" href="#option-cargo-doc---offline"></a><code>--offline</code></dt> | |
295 | <dd class="option-desc">Prevents Cargo from accessing the network for any reason. Without this | |
296 | flag, Cargo will stop with an error if it needs to access the network and | |
297 | the network is not available. With this flag, Cargo will attempt to | |
298 | proceed without the network if possible.</p> | |
299 | <p>Beware that this may result in different dependency resolution than online | |
300 | mode. Cargo will restrict itself to crates that are downloaded locally, even | |
301 | if there might be a newer version as indicated in the local copy of the index. | |
302 | See the <a href="cargo-fetch.html">cargo-fetch(1)</a> command to download dependencies before going | |
303 | offline.</p> | |
304 | <p>May also be specified with the <code>net.offline</code> <a href="../reference/config.html">config value</a>.</dd> | |
305 | ||
306 | ||
307 | </dl> | |
308 | ||
309 | ### Common Options | |
310 | ||
311 | <dl> | |
312 | ||
313 | <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> | |
314 | <dd class="option-desc">If Cargo has been installed with rustup, and the first argument to <code>cargo</code> | |
315 | begins with <code>+</code>, it will be interpreted as a rustup toolchain name (such | |
316 | as <code>+stable</code> or <code>+nightly</code>). | |
317 | See the <a href="https://rust-lang.github.io/rustup/overrides.html">rustup documentation</a> | |
318 | for more information about how toolchain overrides work.</dd> | |
319 | ||
320 | ||
321 | <dt class="option-term" id="option-cargo-doc---config"><a class="option-anchor" href="#option-cargo-doc---config"></a><code>--config</code> <em>KEY=VALUE</em> or <em>PATH</em></dt> | |
322 | <dd class="option-desc">Overrides a Cargo configuration value. The argument should be in TOML syntax of <code>KEY=VALUE</code>, | |
323 | or provided as a path to an extra configuration file. This flag may be specified multiple times. | |
324 | See the <a href="../reference/config.html#command-line-overrides">command-line overrides section</a> for more information.</dd> | |
325 | ||
326 | ||
327 | <dt class="option-term" id="option-cargo-doc--C"><a class="option-anchor" href="#option-cargo-doc--C"></a><code>-C</code> <em>PATH</em></dt> | |
328 | <dd class="option-desc">Changes the current working directory before executing any specified operations. This affects | |
329 | things like where cargo looks by default for the project manifest (<code>Cargo.toml</code>), as well as | |
330 | the directories searched for discovering <code>.cargo/config.toml</code>, for example. This option must | |
331 | appear before the command name, for example <code>cargo -C path/to/my-project build</code>.</p> | |
332 | <p>This option is only available on the <a href="https://doc.rust-lang.org/book/appendix-07-nightly-rust.html">nightly | |
333 | channel</a> and | |
334 | requires the <code>-Z unstable-options</code> flag to enable (see | |
335 | <a href="https://github.com/rust-lang/cargo/issues/10098">#10098</a>).</dd> | |
336 | ||
337 | ||
338 | <dt class="option-term" id="option-cargo-doc--h"><a class="option-anchor" href="#option-cargo-doc--h"></a><code>-h</code></dt> | |
339 | <dt class="option-term" id="option-cargo-doc---help"><a class="option-anchor" href="#option-cargo-doc---help"></a><code>--help</code></dt> | |
340 | <dd class="option-desc">Prints help information.</dd> | |
341 | ||
342 | ||
343 | <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> | |
344 | <dd class="option-desc">Unstable (nightly-only) flags to Cargo. Run <code>cargo -Z help</code> for details.</dd> | |
345 | ||
346 | ||
347 | </dl> | |
348 | ||
349 | ||
350 | ### Miscellaneous Options | |
351 | ||
352 | <dl> | |
353 | <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> | |
354 | <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> | |
355 | <dd class="option-desc">Number of parallel jobs to run. May also be specified with the | |
356 | <code>build.jobs</code> <a href="../reference/config.html">config value</a>. Defaults to | |
357 | the number of logical CPUs. If negative, it sets the maximum number of | |
fe692bf9 FG |
358 | parallel jobs to the number of logical CPUs plus provided value. If |
359 | a string <code>default</code> is provided, it sets the value back to defaults. | |
0a29b90c FG |
360 | Should not be 0.</dd> |
361 | ||
362 | ||
363 | <dt class="option-term" id="option-cargo-doc---keep-going"><a class="option-anchor" href="#option-cargo-doc---keep-going"></a><code>--keep-going</code></dt> | |
364 | <dd class="option-desc">Build as many crates in the dependency graph as possible, rather than aborting | |
781aab86 FG |
365 | the build on the first one that fails to build.</p> |
366 | <p>For example if the current package depends on dependencies <code>fails</code> and <code>works</code>, | |
367 | one of which fails to build, <code>cargo doc -j1</code> may or may not build the | |
368 | one that succeeds (depending on which one of the two builds Cargo picked to run | |
369 | first), whereas <code>cargo doc -j1 --keep-going</code> would definitely run both | |
370 | builds, even if the one run first fails.</dd> | |
0a29b90c FG |
371 | |
372 | ||
373 | </dl> | |
374 | ||
375 | ## ENVIRONMENT | |
376 | ||
377 | See [the reference](../reference/environment-variables.html) for | |
378 | details on environment variables that Cargo reads. | |
379 | ||
380 | ||
381 | ## EXIT STATUS | |
382 | ||
383 | * `0`: Cargo succeeded. | |
384 | * `101`: Cargo failed to complete. | |
385 | ||
386 | ||
387 | ## EXAMPLES | |
388 | ||
389 | 1. Build the local package documentation and its dependencies and output to | |
390 | `target/doc`. | |
391 | ||
392 | cargo doc | |
393 | ||
394 | ## SEE ALSO | |
395 | [cargo(1)](cargo.html), [cargo-rustdoc(1)](cargo-rustdoc.html), [rustdoc(1)](https://doc.rust-lang.org/rustdoc/index.html) |