src/doc/man/cargo.adoc

= cargo(1)
:doctype: manpage

== NAME

cargo - The Rust package manager

== SYNOPSIS

[%hardbreaks]
`cargo [_OPTIONS_] _COMMAND_ [_ARGS_]`
`cargo [_OPTIONS_] --version`
`cargo [_OPTIONS_] --list`
`cargo [_OPTIONS_] --help`
`cargo [_OPTIONS_] --explain _CODE_`

== DESCRIPTION

This program is a package manager and build tool for the Rust language,
available at <https://rust-lang.org>.

== COMMANDS

=== Build Commands

man:cargo-bench[1]::
    Execute benchmarks of a package.

man:cargo-build[1]::
    Compile a package.

man:cargo-check[1]::
    Check a local package and all of its dependencies for errors.

man:cargo-clean[1]::
    Remove artifacts that Cargo has generated in the past.

man:cargo-doc[1]::
    Build a package's documentation.

man:cargo-fetch[1]::
    Fetch dependencies of a package from the network.

man:cargo-fix[1]::
    Automatically fix lint warnings reported by rustc.

man:cargo-run[1]::
    Run a binary or example of the local package.

man:cargo-rustc[1]::
    Compile a package, and pass extra options to the compiler.

man:cargo-rustdoc[1]::
    Build a package's documentation, using specified custom flags.

man:cargo-test[1]::
    Execute unit and integration tests of a package.

=== Manifest Commands

man:cargo-generate-lockfile[1]::
    Generate `Cargo.lock` for a project.

man:cargo-locate-project[1]::
    Print a JSON representation of a `Cargo.toml` file's location.

man:cargo-metadata[1]::
    Output the resolved dependencies of a package, the concrete used versions
    including overrides, in machine-readable format.

man:cargo-pkgid[1]::
    Print a fully qualified package specification.

man:cargo-update[1]::
    Update dependencies as recorded in the local lock file.

man:cargo-verify-project[1]::
    Check correctness of crate manifest.

=== Package Commands

man:cargo-init[1]::
    Create a new Cargo package in an existing directory.

man:cargo-install[1]::
    Build and install a Rust binary.

man:cargo-new[1]::
    Create a new Cargo package.

man:cargo-search[1]::
    Search packages in crates.io.

man:cargo-uninstall[1]::
    Remove a Rust binary.

=== Publishing Commands

man:cargo-login[1]::
    Save an API token from the registry locally.

man:cargo-owner[1]::
    Manage the owners of a crate on the registry.

man:cargo-package[1]::
    Assemble the local package into a distributable tarball.

man:cargo-publish[1]::
    Upload a package to the registry.

man:cargo-yank[1]::
    Remove a pushed crate from the index.

=== General Commands

man:cargo-help[1]::
    Display help information about Cargo.

man:cargo-version[1]::
    Show version information.

== OPTIONS

=== Special Options

*-V*::
*--version*::
    Print version info and exit. If used with `--verbose`, prints extra
    information.

*--list*::
    List all installed Cargo subcommands. If used with `--verbose`, prints
    extra information.

*--explain _CODE_*::
    Run `rustc --explain CODE` which will print out a detailed explanation of
    an error message (for example, `E0004`).

=== Display Options

include::options-display.adoc[]

=== Manifest Options

include::options-locked.adoc[]

=== Common Options

include::options-common.adoc[]

include::section-environment.adoc[]

include::section-exit-status.adoc[]

== FILES

`~/.cargo/`::
    Default location for Cargo's "home" directory where it stores various
    files. The location can be changed with the `CARGO_HOME` environment
    variable.

`$CARGO_HOME/bin/`::
    Binaries installed by man:cargo-install[1] will be located here. If using
    rustup, executables distributed with Rust are also located here.

`$CARGO_HOME/config`::
    The global configuration file. See linkcargo:reference/config.html[the reference]
    for more information about configuration files.

`.cargo/config`::
    Cargo automatically searches for a file named `.cargo/config` in the
    current directory, and all parent directories. These configuration files
    will be merged with the global configuration file.

`$CARGO_HOME/credentials`::
    Private authentication information for logging in to a registry.

`$CARGO_HOME/registry/`::
    This directory contains cached downloads of the registry index and any
    downloaded dependencies.

`$CARGO_HOME/git/`::
    This directory contains cached downloads of git dependencies.

Please note that the internal structure of the `$CARGO_HOME` directory is not
stable yet and may be subject to change.

== EXAMPLES

. Build a local package and all of its dependencies:

    cargo build

. Build a package with optimizations:

    cargo build --release

. Run tests for a cross-compiled target:

    cargo test --target i686-unknown-linux-gnu

. Create a new package that builds an executable:

    cargo new foobar

. Create a package in the current directory:

    mkdir foo && cd foo
    cargo init .

. Learn about a command's options and usage:

    cargo help clean

== BUGS

See https://github.com/rust-lang/cargo/issues for issues.

== SEE ALSO
man:rustc[1], man:rustdoc[1]