knowledge/technology/applications/development/cargo.md

obj
application

cargo

Cargo is the official package manager for the Rust programming language. It serves as a build system, package manager, and dependency manager for Rust projects. Cargo makes it easy to manage, build, and distribute Rust projects, handling tasks such as compiling code, managing dependencies, and running tests.

cargo add

Add dependencies to a Cargo.toml manifest file

Options

Option	Description
--no-default-features	Disable the default features
--default-features	Re-enable the default features
-F, --features <FEATURES>	Space or comma separated list of features to activate
--optional	Mark the dependency as optional. The package name will be exposed as feature of your crate.
--no-optional	Mark the dependency as required. The package will be removed from your features.
--rename <NAME>	Rename the dependency
--dry-run	Don't actually write the manifest
-q, --quiet	Do not print cargo log messages
-v, --verbose...	Use verbose output (-vv very verbose/build.rs output)
--manifest-path <PATH>	Path to Cargo.toml
--path <PATH>	Filesystem path to local crate to add
--git <URI>	Git repository location
--branch <BRANCH>	Git branch to download the crate from
--tag <TAG>	Git tag to download the crate from
--rev <REV>	Git 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

Options

Option	Description
--lib	Build only this package's library
--bins	Build all binaries
--bin [<NAME>]	Build only the specified binary
--examples	Build all examples
--example [<NAME>]	Build only the specified example
--tests	Build all tests
--test [<NAME>]	Build only the specified test target
--all-targets	Build all targets
-F, --features <FEATURES>	Space or comma separated list of features to activate
--all-features	Activate all available features
--no-default-features	Do not activate the default feature
-r, --release	Build artifacts in release mode, with optimizations
-j, --jobs <N>	Number of parallel jobs, defaults to # of CPUs.

cargo check

Check a local package and all of its dependencies for errors

cargo clean

Remove artifacts that cargo has generated in the past
Usage: cargo clean

cargo clippy

Checks a package to catch common mistakes and improve your Rust code.

Options

Option	Description
--no-deps	Run Clippy only on the given crate, without linting the dependencies
--fix	Automatically apply lint suggestions. This flag implies --no-deps and --all-targets
--explain LINT	Print the documentation for a given lint

To allow or deny a lint from the command line you can use cargo clippy -- with:

Option	Description
-W --warn OPT	Set lint warnings
-A --allow OPT	Set lint allowed
-D --deny OPT	Set lint denied
-F --forbid OPT	Set lint forbidden

cargo doc

Build a package's documentation

Options

Option	Description
--open	Opens the docs in a browser after the operation
--no-deps	Don't build documentation for dependencies
--document-private-items	Document private items

cargo fetch

Fetch dependencies of a package from the network

cargo fmt

Formats all bin and lib files of the current crate using rustfmt.
Usage: cargo fmt [--check]

cargo init

Create a new cargo package in an existing directory

Options

Option	Description
--bin	Use a binary (application) template [default]
--lib	Use a library template
--edition <YEAR>	Edition to set for the crate generated [possible values: 2015, 2018, 2021]
--name <NAME>	Set the resulting package name, defaults to the directory name

cargo install

Install a Rust binary. Default location is $HOME/.cargo/bin

Options

Option	Description
--version <VERSION>	Specify a version to install
--index <INDEX>	Registry index to install from
--registry <REGISTRY>	Registry to use
--git <URL>	Git URL to install the specified crate from
--branch <BRANCH>	Branch to use when installing from git
--tag <TAG>	Tag to use when installing from git
--rev <SHA>	Specific commit to use when installing from git
--path <PATH>	Filesystem path to local crate to install
--root <DIR>	Directory to install packages into
-f, --force	Force overwriting existing crates or binaries
--no-track	Do not save tracking information
--list	list all installed packages and their versions
-q, --quiet	Do not print cargo log messages
-v, --verbose...	Use verbose output (-vv very verbose/build.rs output)
--bin [<NAME>]	Install only the specified binary
--bins	Install all binaries
--example [<NAME>]	Install only the specified example
--examples	Install all examples

cargo login

Log in to a registry.
Usage: cargo login --registry registry <token>

cargo logout

Remove an API token from the registry locally.
Usage: cargo logout --registry reg

cargo new

Create a new cargo package

Options

Option	Description
--bin	Use a binary (application) template [default]
--lib	Use a library template
--edition <YEAR>	Edition to set for the crate generated [possible values: 2015, 2018, 2021]
--name <NAME>	Set the resulting package name, defaults to the directory name

cargo package

Assemble the local package into a distributable tarball

Options

