fork/cargo

git clone https://git.julia.blue/fork/cargo

borsAuto merge of #14675 - RalfJung:help, r=weihanglode128bea7

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