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