2020-08-01 16:38:02 +00:00
|
|
|
|
CARGO-PACKAGE(1)
|
|
|
|
|
|
|
|
|
|
NAME
|
2023-02-09 22:52:43 +00:00
|
|
|
|
cargo-package — Assemble the local package into a distributable
|
|
|
|
|
tarball
|
2020-08-01 16:38:02 +00:00
|
|
|
|
|
|
|
|
|
SYNOPSIS
|
|
|
|
|
cargo package [options]
|
|
|
|
|
|
|
|
|
|
DESCRIPTION
|
|
|
|
|
This command will create a distributable, compressed .crate file with
|
|
|
|
|
the source code of the package in the current directory. The resulting
|
|
|
|
|
file will be stored in the target/package directory. This performs the
|
|
|
|
|
following steps:
|
|
|
|
|
|
|
|
|
|
1. Load and check the current workspace, performing some basic checks.
|
|
|
|
|
o Path dependencies are not allowed unless they have a version key.
|
|
|
|
|
Cargo will ignore the path key for dependencies in published
|
|
|
|
|
packages. dev-dependencies do not have this restriction.
|
|
|
|
|
|
|
|
|
|
2. Create the compressed .crate file.
|
|
|
|
|
o The original Cargo.toml file is rewritten and normalized.
|
|
|
|
|
|
|
|
|
|
o [patch], [replace], and [workspace] sections are removed from the
|
|
|
|
|
manifest.
|
|
|
|
|
|
|
|
|
|
o Cargo.lock is automatically included if the package contains an
|
|
|
|
|
executable binary or example target. cargo-install(1) will use the
|
|
|
|
|
packaged lock file if the --locked flag is used.
|
|
|
|
|
|
|
|
|
|
o A .cargo_vcs_info.json file is included that contains information
|
|
|
|
|
about the current VCS checkout hash if available (not included
|
|
|
|
|
with --allow-dirty).
|
|
|
|
|
|
|
|
|
|
3. Extract the .crate file and build it to verify it can build.
|
|
|
|
|
o This will rebuild your package from scratch to ensure that it can
|
|
|
|
|
be built from a pristine state. The --no-verify flag can be used
|
|
|
|
|
to skip this step.
|
|
|
|
|
|
|
|
|
|
4. Check that build scripts did not modify any source files.
|
|
|
|
|
|
|
|
|
|
The list of files included can be controlled with the include and
|
|
|
|
|
exclude fields in the manifest.
|
|
|
|
|
|
|
|
|
|
See the reference
|
|
|
|
|
<https://doc.rust-lang.org/cargo/reference/publishing.html> for more
|
|
|
|
|
details about packaging and publishing.
|
|
|
|
|
|
2021-09-02 06:12:39 +00:00
|
|
|
|
.cargo_vcs_info.json format
|
|
|
|
|
Will generate a .cargo_vcs_info.json in the following format
|
|
|
|
|
|
|
|
|
|
{
|
|
|
|
|
"git": {
|
|
|
|
|
"sha1": "aac20b6e7e543e6dd4118b246c77225e3a3a1302"
|
|
|
|
|
},
|
|
|
|
|
"path_in_vcs": ""
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
path_in_vcs will be set to a repo-relative path for packages in
|
|
|
|
|
subdirectories of the version control repository.
|
|
|
|
|
|
2020-08-01 16:38:02 +00:00
|
|
|
|
OPTIONS
|
|
|
|
|
Package Options
|
|
|
|
|
-l, --list
|
|
|
|
|
Print files included in a package without making one.
|
|
|
|
|
|
|
|
|
|
--no-verify
|
2023-02-09 22:52:43 +00:00
|
|
|
|
Don’t verify the contents by building them.
|
2020-08-01 16:38:02 +00:00
|
|
|
|
|
|
|
|
|
--no-metadata
|
|
|
|
|
Ignore warnings about a lack of human-usable metadata (such as the
|
|
|
|
|
description or the license).
|
|
|
|
|
|
|
|
|
|
--allow-dirty
|
|
|
|
|
Allow working directories with uncommitted VCS changes to be
|
|
|
|
|
packaged.
|
|
|
|
|
|
2021-07-30 20:09:14 +00:00
|
|
|
|
Package Selection
|
|
|
|
|
By default, when no package selection options are given, the packages
|
|
|
|
|
selected depend on the selected manifest file (based on the current
|
|
|
|
|
working directory if --manifest-path is not given). If the manifest is
|
|
|
|
|
the root of a workspace then the workspaces default members are
|
|
|
|
|
selected, otherwise only the package defined by the manifest will be
|
|
|
|
|
selected.
|
|
|
|
|
|
|
|
|
|
The default members of a workspace can be set explicitly with the
|
|
|
|
|
workspace.default-members key in the root manifest. If this is not set,
|
|
|
|
|
a virtual workspace will include all workspace members (equivalent to
|
|
|
|
|
passing --workspace), and a non-virtual workspace will include only the
|
|
|
|
|
root crate itself.
|
|
|
|
|
|
2023-02-09 22:52:43 +00:00
|
|
|
|
-p spec…, --package spec…
|
2021-07-30 20:09:14 +00:00
|
|
|
|
Package only the specified packages. See cargo-pkgid(1) for the SPEC
|
|
|
|
|
format. This flag may be specified multiple times and supports
|
|
|
|
|
common Unix glob patterns like *, ? and []. However, to avoid your
|
|
|
|
|
shell accidentally expanding glob patterns before Cargo handles
|
|
|
|
|
them, you must use single quotes or double quotes around each
|
|
|
|
|
pattern.
|
|
|
|
|
|
|
|
|
|
--workspace
|
|
|
|
|
Package all members in the workspace.
|
|
|
|
|
|
2023-02-09 22:52:43 +00:00
|
|
|
|
--exclude SPEC…
|
2021-07-30 20:09:14 +00:00
|
|
|
|
Exclude the specified packages. Must be used in conjunction with the
|
|
|
|
|
--workspace flag. This flag may be specified multiple times and
|
|
|
|
|
supports common Unix glob patterns like *, ? and []. However, to
|
|
|
|
|
avoid your shell accidentally expanding glob patterns before Cargo
|
|
|
|
|
handles them, you must use single quotes or double quotes around
|
|
|
|
|
each pattern.
|
|
|
|
|
|
2020-08-01 16:38:02 +00:00
|
|
|
|
Compilation Options
|
|
|
|
|
--target triple
|
|
|
|
|
Package for the given architecture. The default is the host
|
|
|
|
|
architecture. The general format of the triple is
|
|
|
|
|
<arch><sub>-<vendor>-<sys>-<abi>. Run rustc --print target-list for
|
2022-06-17 14:56:42 +00:00
|
|
|
|
a list of supported targets. This flag may be specified multiple
|
|
|
|
|
times.
|
2020-08-01 16:38:02 +00:00
|
|
|
|
|
|
|
|
|
This may also be specified with the build.target config value
|
|
|
|
|
<https://doc.rust-lang.org/cargo/reference/config.html>.
|
|
|
|
|
|
|
|
|
|
Note that specifying this flag makes Cargo run in a different mode
|
|
|
|
|
where the target artifacts are placed in a separate directory. See
|
|
|
|
|
the build cache
|
|
|
|
|
<https://doc.rust-lang.org/cargo/guide/build-cache.html>
|
|
|
|
|
documentation for more details.
|
|
|
|
|
|
|
|
|
|
--target-dir directory
|
|
|
|
|
Directory for all generated artifacts and intermediate files. May
|
|
|
|
|
also be specified with the CARGO_TARGET_DIR environment variable, or
|
|
|
|
|
the build.target-dir config value
|
|
|
|
|
<https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
|
|
|
|
|
target in the root of the workspace.
|
|
|
|
|
|
|
|
|
|
Feature Selection
|
2020-12-17 23:21:23 +00:00
|
|
|
|
The feature flags allow you to control which features are enabled. When
|
|
|
|
|
no feature options are given, the default feature is activated for every
|
|
|
|
|
selected package.
|
2020-08-01 16:38:02 +00:00
|
|
|
|
|
2020-12-17 23:21:23 +00:00
|
|
|
|
See the features documentation
|
|
|
|
|
<https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options>
|
|
|
|
|
for more details.
|
2020-08-01 16:38:02 +00:00
|
|
|
|
|
2022-04-19 00:19:40 +00:00
|
|
|
|
-F features, --features features
|
2020-12-17 23:21:23 +00:00
|
|
|
|
Space or comma separated list of features to activate. Features of
|
|
|
|
|
workspace members may be enabled with package-name/feature-name
|
2020-08-01 16:38:02 +00:00
|
|
|
|
syntax. This flag may be specified multiple times, which enables all
|
|
|
|
|
specified features.
|
|
|
|
|
|
|
|
|
|
--all-features
|
|
|
|
|
Activate all available features of all selected packages.
|
|
|
|
|
|
|
|
|
|
--no-default-features
|
2020-12-17 23:21:23 +00:00
|
|
|
|
Do not activate the default feature of the selected packages.
|
2020-08-01 16:38:02 +00:00
|
|
|
|
|
|
|
|
|
Manifest Options
|
|
|
|
|
--manifest-path path
|
|
|
|
|
Path to the Cargo.toml file. By default, Cargo searches for the
|
|
|
|
|
Cargo.toml file in the current directory or any parent directory.
|
|
|
|
|
|
2024-03-28 02:04:46 +00:00
|
|
|
|
--locked
|
2024-03-28 02:24:06 +00:00
|
|
|
|
Ensures that Cargo uses the exact version of every dependency
|
|
|
|
|
captured in the existing Cargo.lock file. Cargo will exit with an
|
|
|
|
|
error when either of the following scenarios arises:
|
|
|
|
|
|
|
|
|
|
o The lock file is missing.
|
|
|
|
|
|
|
|
|
|
o The dependency resolution has changed, often caused by modifying
|
|
|
|
|
dependencies in the Cargo.toml file.
|
2020-08-01 16:38:02 +00:00
|
|
|
|
|
2024-03-28 02:04:46 +00:00
|
|
|
|
It may be used in environments where you want to assert that the
|
2024-03-28 02:24:06 +00:00
|
|
|
|
Cargo.lock file is up-to-date for reproducibility reasons, such as
|
|
|
|
|
in a CI build.
|
2020-08-01 16:38:02 +00:00
|
|
|
|
|
|
|
|
|
--offline
|
|
|
|
|
Prevents Cargo from accessing the network for any reason. Without
|
|
|
|
|
this flag, Cargo will stop with an error if it needs to access the
|
|
|
|
|
network and the network is not available. With this flag, Cargo will
|
|
|
|
|
attempt to proceed without the network if possible.
|
|
|
|
|
|
|
|
|
|
Beware that this may result in different dependency resolution than
|
|
|
|
|
online mode. Cargo will restrict itself to crates that are
|
|
|
|
|
downloaded locally, even if there might be a newer version as
|
|
|
|
|
indicated in the local copy of the index. See the cargo-fetch(1)
|
|
|
|
|
command to download dependencies before going offline.
|
|
|
|
|
|
|
|
|
|
May also be specified with the net.offline config value
|
|
|
|
|
<https://doc.rust-lang.org/cargo/reference/config.html>.
|
|
|
|
|
|
2024-03-28 02:04:46 +00:00
|
|
|
|
--frozen
|
|
|
|
|
Equivalent to specifying both --locked and --offline.
|
|
|
|
|
|
2020-08-01 16:38:02 +00:00
|
|
|
|
Miscellaneous Options
|
|
|
|
|
-j N, --jobs N
|
|
|
|
|
Number of parallel jobs to run. May also be specified with the
|
|
|
|
|
build.jobs config value
|
|
|
|
|
<https://doc.rust-lang.org/cargo/reference/config.html>. Defaults to
|
2022-07-10 23:06:25 +00:00
|
|
|
|
the number of logical CPUs. If negative, it sets the maximum number
|
|
|
|
|
of parallel jobs to the number of logical CPUs plus provided value.
|
2023-06-02 14:10:10 +00:00
|
|
|
|
If a string default is provided, it sets the value back to defaults.
|
2022-07-10 23:06:25 +00:00
|
|
|
|
Should not be 0.
|
2020-08-01 16:38:02 +00:00
|
|
|
|
|
2022-02-12 06:22:38 +00:00
|
|
|
|
--keep-going
|
|
|
|
|
Build as many crates in the dependency graph as possible, rather
|
|
|
|
|
than aborting the build on the first one that fails to build.
|
2023-08-26 16:49:49 +00:00
|
|
|
|
|
|
|
|
|
For example if the current package depends on dependencies fails and
|
|
|
|
|
works, one of which fails to build, cargo package -j1 may or may not
|
|
|
|
|
build the one that succeeds (depending on which one of the two
|
|
|
|
|
builds Cargo picked to run first), whereas cargo package -j1
|
|
|
|
|
--keep-going would definitely run both builds, even if the one run
|
|
|
|
|
first fails.
|
2022-02-12 06:22:38 +00:00
|
|
|
|
|
2020-08-01 16:38:02 +00:00
|
|
|
|
Display Options
|
|
|
|
|
-v, --verbose
|
2023-02-09 22:52:43 +00:00
|
|
|
|
Use verbose output. May be specified twice for “very verbose”
|
|
|
|
|
output which includes extra output such as dependency warnings and
|
|
|
|
|
build script output. May also be specified with the term.verbose
|
|
|
|
|
config value
|
|
|
|
|
<https://doc.rust-lang.org/cargo/reference/config.html>.
|
2020-08-01 16:38:02 +00:00
|
|
|
|
|
|
|
|
|
-q, --quiet
|
2021-12-08 22:15:28 +00:00
|
|
|
|
Do not print cargo log messages. May also be specified with the
|
|
|
|
|
term.quiet config value
|
|
|
|
|
<https://doc.rust-lang.org/cargo/reference/config.html>.
|
2020-08-01 16:38:02 +00:00
|
|
|
|
|
|
|
|
|
--color when
|
|
|
|
|
Control when colored output is used. Valid values:
|
|
|
|
|
|
|
|
|
|
o auto (default): Automatically detect if color support is
|
|
|
|
|
available on the terminal.
|
|
|
|
|
|
|
|
|
|
o always: Always display colors.
|
|
|
|
|
|
|
|
|
|
o never: Never display colors.
|
|
|
|
|
|
|
|
|
|
May also be specified with the term.color config value
|
|
|
|
|
<https://doc.rust-lang.org/cargo/reference/config.html>.
|
|
|
|
|
|
|
|
|
|
Common Options
|
|
|
|
|
+toolchain
|
|
|
|
|
If Cargo has been installed with rustup, and the first argument to
|
|
|
|
|
cargo begins with +, it will be interpreted as a rustup toolchain
|
|
|
|
|
name (such as +stable or +nightly). See the rustup documentation
|
2020-09-26 17:09:04 +00:00
|
|
|
|
<https://rust-lang.github.io/rustup/overrides.html> for more
|
|
|
|
|
information about how toolchain overrides work.
|
2020-08-01 16:38:02 +00:00
|
|
|
|
|
2022-09-13 08:54:33 +00:00
|
|
|
|
--config KEY=VALUE or PATH
|
|
|
|
|
Overrides a Cargo configuration value. The argument should be in
|
|
|
|
|
TOML syntax of KEY=VALUE, or provided as a path to an extra
|
|
|
|
|
configuration file. This flag may be specified multiple times. See
|
|
|
|
|
the command-line overrides section
|
|
|
|
|
<https://doc.rust-lang.org/cargo/reference/config.html#command-line-overrides>
|
|
|
|
|
for more information.
|
2022-06-21 16:24:41 +00:00
|
|
|
|
|
2023-02-01 23:24:12 +00:00
|
|
|
|
-C PATH
|
|
|
|
|
Changes the current working directory before executing any specified
|
|
|
|
|
operations. This affects things like where cargo looks by default
|
|
|
|
|
for the project manifest (Cargo.toml), as well as the directories
|
2023-04-09 16:58:06 +00:00
|
|
|
|
searched for discovering .cargo/config.toml, for example. This
|
|
|
|
|
option must appear before the command name, for example cargo -C
|
|
|
|
|
path/to/my-project build.
|
2023-02-01 23:24:12 +00:00
|
|
|
|
|
2023-04-12 02:42:28 +00:00
|
|
|
|
This option is only available on the nightly channel
|
|
|
|
|
<https://doc.rust-lang.org/book/appendix-07-nightly-rust.html> and
|
|
|
|
|
requires the -Z unstable-options flag to enable (see #10098
|
|
|
|
|
<https://github.com/rust-lang/cargo/issues/10098>).
|
|
|
|
|
|
2020-08-01 16:38:02 +00:00
|
|
|
|
-h, --help
|
|
|
|
|
Prints help information.
|
|
|
|
|
|
|
|
|
|
-Z flag
|
|
|
|
|
Unstable (nightly-only) flags to Cargo. Run cargo -Z help for
|
|
|
|
|
details.
|
|
|
|
|
|
|
|
|
|
ENVIRONMENT
|
|
|
|
|
See the reference
|
|
|
|
|
<https://doc.rust-lang.org/cargo/reference/environment-variables.html>
|
|
|
|
|
for details on environment variables that Cargo reads.
|
|
|
|
|
|
|
|
|
|
EXIT STATUS
|
|
|
|
|
o 0: Cargo succeeded.
|
|
|
|
|
|
|
|
|
|
o 101: Cargo failed to complete.
|
|
|
|
|
|
|
|
|
|
EXAMPLES
|
|
|
|
|
1. Create a compressed .crate file of the current package:
|
|
|
|
|
|
|
|
|
|
cargo package
|
|
|
|
|
|
|
|
|
|
SEE ALSO
|
|
|
|
|
cargo(1), cargo-publish(1)
|
|
|
|
|
|