Publishing packages to Crates.io - Rust for C-Programmers

23.9 Publishing Packages to Crates.io

Crates.io is the official Rust package registry. Publishing your library package allows others to easily use its contained crate(s) as dependencies. Most Rust projects (packages) are managed using Git for version control, and it’s common practice to host them on platforms like GitHub or GitLab. Before publishing, ensure your package is in a clean state in your version control system.

23.9.1 Prerequisites

Account: Create an account on Crates.io, usually via GitHub authentication.
API Token: Generate an API token in your account settings on Crates.io.
Login via Cargo: Authenticate your local Cargo installation with the token:
```
cargo login <your_api_token>
# Paste the token when prompted or provide it directly (less secure)
```
This stores the token locally (typically in ~/.cargo/credentials.toml).

23.9.2 Preparing `Cargo.toml`

Before publishing, ensure your Cargo.toml contains the required metadata in the [package] section for the package you want to publish:

name: The package name (must be unique on Crates.io).
version: The initial version (e.g., "0.1.0"), following SemVer.
license or license-file: A valid SPDX license identifier (e.g., "MIT OR Apache-2.0") or the path to a license file.
description: A brief summary of the package’s purpose.
At least one of documentation, homepage, or repository: Links providing more information. A repository link to your Git host (e.g., GitHub) is highly recommended.
authors, readme, keywords, categories are also highly recommended.

23.9.3 The Publishing Process

Version Control: Ensure all changes intended for the release are committed to your Git repository. The source code published to Crates.io should ideally match a tagged commit in your repository for easy reference.
Package (Optional but Recommended): Simulate the packaging process to check for errors and see exactly which files will be included in the archive that gets uploaded:
```
cargo package
```
Cargo uses .gitignore (and potentially a .cargoignore file if you need finer control beyond what .gitignore offers for packaging) to exclude unnecessary files. Review the generated .crate file (a compressed archive) in target/package/ if needed.
Publish: Upload the package to Crates.io:
```
cargo publish
```

Once published, the specific version of the package is permanent (though it can be “yanked”). Other users can now add your package as a dependency:

[dependencies]
your_package_name = "0.1.0"

23.9.4 Updating and Yanking

Updating: To publish a new version of your package, increment the version field in its Cargo.toml (following SemVer rules). It’s standard practice to commit these changes to your version control system (e.g., Git) before running cargo publish again. This ensures that the published package corresponds to a specific state in your project’s history.
Yanking: If you discover a critical issue (e.g., a security vulnerability) in a published version of your package, you can “yank” it. Yanking prevents new projects from depending on that specific version by default, but does not remove it or break existing projects that already have it in their Cargo.lock.
```
# Yank version 0.1.1 of your package
cargo yank --vers 0.1.1 your_package_name

# Un-yank (undo a yank)
cargo unyank --vers 0.1.1 your_package_name
```

23.9.5 Deleting Packages

Published package versions cannot be deleted from Crates.io to ensure builds that depend on them remain reproducible. Yanking is the standard mechanism for indicating problematic versions. In truly exceptional circumstances, you might contact the Crates.io team.