fork/cargo

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

Weihang Lofix: use `host-tuple` for host target subsitution (#16003)f2932725b

home-0.5.12
17.2 KiB391 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 specified target architecture. Flag may be
132           specified multiple times. The default is the host architecture. The
133           general format of the triple is <arch><sub>-<vendor>-<sys>-<abi>.
134
135           Possible values:
136
137           o  Any supported target in rustc --print target-list.
138
139           o  "host-tuple", which will internally be substituted by the
140              host’s target. This can be particularly useful if you’re
141              cross-compiling some crates, and don’t want to specify your
142              host’s machine as a target (for instance, an xtask in a shared
143              project that may be worked on by many hosts).
144
145           o  A path to a custom target specification. See Custom Target Lookup
146              Path
147              <https://doc.rust-lang.org/rustc/targets/custom.html#custom-target-lookup-path>
148              for more information.
149
150           This may also be specified with the build.target config value
151           <https://doc.rust-lang.org/cargo/reference/config.html>.
152
153           Note that specifying this flag makes Cargo run in a different mode
154           where the target artifacts are placed in a separate directory. See
155           the build cache
156           <https://doc.rust-lang.org/cargo/reference/build-cache.html>
157           documentation for more details.
158
159       -r, --release
160           Document optimized artifacts with the release profile. See also the
161           --profile option for choosing a specific profile by name.
162
163       --profile name
164           Document with the given profile. See the reference
165           <https://doc.rust-lang.org/cargo/reference/profiles.html> for more
166           details on profiles.
167
168       --timings=fmts
169           Output information how long each compilation takes, and track
170           concurrency information over time. Accepts an optional
171           comma-separated list of output formats; --timings without an
172           argument will default to --timings=html. Specifying an output format
173           (rather than the default) is unstable and requires
174           -Zunstable-options. Valid output formats:
175
176           o  html (unstable, requires -Zunstable-options): Write a
177              human-readable file cargo-timing.html to the target/cargo-timings
178              directory with a report of the compilation. Also write a report
179              to the same directory with a timestamp in the filename if you
180              want to look at older runs. HTML output is suitable for human
181              consumption only, and does not provide machine-readable timing
182              data.
183
184           o  json (unstable, requires -Zunstable-options): Emit
185              machine-readable JSON information about timing information.
186
187   Output Options
188       --target-dir directory
189           Directory for all generated artifacts and intermediate files. May
190           also be specified with the CARGO_TARGET_DIR environment variable, or
191           the build.target-dir config value
192           <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
193           target in the root of the workspace.
194
195   Display Options
196       -v, --verbose
197           Use verbose output. May be specified twice for “very verbose”
198           output which includes extra output such as dependency warnings and
199           build script output. May also be specified with the term.verbose
200           config value
201           <https://doc.rust-lang.org/cargo/reference/config.html>.
202
203       -q, --quiet
204           Do not print cargo log messages. May also be specified with the
205           term.quiet config value
206           <https://doc.rust-lang.org/cargo/reference/config.html>.
207
208       --color when
209           Control when colored output is used. Valid values:
210
211           o  auto (default): Automatically detect if color support is
212              available on the terminal.
213
214           o  always: Always display colors.
215
216           o  never: Never display colors.
217
218           May also be specified with the term.color config value
219           <https://doc.rust-lang.org/cargo/reference/config.html>.
220
221       --message-format fmt
222           The output format for diagnostic messages. Can be specified multiple
223           times and consists of comma-separated values. Valid values:
224
225           o  human (default): Display in a human-readable text format.
226              Conflicts with short and json.
227
228           o  short: Emit shorter, human-readable text messages. Conflicts with
229              human and json.
230
231           o  json: Emit JSON messages to stdout. See the reference
232              <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages>
233              for more details. Conflicts with human and short.
234
235           o  json-diagnostic-short: Ensure the rendered field of JSON messages
236              contains the “short” rendering from rustc. Cannot be used
237              with human or short.
238
239           o  json-diagnostic-rendered-ansi: Ensure the rendered field of JSON
240              messages contains embedded ANSI color codes for respecting
241              rustc’s default color scheme. Cannot be used with human or
242              short.
243
244           o  json-render-diagnostics: Instruct Cargo to not include rustc
245              diagnostics in JSON messages printed, but instead Cargo itself
246              should render the JSON diagnostics coming from rustc. Cargo’s
247              own JSON diagnostics and others coming from rustc are still
248              emitted. Cannot be used with human or short.
249
250   Manifest Options
251       --manifest-path path
252           Path to the Cargo.toml file. By default, Cargo searches for the
253           Cargo.toml file in the current directory or any parent directory.
254
255       --ignore-rust-version
256           Ignore rust-version specification in packages.
257
258       --locked
259           Asserts that the exact same dependencies and versions are used as
260           when the existing Cargo.lock file was originally generated. Cargo
261           will exit with an error when either of the following scenarios
262           arises:
263
264           o  The lock file is missing.
265
266           o  Cargo attempted to change the lock file due to a different
267              dependency resolution.
268
269           It may be used in environments where deterministic builds are
270           desired, such as in CI pipelines.
271
272       --offline
273           Prevents Cargo from accessing the network for any reason. Without
274           this flag, Cargo will stop with an error if it needs to access the
275           network and the network is not available. With this flag, Cargo will
276           attempt to proceed without the network if possible.
277
278           Beware that this may result in different dependency resolution than
279           online mode. Cargo will restrict itself to crates that are
280           downloaded locally, even if there might be a newer version as
281           indicated in the local copy of the index. See the cargo-fetch(1)
282           command to download dependencies before going offline.
283
284           May also be specified with the net.offline config value
285           <https://doc.rust-lang.org/cargo/reference/config.html>.
286
287       --frozen
288           Equivalent to specifying both --locked and --offline.
289
290       --lockfile-path PATH
291           Changes the path of the lockfile from the default
292           (<workspace_root>/Cargo.lock) to PATH. PATH must end with Cargo.lock
293           (e.g. --lockfile-path /tmp/temporary-lockfile/Cargo.lock). Note that
294           providing --lockfile-path will ignore existing lockfile at the
295           default path, and instead will either use the lockfile from PATH, or
296           write a new lockfile into the provided PATH if it doesn’t exist.
297           This flag can be used to run most commands in read-only directories,
298           writing lockfile into the provided PATH.
299
300           This option is only available on the nightly channel
301           <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and
302           requires the -Z unstable-options flag to enable (see #14421
303           <https://github.com/rust-lang/cargo/issues/14421>).
304
305   Common Options
306       +toolchain
307           If Cargo has been installed with rustup, and the first argument to
308           cargo begins with +, it will be interpreted as a rustup toolchain
309           name (such as +stable or +nightly). See the rustup documentation
310           <https://rust-lang.github.io/rustup/overrides.html> for more
311           information about how toolchain overrides work.
312
313       --config KEY=VALUE or PATH
314           Overrides a Cargo configuration value. The argument should be in
315           TOML syntax of KEY=VALUE, or provided as a path to an extra
316           configuration file. This flag may be specified multiple times. See
317           the command-line overrides section
318           <https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides>
319           for more information.
320
321       -C PATH
322           Changes the current working directory before executing any specified
323           operations. This affects things like where cargo looks by default
324           for the project manifest (Cargo.toml), as well as the directories
325           searched for discovering .cargo/config.toml, for example. This
326           option must appear before the command name, for example cargo -C
327           path/to/my-project build.
328
329           This option is only available on the nightly channel
330           <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and
331           requires the -Z unstable-options flag to enable (see #10098
332           <https://github.com/rust-lang/cargo/issues/10098>).
333
334       -h, --help
335           Prints help information.
336
337       -Z flag
338           Unstable (nightly-only) flags to Cargo. Run cargo -Z help for
339           details.
340
341   Miscellaneous Options
342       -j N, --jobs N
343           Number of parallel jobs to run. May also be specified with the
344           build.jobs config value
345           <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
346           the number of logical CPUs. If negative, it sets the maximum number
347           of parallel jobs to the number of logical CPUs plus provided value.
348           If a string default is provided, it sets the value back to defaults.
349           Should not be 0.
350
351       --keep-going
352           Build as many crates in the dependency graph as possible, rather
353           than aborting the build on the first one that fails to build.
354
355           For example if the current package depends on dependencies fails and
356           works, one of which fails to build, cargo rustdoc -j1 may or may not
357           build the one that succeeds (depending on which one of the two
358           builds Cargo picked to run first), whereas cargo rustdoc -j1
359           --keep-going would definitely run both builds, even if the one run
360           first fails.
361
362       --output-format
363           The output type for the documentation emitted. Valid values:
364
365           o  html (default): Emit the documentation in HTML format.
366
367           o  json: Emit the documentation in the experimental JSON format
368              <https://doc.rust-lang.org/nightly/nightly-rustc/rustdoc_json_types>.
369
370           This option is only available on the nightly channel
371           <https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and
372           requires the -Z unstable-options flag to enable.
373
374ENVIRONMENT
375       See the reference
376       <https://doc.rust-lang.org/cargo/reference/environment-variables.html>
377       for details on environment variables that Cargo reads.
378
379EXIT STATUS
380       o  0: Cargo succeeded.
381
382       o  101: Cargo failed to complete.
383
384EXAMPLES
385       1. Build documentation with custom CSS included from a given file:
386
387              cargo rustdoc --lib -- --extend-css extra.css
388
389SEE ALSO
390       cargo(1), cargo-doc(1), rustdoc(1)
391