how to create your rust package

Here is a step-by-step guide to creating, structuring, and publishing your first Rust library crate to crates.io (the official Rust package registry).

How to Create and Publish a Rust Crate

Initialize the Crate: Use Cargo to scaffold the project. To create a new library crate, open your terminal and use the cargo new command with the --lib flag. If you were building an application, you would omit the flag.

cargo new my_awesome_crate --lib
cd my_awesome_crate

This generates a standardized project structure, initializing a Git repository along with it.

Understand the Project Layout: The heart of your crate. Cargo generates two primary files:
Cargo.toml: The manifest file containing metadata and dependencies.
src/lib.rs: The root file for your library’s code.

Update your Cargo.toml to include metadata required for publishing. You must add a description and a license.

[package]
name = "my_awesome_crate"
version = "0.1.0"
edition = "2021"
description = "A lightweight utility for doing awesome things."
license = "MIT OR Apache-2.0"
repository = "https://github.com/yourusername/my_awesome_crate"

Write Code and Tests: Writing your library code. Open src/lib.rs. You will see that Cargo has already generated a basic test function for you. Replace it with your actual logic.

In Rust, testing is built directly into the language. It is best practice to keep your unit tests in the same file as your code using the #[cfg(test)] module.

/// Adds two numbers together.
///
/// # Examples
///
/// ```
/// let result = my_awesome_crate::add(2, 2);
/// assert_eq!(result, 4);
/// ```
pub fn add(left: usize, right: usize) -> usize {
    left + right
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn it_works() {
        let result = add(2, 2);
        assert_eq!(result, 4);
    }
}

Run cargo test in your terminal to ensure everything works. Cargo will even run the code inside your documentation comments!

Log In to Cargo: Authenticate with crates.io. Before publishing, you need an account on crates.io.
Go to crates.io and log in with your GitHub account.
Navigate to your Account Settings and generate a new API token.
Back in your terminal, authenticate Cargo using the token:

cargo login <your-api-token>

Note: This saves your token locally in ~/.cargo/credentials. Do not share it!

Publish Your Crate: Sharing your crate with the world. Before uploading, it is highly recommended to do a dry run to ensure your crate packages correctly and passes all checks:

cargo publish --dry-run

If the dry run is successful and there are no uncommitted changes in your working directory, publish it for real:

cargo publish

Congratulations! Your crate is now live and can be installed by anyone using cargo add my_awesome_crate.

Best Practices for Rust Crates

Document Everything (Rustdoc): Rust has a world-class documentation generator. Use /// (three slashes) above functions, structs, and modules to document them. When you publish your crate, it will automatically be hosted and beautifully formatted on docs.rs.
Follow Semantic Versioning: Cargo heavily relies on SemVer (MAJOR.MINOR.PATCH). Only increment the MAJOR version when you make breaking API changes.
Include a README: Cargo will automatically look for a README.md file in your project root and display it on your crate’s page on crates.io. Make sure it includes a brief overview and a quickstart example.
Dual-License Your Code: The Rust ecosystem standard is to dual-license crates under both the MIT and Apache-2.0 licenses. This provides maximum compatibility for users wanting to integrate your library.