====== Publish to Crates.io ======

===== Before You Publish =====

==== API Token ====

  - Log in at https://crates.io/
  - Go to **Account Settings**, then **API Tokens**
  - Click "New Token"
  - Give it a unique name.
  - Set an expiration date (optional)
  - Select the scopes you need.  I used ''publish-new'', ''publish-update'', and ''yank''.
  - Click "Generate Token".

The generated API token value will look similar to this:

<code>
ciowhNhkHp4WpZCYjA27AENzrhO9c9T9m4r
</code>

It is stored on crates.io as a hash (for security), and is only displayed once.  Make sure you document it in a safe place.

This step only needs to be done once, unless you forget your token value, or it becomes compromised. In that case, you'll need to revoke it and generate a new one.

==== Log In ====

Open a terminal, and type:

<code bash>
cargo login
</code>

When prompted, paste your generated token.

This token will be stored locally in ''~/.cargo/credentials.toml''. If you ever need to use a different token, first logout:

<code bash>
cargo logout
</code>

This removes the token from your credentials file. Then, you can log in again.

===== Metadata in Cargo.toml =====

^ Tag ^ Example ^
| license | "MIT OR Apache-2.0" |
| description | "A short description of my package" |
| homepage | <nowiki>"https://serde.rs"</nowiki> |
| documentation | <nowiki>"https://docs.rs/bitflags"</nowiki> |
| repository | <nowiki>"https://github.com/rust-lang/cargo"</nowiki> |
| readme | "README.md" |

Source: https://doc.rust-lang.org/cargo/reference/manifest.html

===== Validate and Publish =====

Check your project for warnings and errors:

<code bash>
cargo package
</code>

You can also list the contents of the generated .crate file:

<code bash>
cargo package --list
</code>

When you're ready to publish:

<code bash>
cargo publish
</code>

===== Sources =====

https://doc.rust-lang.org/cargo/reference/publishing.html

{{tag>rust}}