fork/cargo

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

borsAuto merge of #14620 - epage:guideless, r=weihanglo0473ee8b8

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