cargo-build

Build the package or packages defined by the Cargo.toml manifest file in the local path

$ cargo [[b|build]]

$ cargo [[b|build]] [[-r|--release]]

$ cargo [[b|build]] --locked

$ cargo [[b|build]] --workspace

$ cargo [[b|build]] [[-p|--package]] [package]

$ cargo [[b|build]] --bin [name]

$ cargo [[b|build]] --test [test_name]

cargo build [OPTIONS] [PACKAGE]...

--release
    Compiles the package in release mode with optimizations. Artifacts are placed in target/release/.

--target
    Builds for the specified target triple (e.g., x86_64-unknown-linux-gnu).

-p , --package
    Builds only the specified package(s) within the workspace. This option can be used multiple times.

--workspace
    Builds all packages in the current workspace.

--bin
    Builds only the specified binary target. This option can be used multiple times.

--lib
    Builds only the library target of the current package.

--example
    Builds only the specified example target. This option can be used multiple times.

--test
    Builds only the specified test target. This option can be used multiple times.

--benches
    Builds only the specified benchmark target. This option can be used multiple times.

--features
    Space or comma separated list of features to activate.

--all-features
    Activates all available features of the current package.

--no-default-features
    Do not activate the default feature.

-j , --jobs
    Number of parallel jobs to run. Defaults to the number of CPUs.

--profile
    Builds with the given build profile (e.g., dev, release, test, bench).

--verbose
    Uses verbose output, printing more information during the build process.

--message-format
    The output format for messages (e.g., json).

--dry-run
    Performs a 'dry run'; doesn't actually build anything, just prints what would be done.

cargo build is the fundamental command within the Rust ecosystem's build system, Cargo. Its primary purpose is to compile the current package (crate) and all its dependencies into executable binaries, libraries, or other build artifacts. When you execute cargo build in a Rust project directory, Cargo reads the Cargo.toml manifest file to understand the project's structure, dependencies, and configuration. It then proceeds to download and compile any missing dependencies, followed by the compilation of your own source code. By default, cargo build compiles in debug mode, which includes debugging symbols and performs fewer optimizations, making the compilation process faster and debugging easier. For production-ready builds, the --release flag is used to compile in release mode, which applies aggressive optimizations for performance and produces smaller binaries. Cargo intelligently caches compiled dependencies, meaning subsequent builds are significantly faster as only changed files and their dependents are recompiled. This command is essential for developing, testing, and preparing Rust applications for deployment.

Requires a correctly installed Rust toolchain (Rust compiler rustc and Cargo itself).
The first build of a project or when dependencies change significantly can be time-consuming and consume considerable disk space, especially for large dependency trees.
Cross-compilation using --target often requires specific target toolchains to be installed (e.g., via rustup target add ).
Network access is required for downloading new dependencies from crates.io.

By default, cargo build compiles in the debug profile, placing artifacts in project_root/target/debug/. When cargo build --release is used, it compiles in the release profile, with artifacts located in project_root/target/release/. These profiles can be customized in Cargo.toml to define different compilation settings, such as optimization levels, debug info, and link-time optimizations, for various build scenarios.

cargo build leverages incremental compilation to speed up rebuilds. After the initial full build, Cargo only recompiles the parts of the code that have changed and any parts that depend on them. This significantly reduces compilation times for iterative development, making the edit-compile-test cycle much faster. The compiled artifacts and metadata for incremental builds are stored in project_root/target/debug/.fingerprint/ and other subdirectories.

Cargo was developed alongside the Rust programming language itself, becoming an integral part of the Rust ecosystem. Its development began early in Rust's history, with a significant push for its stabilization and feature completeness leading up to the 1.0 release of Rust in May 2015. Since then, cargo build has been the standard way to compile Rust projects, abstracting away the complexities of managing source files, dependencies, and build configurations. Its design emphasizes convention over configuration, making it easy for developers to get started without extensive setup. Continuous development has added support for workspaces, features, profiles, and more granular control over the build process, solidifying Cargo's position as the official and indispensable build system and package manager for Rust.

cargo run(1), cargo check(1), cargo test(1), cargo clean(1), cargo new(1), cargo init(1), rustc(1)