[Rust Guide] 14.4. Publishing Crates Part 2

If you find this helpful, please like, bookmark, and follow. To keep learning along, follow this series.

14.4.1 Create and Set Up a crates.io Account

Before publishing any crate, you need to have a crates.io account and obtain an API token. To do this, visit the crates.io homepage and sign in with a GitHub account. Currently, only GitHub login is supported. If you are already signed in, open your account settings at https://crates.io/me/ and find the API key. Then use the cargo login command locally and paste your API key when prompted:

$ cargo login
just1a1nexample

This command tells Cargo your API token and stores it locally in ~/.cargo/credentials. Note that this token must not be shared with anyone else. If you leak it, you should revoke it and generate a new token on crates.io.

14.4.2 Add Metadata to the Crate

Before publishing a crate, you also need to add some metadata to the [package] section in Cargo.toml:

• First, make sure the project name is unique on the website.
• Second, write a description, which is a short introduction. It does not need to be long; one or two sentences is enough. The description will appear in crate search results.
• You need to provide the license identifier value used by this crate (you can look it up at spdx.org/licenses/); you can specify multiple licenses, separated by OR, in license.
• Semantic version information goes in version.
• Author information goes in authors.

Of course, you can provide more information than that; for details, see the Cargo Book.

The full [package] section should look like this:

[package]
name = "guessing_game"
version = "0.1.0"
edition = "2021"
description = "A fun game where you guess what number the computer has chosen."
license = "MIT OR Apache-2.0"

14.4.3 Publish a Crate with a Command

You can publish a crate with the cargo publish command, but only if the metadata is complete and the project name is unique.

When cargo publish runs successfully, it sends a verification email to the address registered to your crates.io account; just confirm it in your inbox.

If something goes wrong, cargo publish reports an error:

$ cargo publish
    Updating crates.io index
warning: manifest has no description, license, license-file, documentation, homepage or repository.
See https://doc.rust-lang.org/cargo/reference/manifest.html#package-metadata for more info.
......
error: failed to publish to registry at https://crates.io

Caused by:
  the remote server responded with an error: missing or empty metadata fields: description, license. Please see https://doc.rust-lang.org/cargo/reference/manifest.html for how to upload metadata

I omitted some of the middle content. The Caused by section says that the error was caused by missing metadata.

Once a crate is published, it is permanent: that version cannot be overwritten, and the code cannot be deleted. This is so projects depending on that version can continue to work normally.

14.4.4 Publish a New Crate Version

If you need to publish a newer version of an existing crate, modify the crate source code, update the version value in Cargo.toml according to semantic versioning, and then publish again.

14.4.5 Yank a Version

Yanking a version prevents new projects from depending on that version, but projects that were already built against it can still use and download it.

The command is cargo yank --vers the-specified-version. For example, to yank version 1.0.1, write:

cargo yank --vers 1.0.1

If you change your mind after yanking and want to undo it, write:

cargo yank --vers 1.0.1 --undo

yank means:

• Projects that already have a generated Cargo.lock will not be interrupted by the version being yanked.
• Future Cargo.lock files will not use the yanked version.