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 Conflicts with short and json.
164 • short: Emit shorter, human-readable text messages. Conflicts
166 with human and json.
167 • json: Emit JSON messages to stdout. See the reference
169 <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages>
170 for more details. Conflicts with human and short.
171 • json-diagnostic-short: Ensure the rendered field of JSON
173 messages contains the "short" rendering from rustc. Cannot be
174 used with human or short.
175 • json-diagnostic-rendered-ansi: Ensure the rendered field of JSON
177 messages contains embedded ANSI color codes for respecting
178 rustc's default color scheme. Cannot be used with human or
179 short.
180 • json-render-diagnostics: Instruct Cargo to not include rustc
182 diagnostics in in JSON messages printed, but instead Cargo
183 itself should render the JSON diagnostics coming from rustc.
184 Cargo's own JSON diagnostics and others coming from rustc are
185 still emitted. Cannot be used with human or short.
186 Manifest Options
188 --manifest-path path
189 Path to the Cargo.toml file. By default, Cargo searches for the
190 Cargo.toml file in the current directory or any parent directory.
191 --frozen, --locked
193 Either of these flags requires that the Cargo.lock file is
194 up-to-date. If the lock file is missing, or it needs to be updated,
195 Cargo will exit with an error. The --frozen flag also prevents
196 Cargo from attempting to access the network to determine if it is
197 out-of-date.
198 These may be used in environments where you want to assert that the
200 Cargo.lock file is up-to-date (such as a CI build) or want to avoid
201 network access.
202 --offline
204 Prevents Cargo from accessing the network for any reason. Without
205 this flag, Cargo will stop with an error if it needs to access the
206 network and the network is not available. With this flag, Cargo
207 will attempt to proceed without the network if possible.
208 Beware that this may result in different dependency resolution than
210 online mode. Cargo will restrict itself to crates that are
211 downloaded locally, even if there might be a newer version as
212 indicated in the local copy of the index. See the cargo-fetch(1)
213 command to download dependencies before going offline.
214 May also be specified with the net.offline config value
216 <https://doc.rust-lang.org/cargo/reference/config.html>.
217 Common Options
219 +toolchain
220 If Cargo has been installed with rustup, and the first argument to
221 cargo begins with +, it will be interpreted as a rustup toolchain
222 name (such as +stable or +nightly). See the rustup documentation
223 <https://rust-lang.github.io/rustup/overrides.html> for more
224 information about how toolchain overrides work.
225 -h, --help
227 Prints help information.
228 -Z flag
230 Unstable (nightly-only) flags to Cargo. Run cargo -Z help for
231 details.
232 Miscellaneous Options
234 -j N, --jobs N
235 Number of parallel jobs to run. May also be specified with the
236 build.jobs config value
237 <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults
238 to the number of CPUs.
239
241 Profiles may be used to configure compiler options such as optimization
242 levels and debug settings. See the reference
243 <https://doc.rust-lang.org/cargo/reference/profiles.html> for more
244 details.
245 Profile selection depends on the target and crate being built. By
247 default the dev or test profiles are used. If the --release flag is
248 given, then the release or bench profiles are used.
249 ┌────────────────────┬─────────────────┬───────────────────┐
252 │Target │ Default Profile │ --release Profile │
253 ├────────────────────┼─────────────────┼───────────────────┤
254 │lib, bin, example │ dev │ release │
255 ├────────────────────┼─────────────────┼───────────────────┤
256 │test, bench, or any │ test │ bench │
257 │target in "test" or │ │ │
258 │"bench" mode │ │ │
259 └────────────────────┴─────────────────┴───────────────────┘
260 Dependencies use the dev/release profiles.
262
264 See the reference
265 <https://doc.rust-lang.org/cargo/reference/environment-variables.html>
266 for details on environment variables that Cargo reads.
267
269 • 0: Cargo succeeded.
270 • 101: Cargo failed to complete.
272
274 1. Build the local package documentation and its dependencies and
275 output to target/doc.
276 cargo doc
278
280 cargo(1), cargo-rustdoc(1), rustdoc(1)
281 CARGO-DOC(1)