Rust — Async Await

What a crate is

A crate is the smallest unit of code Rust compiles at once. Every cargo build produces at least one:

• Binary crate — compiles to an executable, requires a fn main()
• Library crate — compiles to a reusable .rlib, no main, meant for others to import

A package may contain both: logic in the lib crate, interface in the bin crate.

Crate roots

Every crate has a root file where the compiler starts building its module tree:

src/main.rs   ← binary crate root
src/lib.rs    ← library crate root

All mod declarations chain outward from these files. The name comes from Cargo.toml — hyphens become underscores in code (my-tool → my_tool).

The crates you already depend on

std — implicit everywhere

let v = vec![1, 2];        // std::vec::vec!
use std::collections::HashMap;

The standard library links into every crate automatically; only external dependencies need declaring.

Popular ecosystem crates

Crate	Purpose
serde + serde_json	serialize/deserialize anything
tokio	async runtime
clap	command-line argument parsing
rand	randomness
reqwest	HTTP client
axum / actix-web	web servers
anyhow / thiserror	ergonomic error handling
regex	pattern matching

[dependencies]
clap = { version = "4", features = ["derive"] }

Using another crate's items

use rand::Rng;                     // trait must be in scope for methods!

fn main() {
    let n = rand::thread_rng().gen_range(1..=6);
    println!("dice: {}", n);
}

That use rand::Rng line trips up everyone once — traits must be imported before their methods appear.

Publishing your own crate

$ cargo login <api-token>       # from crates.io/account
$ cargo publish                 # builds, verifies, uploads

Requirements: unique name (crates.io enforces), semver version bump for re-publishes (0.1.0 → 0.1.1), license field recommended. Published versions are permanent — you can yank but never delete.

Semantic versioning in Cargo.toml

rand = "0.8"        means ">=0.8.0, <0.9.0"   — caret default
rand = ">=0.7, <0.9"
rand = "=0.8.5"     exact pin

Cargo.lock pins exact versions for reproducible builds; cargo update refreshes within ranges.

Docs & metadata polish

[package]
name = "my-crate"
version = "0.1.0"
edition = "2021"
description = "One-line summary shown on crates.io"
license = "MIT OR Apache-2.0"
repository = "https://github.com/you/my-crate"
documentation = "https://docs.rs/my-crate"

docs.rs auto-builds documentation for every published release — keep doc comments healthy.

Mini Practice

1. Add clap with derive; parse --name flag into a greeting.
2. Find one crate's docs.rs page; locate an example.
3. Split a project into lib.rs (logic) + main.rs (CLI).
4. cargo publish a throwaway crate to test the flow (dry-run first: cargo publish --dry-run).

Next: async await →