mirror of https://github.com/rust-lang/cargo
264 lines
11 KiB
Plaintext
264 lines
11 KiB
Plaintext
CARGO-PUBLISH(1)
|
||
|
||
NAME
|
||
cargo-publish — Upload a package to the registry
|
||
|
||
SYNOPSIS
|
||
cargo publish [options]
|
||
|
||
DESCRIPTION
|
||
This command will create a distributable, compressed .crate file with
|
||
the source code of the package in the current directory and upload it to
|
||
a registry. The default registry is <https://crates.io>. This performs
|
||
the following steps:
|
||
|
||
1. Performs a few checks, including:
|
||
o Checks the package.publish key in the manifest for restrictions on
|
||
which registries you are allowed to publish to.
|
||
|
||
2. Create a .crate file by following the steps in cargo-package(1).
|
||
|
||
3. Upload the crate to the registry. The server will perform additional
|
||
checks on the crate.
|
||
|
||
4. The client will poll waiting for the package to appear in the index,
|
||
and may timeout. In that case, you will need to check for completion
|
||
manually. This timeout does not affect the upload.
|
||
|
||
This command requires you to be authenticated with either the --token
|
||
option or using cargo-login(1).
|
||
|
||
See the reference
|
||
<https://doc.rust-lang.org/cargo/reference/publishing.html> for more
|
||
details about packaging and publishing.
|
||
|
||
OPTIONS
|
||
Publish Options
|
||
--dry-run
|
||
Perform all checks without uploading.
|
||
|
||
--token token
|
||
API token to use when authenticating. This overrides the token
|
||
stored in the credentials file (which is created by cargo-login(1)).
|
||
|
||
Cargo config <https://doc.rust-lang.org/cargo/reference/config.html>
|
||
environment variables can be used to override the tokens stored in
|
||
the credentials file. The token for crates.io may be specified with
|
||
the CARGO_REGISTRY_TOKEN environment variable. Tokens for other
|
||
registries may be specified with environment variables of the form
|
||
CARGO_REGISTRIES_NAME_TOKEN where NAME is the name of the registry
|
||
in all capital letters.
|
||
|
||
--no-verify
|
||
Don’t verify the contents by building them.
|
||
|
||
--allow-dirty
|
||
Allow working directories with uncommitted VCS changes to be
|
||
packaged.
|
||
|
||
--index index
|
||
The URL of the registry index to use.
|
||
|
||
--registry registry
|
||
Name of the registry to publish to. Registry names are defined in
|
||
Cargo config files
|
||
<https://doc.rust-lang.org/cargo/reference/config.html>. If not
|
||
specified, and there is a package.publish
|
||
<https://doc.rust-lang.org/cargo/reference/manifest.html#the-publish-field>
|
||
field in Cargo.toml with a single registry, then it will publish to
|
||
that registry. Otherwise it will use the default registry, which is
|
||
defined by the registry.default
|
||
<https://doc.rust-lang.org/cargo/reference/config.html#registrydefault>
|
||
config key which defaults to crates-io.
|
||
|
||
Package Selection
|
||
By default, the package in the current working directory is selected.
|
||
The -p flag can be used to choose a different package in a workspace.
|
||
|
||
-p spec, --package spec
|
||
The package to publish. See cargo-pkgid(1) for the SPEC format.
|
||
|
||
Compilation Options
|
||
--target triple
|
||
Publish 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
|
||
a list of supported targets. This flag may be specified multiple
|
||
times.
|
||
|
||
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
|
||
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.
|
||
|
||
See the features documentation
|
||
<https://doc.rust-lang.org/cargo/reference/features.html#command-line-feature-options>
|
||
for more details.
|
||
|
||
-F features, --features features
|
||
Space or comma separated list of features to activate. Features of
|
||
workspace members may be enabled with package-name/feature-name
|
||
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
|
||
Do not activate the default feature of the selected packages.
|
||
|
||
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.
|
||
|
||
--locked
|
||
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.
|
||
|
||
It may be used in environments where you want to assert that the
|
||
Cargo.lock file is up-to-date for reproducibility reasons, such as
|
||
in a CI build.
|
||
|
||
--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>.
|
||
|
||
--frozen
|
||
Equivalent to specifying both --locked and --offline.
|
||
|
||
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
|
||
the number of logical CPUs. If negative, it sets the maximum number
|
||
of parallel jobs to the number of logical CPUs plus provided value.
|
||
If a string default is provided, it sets the value back to defaults.
|
||
Should not be 0.
|
||
|
||
--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.
|
||
|
||
For example if the current package depends on dependencies fails and
|
||
works, one of which fails to build, cargo publish -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 publish -j1
|
||
--keep-going would definitely run both builds, even if the one run
|
||
first fails.
|
||
|
||
Display Options
|
||
-v, --verbose
|
||
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>.
|
||
|
||
-q, --quiet
|
||
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>.
|
||
|
||
--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
|
||
<https://rust-lang.github.io/rustup/overrides.html> for more
|
||
information about how toolchain overrides work.
|
||
|
||
--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.
|
||
|
||
-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
|
||
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.
|
||
|
||
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>).
|
||
|
||
-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. Publish the current package:
|
||
|
||
cargo publish
|
||
|
||
SEE ALSO
|
||
cargo(1), cargo-package(1), cargo-login(1)
|
||
|