[Cargo](https://doc.rust-lang.org/cargo/) is the official package manager for the [Rust](../../dev/programming/languages/Rust.md) programming language. It serves as a build system, package manager, and dependency manager for [Rust](../../dev/programming/languages/Rust.md) projects. Cargo makes it easy to manage, build, and distribute [Rust](../../dev/programming/languages/Rust.md) projects, handling tasks such as compiling code, managing dependencies, and running tests.
| `--branch <BRANCH>` | [Git](../../dev/Git.md) branch to download the crate from |
| `--tag <TAG>` | [Git](../../dev/Git.md) tag to download the crate from |
| `--rev <REV>` | [Git](../../dev/Git.md) reference to download the crate from |
| `--registry <NAME>` | Package registry for this dependency |
| `--dev` | Add as development dependency. Dev-dependencies are not used when compiling a package for building, but are used for compiling tests, examples, and benchmarks. These dependencies are not propagated to other packages which depend on this package. |
| `--build` | Add as build dependency. Build-dependencies are the only dependencies available for use by build scripts (`build.rs` files). |
| `--target <TARGET>` | Add as dependency to the given target platform |
## `cargo build`
Compile a local package and all of its dependencies
Update dependencies as recorded in the local lock file
Usage: `cargo update [--dry-run]`
## Manifest
The `Cargo.toml` file for each package is called its manifest. It is written in the [TOML](../../files/TOML.md) format. It contains metadata that is needed to compile the package.
Every manifest file consists of the following sections:
- [`[package]`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-package-section) — Defines a package.
- [`name`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-name-field) — The name of the package.
- [`version`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-version-field) — The version of the package.
- [`authors`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-authors-field) — The authors of the package.
- [`edition`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-edition-field) — The [Rust](../../dev/programming/languages/Rust.md) edition.
- [`rust-version`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-rust-version-field) — The minimal supported [Rust](../../dev/programming/languages/Rust.md) version.
- [`description`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-description-field) — A description of the package.
- [`documentation`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-documentation-field) — [URL](../../internet/URL.md) of the package documentation.
- [`readme`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-readme-field) — Path to the package’s README file.
- [`homepage`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-homepage-field) — [URL](../../internet/URL.md) of the package homepage.
- [`repository`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-repository-field) — [URL](../../internet/URL.md) of the package source repository.
- [`license`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-license-and-license-file-fields) — The package license.
- [`license-file`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-license-and-license-file-fields) — Path to the text of the license.
- [`keywords`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-keywords-field) — Keywords for the package.
- [`categories`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-categories-field) — Categories of the package.
- [`workspace`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-workspace-field) — Path to the workspace for the package.
- [`build`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-build-field) — Path to the package build script.
- [`links`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-links-field) — Name of the native library the package links with.
- [`exclude`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-exclude-and-include-fields) — Files to exclude when publishing.
- [`include`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-exclude-and-include-fields) — Files to include when publishing.
- [`publish`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-publish-field) — Can be used to prevent publishing the package.
- [`metadata`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-metadata-table) — Extra settings for external tools.
- [`default-run`](https://doc.rust-lang.org/cargo/reference/manifest.html#the-default-run-field) — The default binary to run by [`cargo run`](https://doc.rust-lang.org/cargo/commands/cargo-run.html).
- [`autobins`](https://doc.rust-lang.org/cargo/reference/cargo-targets.html#target-auto-discovery) — Disables binary auto discovery.
- [`autoexamples`](https://doc.rust-lang.org/cargo/reference/cargo-targets.html#target-auto-discovery) — Disables example auto discovery.
- [`autotests`](https://doc.rust-lang.org/cargo/reference/cargo-targets.html#target-auto-discovery) — Disables test auto discovery.
- [`autobenches`](https://doc.rust-lang.org/cargo/reference/cargo-targets.html#target-auto-discovery) — Disables bench auto discovery.
- [`resolver`](https://doc.rust-lang.org/cargo/reference/resolver.html#resolver-versions) — Sets the dependency resolver to use.
- Target tables: (see [configuration](https://doc.rust-lang.org/cargo/reference/cargo-targets.html#configuring-a-target) for settings)
- [`[dev-dependencies]`](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#development-dependencies) — Dependencies for examples, tests, and benchmarks.
- [`[build-dependencies]`](https://doc.rust-lang.org/cargo/reference/specifying-dependencies.html#build-dependencies) — Dependencies for build scripts.
Some packages need to compile third-party non-[Rust](../../dev/programming/languages/Rust.md) code, for example C libraries. Other packages need to link to C libraries which can either be located on the system or possibly need to be built from source. Others still need facilities for functionality such as code generation before building (think parser generators).
Cargo does not aim to replace other tools that are well-optimized for these tasks, but it does integrate with them with custom build scripts. Placing a file named `build.rs` in the root of a package will cause Cargo to compile that script and execute it just before building the package.
When the build script is run, there are a number of inputs to the build script, all passed in the form of [environment variables](../../linux/Environment%20Variables.md).
Cargo exposes these [environment variables](../../linux/Environment%20Variables.md) to your crate when it is compiled. Note that this applies for running binaries with `cargo run` and `cargo test` as well. To get the value of any of these variables in a [Rust](../../dev/programming/languages/Rust.md) program, do this:
-`CARGO` — Path to the `cargo` binary performing the build.
-`CARGO_MANIFEST_DIR` — The directory containing the manifest of your package.
-`CARGO_PKG_VERSION` — The full version of your package.
-`CARGO_PKG_VERSION_MAJOR` — The major version of your package.
-`CARGO_PKG_VERSION_MINOR` — The minor version of your package.
-`CARGO_PKG_VERSION_PATCH` — The patch version of your package.
-`CARGO_PKG_VERSION_PRE` — The pre-release version of your package.
-`CARGO_PKG_AUTHORS` — Colon separated list of authors from the manifest of your package.
-`CARGO_PKG_NAME` — The name of your package.
-`CARGO_PKG_DESCRIPTION` — The description from the manifest of your package.
-`CARGO_PKG_HOMEPAGE` — The home page from the manifest of your package.
-`CARGO_PKG_REPOSITORY` — The repository from the manifest of your package.
-`CARGO_PKG_LICENSE` — The license from the manifest of your package.
-`CARGO_PKG_LICENSE_FILE` — The license file from the manifest of your package.
-`CARGO_PKG_RUST_VERSION` — The [Rust](../../dev/programming/languages/Rust.md) version from the manifest of your package. Note that this is the minimum [Rust](../../dev/programming/languages/Rust.md) version supported by the package, not the current [Rust](../../dev/programming/languages/Rust.md) version.
-`CARGO_PKG_README` — Path to the README file of your package.
-`CARGO_CRATE_NAME` — The name of the crate that is currently being compiled. It is the name of the Cargo target with `-` converted to `_`, such as the name of the library, binary, example, integration test, or benchmark.
-`CARGO_BIN_NAME` — The name of the binary that is currently being compiled. Only set for binaries or binary examples. This name does not include any file extension, such as `.exe`.
-`OUT_DIR` — If the package has a build script, this is set to the folder where the build script should place its output.
-`CARGO_BIN_EXE_<name>` — The absolute path to a binary target’s executable. This is only set when building an integration test or benchmark. This may be used with the `env` macro to find the executable to run for testing purposes. The `<name>` is the name of the binary target, exactly as-is. For example, `CARGO_BIN_EXE_my-program` for a binary named `my-program`. Binaries are automatically built when the test is built, unless the binary has required features that are not enabled.
-`CARGO_PRIMARY_PACKAGE` — This environment variable will be set if the package being built is primary. Primary packages are the ones the user selected on the command-line, either with `-p` flags or the defaults based on the current directory and the default workspace members. This environment variable will not be set when building dependencies. This is only set when compiling the package (not when running binaries or tests).
-`CARGO_TARGET_TMPDIR` — Only set when building integration test or benchmark code. This is a path to a directory inside the target directory where integration tests or benchmarks are free to put any data needed by the tests/benches. Cargo initially creates this directory but doesn’t manage its content in any way, this is the responsibility of the test code.