Option	Description
-l, --list	Print files included in a package without making one
--no-verify	Don't verify the contents by building them
--no-metadata	Ignore warnings about a lack of human-usable metadata
--allow-dirty	Allow dirty working directories to be packaged
-q, --quiet	Do not print cargo log messages
-v, --verbose...	Use verbose output (-vv very verbose/build.rs output)

cargo publish

Upload a package to the registry

Options

Option	Description
--dry-run	Perform all checks without uploading
--index <INDEX>	Registry index URL to upload the package to
--registry <REGISTRY>	Registry to publish to
--token <TOKEN>	Token to use when uploading
--no-verify	Don't verify the contents by building them
--allow-dirty	Allow dirty working directories to be packaged
-q, --quiet	Do not print cargo log messages
-v, --verbose...	Use verbose output (-vv very verbose/build.rs output)

cargo metadata

Print a JSON representation of a Cargo.toml manifest.
Usage: cargo metadata --no-deps

cargo remove

Remove dependencies from a Cargo.toml manifest file

Options

Option	Description
--dry-run	Don't actually write the manifest
--dev	Remove as development dependency
--build	Remove as build dependency
--target <TARGET>	Remove as dependency from the given target platform

cargo run

Run a binary or example of the local package

Options

Option	Description
--bin <NAME>	Name of the bin target to run
--example <NAME>	Name of the example target to run
-F, --features <FEATURES>	Space or comma separated list of features to activate
--all-features	Activate all available features
--no-default-features	Do not activate the default feature
-j, --jobs <N>	Number of parallel jobs, defaults to # of CPUs
-r, --release	Build artifacts in release mode, with optimizations

cargo search

Search packages in registry.
Usage: cargo search [--registry registry] [--limit limit] package

cargo test

Execute all unit and integration tests and build examples of a local package

cargo tree

Display a tree visualization of a dependency graph

cargo uninstall

Remove a Rust binary

cargo update

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 format. It contains metadata that is needed to compile the package.

Every manifest file consists of the following sections:

• cargo-features — Unstable, nightly-only features.
• [package] — Defines a package.
  • name — The name of the package.
  • version — The version of the package.
  • authors — The authors of the package.
  • edition — The Rust edition.
  • rust-version — The minimal supported Rust version.
  • description — A description of the package.
  • documentation — URL of the package documentation.
  • readme — Path to the package’s README file.
  • homepage — URL of the package homepage.
  • repository — URL of the package source repository.
  • license — The package license.
  • license-file — Path to the text of the license.
  • keywords — Keywords for the package.
  • categories — Categories of the package.
  • workspace — Path to the workspace for the package.
  • build — Path to the package build script.
  • links — Name of the native library the package links with.
  • exclude — Files to exclude when publishing.
  • include — Files to include when publishing.
  • publish — Can be used to prevent publishing the package.
  • metadata — Extra settings for external tools.
  • default-run — The default binary to run by cargo run.
  • autobins — Disables binary auto discovery.
  • autoexamples — Disables example auto discovery.
  • autotests — Disables test auto discovery.
  • autobenches — Disables bench auto discovery.
  • resolver — Sets the dependency resolver to use.
• Target tables: (see configuration for settings)
  • [lib] — Library target settings.
  • [[bin]] — Binary target settings.
  • [[example]] — Example target settings.
  • [[test]] — Test target settings.
  • [[bench]] — Benchmark target settings.
• Dependency tables:
  • [dependencies] — Package library dependencies.
  • [dev-dependencies] — Dependencies for examples, tests, and benchmarks.
  • [build-dependencies] — Dependencies for build scripts.
  • [target] — Platform-specific dependencies.
• [badges] — Badges to display on a registry.
• [features] — Conditional compilation features.
• [lints] — Configure linters for this package.
• [patch] — Override dependencies.
• [profile] — Compiler settings and optimizations.
• [workspace] — The workspace definition.

Build Scripts

Some packages need to compile third-party non-Rust 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.

// Example custom build script.
fn main() {
    // Tell Cargo that if the given file changes, to rerun this build script.
    println!("cargo:rerun-if-changed=src/hello.c");
    // Use the `cc` crate to build a C file and statically link it.
    cc::Build::new()
        .file("src/hello.c")
        .compile("hello");
}

Environment Variables

When the build script is run, there are a number of inputs to the build script, all passed in the form of environment variables.

Cargo exposes these environment variables 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 program, do this:

let version = env!("CARGO_PKG_VERSION");

Exposed environment variables:

• 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 version from the manifest of your package. Note that this is the minimum Rust version supported by the package, not the current Rust 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.