1CARGO-DOC(1) 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.
45 --workspace
47 Document all members in the workspace.
48 --all
50 Deprecated alias for --workspace.
51 --exclude SPEC...
53 Exclude the specified packages. Must be used in conjunction with
54 the --workspace flag. This flag may be specified multiple times.
55 Target Selection
57 When no target selection options are given, cargo doc will document all
58 binary and library targets of the selected package. The binary will be
59 skipped if its name is the same as the lib target. Binaries are skipped
60 if they have required-features that are missing.
61 The default behavior can be changed by setting doc = false for the
63 target in the manifest settings. Using target selection options will
64 ignore the doc flag and will always document the given target.
65 --lib
67 Document the package’s library.
68 --bin NAME...
70 Document the specified binary. This flag may be specified multiple
71 times.
72 --bins
74 Document all binary targets.
75 Feature Selection
77 The feature flags allow you to control the enabled features for the
78 "current" package. The "current" package is the package in the current
79 directory, or the one specified in --manifest-path. If running in the
80 root of a virtual workspace, then the default features are selected for
81 all workspace members, or all features if --all-features is specified.
82 When no feature options are given, the default feature is activated for
84 every selected package.
85 --features FEATURES
87 Space or comma separated list of features to activate. These
88 features only apply to the current directory’s package. Features of
89 direct dependencies may be enabled with <dep-name>/<feature-name>
90 syntax. This flag may be specified multiple times, which enables
91 all specified features.
92 --all-features
94 Activate all available features of all selected packages.
95 --no-default-features
97 Do not activate the default feature of the current directory’s
98 package.
99 Compilation Options
101 --target TRIPLE
102 Document for the given architecture. The default is the host
103 architecture. The general format of the triple is
104 <arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for
105 a list of supported targets.
106 This may also be specified with the build.target config value
108 <https://doc.rust-lang.org/cargo/reference/config.html>.
109 Note that specifying this flag makes Cargo run in a different mode
111 where the target artifacts are placed in a separate directory. See
112 the build cache
113 <https://doc.rust-lang.org/cargo/guide/build-cache.html>
114 documentation for more details.
115 --release
117 Document optimized artifacts with the release profile. See the
118 PROFILES section for details on how this affects profile selection.
119 Output Options
121 --target-dir DIRECTORY
122 Directory for all generated artifacts and intermediate files. May
123 also be specified with the CARGO_TARGET_DIR environment variable,
124 or the build.target-dir config value
125 <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults
126 to target in the root of the workspace.
127 Display Options
129 -v, --verbose
130 Use verbose output. May be specified twice for "very verbose"
131 output which includes extra output such as dependency warnings and
132 build script output. May also be specified with the term.verbose
133 config value
134 <https://doc.rust-lang.org/cargo/reference/config.html>.
135 -q, --quiet
137 No output printed to stdout.
138 --color WHEN
140 Control when colored output is used. Valid values:
141 · auto (default): Automatically detect if color support is
143 available on the terminal.
144 · always: Always display colors.
146 · never: Never display colors.
148 May also be specified with the term.color config value
150 <https://doc.rust-lang.org/cargo/reference/config.html>.
151 --message-format FMT
153 The output format for diagnostic messages. Can be specified
154 multiple times and consists of comma-separated values. Valid
155 values:
156 · human (default): Display in a human-readable text format.
158 · short: Emit shorter, human-readable text messages.
160 · json: Emit JSON messages to stdout. See the reference
162 <https://doc.rust-lang.org/cargo/reference/external-tools.html#json-messages>
163 for more details.
164 · json-diagnostic-short: Ensure the rendered field of JSON
166 messages contains the "short" rendering from rustc.
167 · json-diagnostic-rendered-ansi: Ensure the rendered field of
169 JSON messages contains embedded ANSI color codes for respecting
170 rustc’s default color scheme.
171 · json-render-diagnostics: Instruct Cargo to not include rustc
173 diagnostics in in JSON messages printed, but instead Cargo
174 itself should render the JSON diagnostics coming from rustc.
175 Cargo’s own JSON diagnostics and others coming from rustc are
176 still emitted.
177 Manifest Options
179 --manifest-path PATH
180 Path to the Cargo.toml file. By default, Cargo searches for the
181 Cargo.toml file in the current directory or any parent directory.
182 --frozen, --locked
184 Either of these flags requires that the Cargo.lock file is
185 up-to-date. If the lock file is missing, or it needs to be updated,
186 Cargo will exit with an error. The --frozen flag also prevents
187 Cargo from attempting to access the network to determine if it is
188 out-of-date.
189 These may be used in environments where you want to assert that the
191 Cargo.lock file is up-to-date (such as a CI build) or want to avoid
192 network access.
193 --offline
195 Prevents Cargo from accessing the network for any reason. Without
196 this flag, Cargo will stop with an error if it needs to access the
197 network and the network is not available. With this flag, Cargo
198 will attempt to proceed without the network if possible.
199 Beware that this may result in different dependency resolution than
201 online mode. Cargo will restrict itself to crates that are
202 downloaded locally, even if there might be a newer version as
203 indicated in the local copy of the index. See the cargo-fetch(1)
204 command to download dependencies before going offline.
205 May also be specified with the net.offline config value
207 <https://doc.rust-lang.org/cargo/reference/config.html>.
208 Common Options
210 -h, --help
211 Prints help information.
212 -Z FLAG...
214 Unstable (nightly-only) flags to Cargo. Run cargo -Z help for
215 details.
216 Miscellaneous Options
218 -j N, --jobs N
219 Number of parallel jobs to run. May also be specified with the
220 build.jobs config value
221 <https://doc.rust-lang.org/cargo/reference/config.html>. Defaults
222 to the number of CPUs.
223
225 Profiles may be used to configure compiler options such as optimization
226 levels and debug settings. See the reference
227 <https://doc.rust-lang.org/cargo/reference/profiles.html> for more
228 details.
229 Profile selection depends on the target and crate being built. By
231 default the dev or test profiles are used. If the --release flag is
232 given, then the release or bench profiles are used.
233 ┌────────────────────┬─────────────────┬───────────────────┐
235 │ │ │ │
236 │Target │ Default Profile │ --release Profile │
237 ├────────────────────┼─────────────────┼───────────────────┤
238 │ │ │ │
239 │lib, bin, example │ dev │ release │
240 ├────────────────────┼─────────────────┼───────────────────┤
241 │ │ │ │
242 │test, bench, or any │ test │ bench │
243 │target │ │ │
244 │in "test" or │ │ │
245 │"bench" mode │ │ │
246 └────────────────────┴─────────────────┴───────────────────┘
247 Dependencies use the dev/release profiles.
249
251 See the reference
252 <https://doc.rust-lang.org/cargo/reference/environment-variables.html>
253 for details on environment variables that Cargo reads.
254
256 0
257 Cargo succeeded.
258 101
260 Cargo failed to complete.
261
263 1. Build the local package documentation and its dependencies and
264 output to target/doc.
265 cargo doc
267
269 cargo(1), cargo-rustdoc(1), rustdoc(1)
270 2020-02-06 CARGO-DOC(1)