fork/cargo
git clone https://git.julia.blue/fork/cargo
0473ee8b8
0.88.0
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