1CARGO-DOC(1) General Commands Manual CARGO-DOC(1)
2
6 cargo-doc - Build a package's documentation
7
9 cargo doc [options]
10
12 Build the documentation for the local package and all dependencies. The
13 output is placed in target/doc in rustdoc's usual format.
14
16 Documentation Options
17 --open
18 Open the docs in a browser after building them. This will use your
19 default browser unless you define another one in the BROWSER
20 environment variable.
21 --no-deps
23 Do not build documentation for dependencies.
24 --document-private-items
26 Include non-public items in the documentation.
27 Package Selection
29 By default, when no package selection options are given, the packages
30 selected depend on the selected manifest file (based on the current
31 working directory if --manifest-path is not given). If the manifest is
32 the root of a workspace then the workspaces default members are
33 selected, otherwise only the package defined by the manifest will be
34 selected.
35 The default members of a workspace can be set explicitly with the
37 workspace.default-members key in the root manifest. If this is not set,
38 a virtual workspace will include all workspace members (equivalent to
39 passing --workspace), and a non-virtual workspace will include only the
40 root crate itself.
41 -p spec..., --package spec...
43 Document only the specified packages. See cargo-pkgid(1) for the
44 SPEC format. This flag may be specified multiple times and supports
45 common Unix glob patterns like *, ? and []. However, to avoid your
46 shell accidentally expanding glob patterns before Cargo handles
47 them, you must use single quotes or double quotes around each
48 pattern.
49 --workspace
51 Document all members in the workspace.
52 --all
54 Deprecated alias for --workspace.
55 --exclude SPEC...
57 Exclude the specified packages. Must be used in conjunction with
58 the --workspace flag. This flag may be specified multiple times and
59 supports common Unix glob patterns like *, ? and []. However, to
60 avoid your shell accidentally expanding glob patterns before Cargo
61 handles them, you must use single quotes or double quotes around
62 each pattern.
63 Target Selection
65 When no target selection options are given, cargo doc will document all
66 binary and library targets of the selected package. The binary will be
67 skipped if its name is the same as the lib target. Binaries are skipped
68 if they have required-features that are missing.
69 The default behavior can be changed by setting doc = false for the
71 target in the manifest settings. Using target selection options will
72 ignore the doc flag and will always document the given target.
73 --lib
75 Document the package's library.
76 --bin name...
78 Document the specified binary. This flag may be specified multiple
79 times and supports common Unix glob patterns.
80 --bins
82 Document all binary targets.
83 Feature Selection
85 The feature flags allow you to control which features are enabled. When
86 no feature options are given, the default feature is activated for
87 every selected package.
88 See the features documentation
90 <https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options>
91 for more details.
92 --features features
94 Space or comma separated list of features to activate. Features of
95 workspace members may be enabled with package-name/feature-name
96 syntax. This flag may be specified multiple times, which enables
97 all specified features.
98 --all-features
100 Activate all available features of all selected packages.
101 --no-default-features
103 Do not activate the default feature of the selected packages.
104 Compilation Options
106 --target triple
107 Document for the given architecture. The default is the host
108 architecture. The general format of the triple is
109 <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for
110 a list of supported targets.
111 This may also be specified with the build.target config value
113 <https://doc.rust-lang.org/cargo/reference/config.html>.
114 Note that specifying this flag makes Cargo run in a different mode
116 where the target artifacts are placed in a separate directory. See
117 the build cache
118 <https://doc.rust-lang.org/cargo/guide/build-cache.html>
119 documentation for more details.
120 --release
122 Document optimized artifacts with the release profile. See the
123 PROFILES section for details on how this affects profile selection.
124 Output Options
126 --target-dir directory
127 Directory for all generated artifacts and intermediate files. May
128 also be specified with the CARGO_TARGET_DIR environment variable,
129 or the build.target-dir config value
130 <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults
131 to target in the root of the workspace.
132 Display Options
134 -v, --verbose
135 Use verbose output. May be specified twice for "very verbose"
136 output which includes extra output such as dependency warnings and
137 build script output. May also be specified with the term.verbose
138 config value
139 <https://doc.rust-lang.org/cargo/reference/config.html>.
140 -q, --quiet
142 No output printed to stdout.
143 --color when
145 Control when colored output is used. Valid values:
146 · auto (default): Automatically detect if color support is
148 available on the terminal.
149 · always: Always display colors.
151 · never: Never display colors.
153 May also be specified with the term.color config value
155 <https://doc.rust-lang.org/cargo/reference/config.html>.
156 --message-format fmt
158 The output format for diagnostic messages. Can be specified
159 multiple times and consists of comma-separated values. Valid
160 values:
161 · human (default): Display in a human-readable text format.
163 · short: Emit shorter, human-readable text messages.
165 · json: Emit JSON messages to stdout. See the reference
167 <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages>
168 for more details.
169 · json-diagnostic-short: Ensure the rendered field of JSON
171 messages contains the "short" rendering from rustc.
172 · json-diagnostic-rendered-ansi: Ensure the rendered field of JSON
174 messages contains embedded ANSI color codes for respecting
175 rustc's default color scheme.
176 · json-render-diagnostics: Instruct Cargo to not include rustc
178 diagnostics in in JSON messages printed, but instead Cargo
179 itself should render the JSON diagnostics coming from rustc.
180 Cargo's own JSON diagnostics and others coming from rustc are
181 still emitted.
182 Manifest Options
184 --manifest-path path
185 Path to the Cargo.toml file. By default, Cargo searches for the
186 Cargo.toml file in the current directory or any parent directory.
187 --frozen, --locked
189 Either of these flags requires that the Cargo.lock file is
190 up-to-date. If the lock file is missing, or it needs to be updated,
191 Cargo will exit with an error. The --frozen flag also prevents
192 Cargo from attempting to access the network to determine if it is
193 out-of-date.
194 These may be used in environments where you want to assert that the
196 Cargo.lock file is up-to-date (such as a CI build) or want to avoid
197 network access.
198 --offline
200 Prevents Cargo from accessing the network for any reason. Without
201 this flag, Cargo will stop with an error if it needs to access the
202 network and the network is not available. With this flag, Cargo
203 will attempt to proceed without the network if possible.
204 Beware that this may result in different dependency resolution than
206 online mode. Cargo will restrict itself to crates that are
207 downloaded locally, even if there might be a newer version as
208 indicated in the local copy of the index. See the cargo-fetch(1)
209 command to download dependencies before going offline.
210 May also be specified with the net.offline config value
212 <https://doc.rust-lang.org/cargo/reference/config.html>.
213 Common Options
215 +toolchain
216 If Cargo has been installed with rustup, and the first argument to
217 cargo begins with +, it will be interpreted as a rustup toolchain
218 name (such as +stable or +nightly). See the rustup documentation
219 <https://rust-lang.github.io/rustup/overrides.html> for more
220 information about how toolchain overrides work.
221 -h, --help
223 Prints help information.
224 -Z flag
226 Unstable (nightly-only) flags to Cargo. Run cargo -Z help for
227 details.
228 Miscellaneous Options
230 -j N, --jobs N
231 Number of parallel jobs to run. May also be specified with the
232 build.jobs config value
233 <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults
234 to the number of CPUs.
235
237 Profiles may be used to configure compiler options such as optimization
238 levels and debug settings. See the reference
239 <https://doc.rust-lang.org/cargo/reference/profiles.html> for more
240 details.
241 Profile selection depends on the target and crate being built. By
243 default the dev or test profiles are used. If the --release flag is
244 given, then the release or bench profiles are used.
245 ┌────────────────────┬─────────────────┬───────────────────┐
248 │Target │ Default Profile │ --release Profile │
249 ├────────────────────┼─────────────────┼───────────────────┤
250 │lib, bin, example │ dev │ release │
251 ├────────────────────┼─────────────────┼───────────────────┤
252 │test, bench, or any │ test │ bench │
253 │target in "test" or │ │ │
254 │"bench" mode │ │ │
255 └────────────────────┴─────────────────┴───────────────────┘
256 Dependencies use the dev/release profiles.
258
260 See the reference
261 <https://doc.rust-lang.org/cargo/reference/environment-variables.html>
262 for details on environment variables that Cargo reads.
263
265 · 0: Cargo succeeded.
266 · 101: Cargo failed to complete.
268
270 1. Build the local package documentation and its dependencies and
271 output to target/doc.
272 cargo doc
274
276 cargo(1), cargo-rustdoc(1), rustdoc(1)
277 CARGO-DOC(1)