cargo-package

Perform checks and create a .crate file (equivalent of cargo publish --dry-run)

Display what files would be included in the tarball without actually creating it

cargo package [OPTIONS]

--no-verify
    Skip verification of the contents of the package. This means it won't build the package before packaging.

--no-metadata-check
    Skip checking `Cargo.toml` for missing metadata. Useful if you're packaging for reasons other than publishing to crates.io.

--allow-dirty
    Allow the cargo package command to be run even if the working directory is dirty. This is useful for testing or packaging non-public versions.

--dry-run
    Perform all checks and create a temporary archive, but do not write the `.crate` file to disk. Useful for seeing what would be packaged.

-p , --package
    Package only the specified package. If omitted, packages the current workspace root package.

-j , --jobs
    Number of parallel jobs to run.

--target
    Build for the target triple.

--profile
    Build with the given profile. (e.g., `dev`, `release`).

--all-features
    Activate all available features.

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

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

--workspace
    Package the workspace root, even if not the current directory.

--manifest-path
    Path to the `Cargo.toml` file.

--verbose, -v
    Use verbose output.

--quiet, -q
    Do not print cargo log messages.

--color
    Coloring: auto, always, never.

--frozen
    Require `Cargo.lock` and `Cargo.toml` to be up-to-date and disallow network access.

--locked
    Require `Cargo.lock` to be up-to-date.

--offline
    Disallow network access.

--config
    Set a configuration value.

-Z
    Unstable (nightly-only) flag.

--help, -h
    Prints help information.

The cargo package command is a crucial part of the Rust ecosystem's publishing workflow. Its primary purpose is to take a Rust package (a crate) and create a .crate archive file, which is the standardized format for distributing Rust packages. This archive typically contains the source code of the package, its Cargo.toml manifest, and any other necessary files specified in Cargo.toml's include or exclude directives.

Before creating the archive, cargo package performs several important checks to ensure the package is ready for publishing. These checks include:

• Verifying that the working directory is clean (no uncommitted changes).
• Building the package to ensure it compiles successfully with the specified features and targets.
• Running metadata checks to ensure Cargo.toml has essential fields like description, license or license-file, and documentation.

This command is usually executed as a preliminary step before cargo publish, allowing developers to test the packaging process and inspect the generated .crate file locally before pushing it to a registry like crates.io.

• By default, cargo package requires the Git working directory to be clean. This prevents accidentally packaging uncommitted or untracked changes. Use --allow-dirty to bypass this for testing purposes.
• The command does not actually publish your package to a registry; it only creates the .crate archive. You must use cargo publish for that.
• Skipping verification checks with --no-verify or --no-metadata-check is generally not recommended for packages intended for public distribution, as it might lead to non-compiling or improperly described packages.

The command generates a .crate file (e.g., my_crate-1.0.0.crate) in the target/package directory of your project. This file is a gzipped tar archive containing all necessary files for the package.

The default verification process ensures that the package builds successfully, its tests pass (if any), and its metadata meets publishing requirements. This helps catch potential issues before a package is published and consumed by others.

The cargo package command is an integral part of Cargo, the Rust package manager, which was initially introduced alongside the Rust programming language itself. Cargo's development began around 2014, aiming to provide a robust and easy-to-use system for managing Rust projects, their dependencies, and their distribution. The package command has been a core component of Cargo's release workflow since its early stable versions, facilitating the creation of reproducible .crate archives necessary for publishing to crates.io, Rust's official package registry. Its design reflects Rust's emphasis on correctness and safety, performing checks before packaging to ensure a higher quality of published crates.

cargo publish(1), cargo build(1), cargo check(1), cargo doc(1), cargo clean(1)