src/tools/cargo/src/doc/man/cargo.md

   1 # cargo(1)
   2
   3 ## NAME
   4
   5 cargo --- The Rust package manager
   6
   7 ## SYNOPSIS
   8
   9 `cargo` [_options_] _command_ [_args_]\
  10 `cargo` [_options_] `--version`\
  11 `cargo` [_options_] `--list`\
  12 `cargo` [_options_] `--help`\
  13 `cargo` [_options_] `--explain` _code_
  14
  15 ## DESCRIPTION
  16
  17 This program is a package manager and build tool for the Rust language,
  18 available at <https://rust-lang.org>.
  19
  20 ## COMMANDS
  21
  22 ### Build Commands
  23
  24 {{man "cargo-bench" 1}}\
  25 &nbsp;&nbsp;&nbsp;&nbsp;Execute benchmarks of a package.
  26
  27 {{man "cargo-build" 1}}\
  28 &nbsp;&nbsp;&nbsp;&nbsp;Compile a package.
  29
  30 {{man "cargo-check" 1}}\
  31 &nbsp;&nbsp;&nbsp;&nbsp;Check a local package and all of its dependencies for errors.
  32
  33 {{man "cargo-clean" 1}}\
  34 &nbsp;&nbsp;&nbsp;&nbsp;Remove artifacts that Cargo has generated in the past.
  35
  36 {{man "cargo-doc" 1}}\
  37 &nbsp;&nbsp;&nbsp;&nbsp;Build a package's documentation.
  38
  39 {{man "cargo-fetch" 1}}\
  40 &nbsp;&nbsp;&nbsp;&nbsp;Fetch dependencies of a package from the network.
  41
  42 {{man "cargo-fix" 1}}\
  43 &nbsp;&nbsp;&nbsp;&nbsp;Automatically fix lint warnings reported by rustc.
  44
  45 {{man "cargo-run" 1}}\
  46 &nbsp;&nbsp;&nbsp;&nbsp;Run a binary or example of the local package.
  47
  48 {{man "cargo-rustc" 1}}\
  49 &nbsp;&nbsp;&nbsp;&nbsp;Compile a package, and pass extra options to the compiler.
  50
  51 {{man "cargo-rustdoc" 1}}\
  52 &nbsp;&nbsp;&nbsp;&nbsp;Build a package's documentation, using specified custom flags.
  53
  54 {{man "cargo-test" 1}}\
  55 &nbsp;&nbsp;&nbsp;&nbsp;Execute unit and integration tests of a package.
  56
  57 ### Manifest Commands
  58
  59 {{man "cargo-generate-lockfile" 1}}\
  60 &nbsp;&nbsp;&nbsp;&nbsp;Generate `Cargo.lock` for a project.
  61
  62 {{man "cargo-locate-project" 1}}\
  63 &nbsp;&nbsp;&nbsp;&nbsp;Print a JSON representation of a `Cargo.toml` file's location.
  64
  65 {{man "cargo-metadata" 1}}\
  66 &nbsp;&nbsp;&nbsp;&nbsp;Output the resolved dependencies of a package in machine-readable format.
  67
  68 {{man "cargo-pkgid" 1}}\
  69 &nbsp;&nbsp;&nbsp;&nbsp;Print a fully qualified package specification.
  70
  71 {{man "cargo-tree" 1}}\
  72 &nbsp;&nbsp;&nbsp;&nbsp;Display a tree visualization of a dependency graph.
  73
  74 {{man "cargo-update" 1}}\
  75 &nbsp;&nbsp;&nbsp;&nbsp;Update dependencies as recorded in the local lock file.
  76
  77 {{man "cargo-vendor" 1}}\
  78 &nbsp;&nbsp;&nbsp;&nbsp;Vendor all dependencies locally.
  79
  80 {{man "cargo-verify-project" 1}}\
  81 &nbsp;&nbsp;&nbsp;&nbsp;Check correctness of crate manifest.
  82
  83 ### Package Commands
  84
  85 {{man "cargo-init" 1}}\
  86 &nbsp;&nbsp;&nbsp;&nbsp;Create a new Cargo package in an existing directory.
  87
  88 {{man "cargo-install" 1}}\
  89 &nbsp;&nbsp;&nbsp;&nbsp;Build and install a Rust binary.
  90
  91 {{man "cargo-new" 1}}\
  92 &nbsp;&nbsp;&nbsp;&nbsp;Create a new Cargo package.
  93
  94 {{man "cargo-search" 1}}\
  95 &nbsp;&nbsp;&nbsp;&nbsp;Search packages in crates.io.
  96
  97 {{man "cargo-uninstall" 1}}\
  98 &nbsp;&nbsp;&nbsp;&nbsp;Remove a Rust binary.
  99
 100 ### Publishing Commands
 101
 102 {{man "cargo-login" 1}}\
 103 &nbsp;&nbsp;&nbsp;&nbsp;Save an API token from the registry locally.
 104
 105 {{man "cargo-logout" 1}}\
 106 &nbsp;&nbsp;&nbsp;&nbsp;Remove an API token from the registry locally.
 107
 108 {{man "cargo-owner" 1}}\
 109 &nbsp;&nbsp;&nbsp;&nbsp;Manage the owners of a crate on the registry.
 110
 111 {{man "cargo-package" 1}}\
 112 &nbsp;&nbsp;&nbsp;&nbsp;Assemble the local package into a distributable tarball.
 113
 114 {{man "cargo-publish" 1}}\
 115 &nbsp;&nbsp;&nbsp;&nbsp;Upload a package to the registry.
 116
 117 {{man "cargo-yank" 1}}\
 118 &nbsp;&nbsp;&nbsp;&nbsp;Remove a pushed crate from the index.
 119
 120 ### General Commands
 121
 122 {{man "cargo-help" 1}}\
 123 &nbsp;&nbsp;&nbsp;&nbsp;Display help information about Cargo.
 124
 125 {{man "cargo-version" 1}}\
 126 &nbsp;&nbsp;&nbsp;&nbsp;Show version information.
 127
 128 ## OPTIONS
 129
 130 ### Special Options
 131
 132 {{#options}}
 133
 134 {{#option "`-V`" "`--version`" }}
 135 Print version info and exit. If used with `--verbose`, prints extra
 136 information.
 137 {{/option}}
 138
 139 {{#option "`--list`" }}
 140 List all installed Cargo subcommands. If used with `--verbose`, prints extra
 141 information.
 142 {{/option}}
 143
 144 {{#option "`--explain` _code_" }}
 145 Run `rustc --explain CODE` which will print out a detailed explanation of an
 146 error message (for example, `E0004`).
 147 {{/option}}
 148
 149 {{/options}}
 150
 151 ### Display Options
 152
 153 {{#options}}
 154
 155 {{> options-display }}
 156
 157 {{/options}}
 158
 159 ### Manifest Options
 160
 161 {{#options}}
 162 {{> options-locked }}
 163 {{/options}}
 164
 165 {{> section-options-common }}
 166
 167 {{> section-environment }}
 168
 169 {{> section-exit-status }}
 170
 171 ## FILES
 172
 173 `~/.cargo/`\
 174 &nbsp;&nbsp;&nbsp;&nbsp;Default location for Cargo's "home" directory where it
 175 stores various files. The location can be changed with the `CARGO_HOME`
 176 environment variable.
 177
 178 `$CARGO_HOME/bin/`\
 179 &nbsp;&nbsp;&nbsp;&nbsp;Binaries installed by {{man "cargo-install" 1}} will be located here. If using
 180 [rustup], executables distributed with Rust are also located here.
 181
 182 `$CARGO_HOME/config.toml`\
 183 &nbsp;&nbsp;&nbsp;&nbsp;The global configuration file. See [the reference](../reference/config.html)
 184 for more information about configuration files.
 185
 186 `.cargo/config.toml`\
 187 &nbsp;&nbsp;&nbsp;&nbsp;Cargo automatically searches for a file named `.cargo/config.toml` in the
 188 current directory, and all parent directories. These configuration files
 189 will be merged with the global configuration file.
 190
 191 `$CARGO_HOME/credentials.toml`\
 192 &nbsp;&nbsp;&nbsp;&nbsp;Private authentication information for logging in to a registry.
 193
 194 `$CARGO_HOME/registry/`\
 195 &nbsp;&nbsp;&nbsp;&nbsp;This directory contains cached downloads of the registry index and any
 196 downloaded dependencies.
 197
 198 `$CARGO_HOME/git/`\
 199 &nbsp;&nbsp;&nbsp;&nbsp;This directory contains cached downloads of git dependencies.
 200
 201 Please note that the internal structure of the `$CARGO_HOME` directory is not
 202 stable yet and may be subject to change.
 203
 204 [rustup]: https://rust-lang.github.io/rustup/
 205
 206 ## EXAMPLES
 207
 208 1. Build a local package and all of its dependencies:
 209
 210        cargo build
 211
 212 2. Build a package with optimizations:
 213
 214        cargo build --release
 215
 216 3. Run tests for a cross-compiled target:
 217
 218        cargo test --target i686-unknown-linux-gnu
 219
 220 4. Create a new package that builds an executable:
 221
 222        cargo new foobar
 223
 224 5. Create a package in the current directory:
 225
 226        mkdir foo && cd foo
 227        cargo init .
 228
 229 6. Learn about a command's options and usage:
 230
 231        cargo help clean
 232
 233 ## BUGS
 234
 235 See <https://github.com/rust-lang/cargo/issues> for issues.
 236
 237 ## SEE ALSO
 238 {{man "rustc" 1}}, {{man "rustdoc" 1}}