Understanding Rust Crates, Cargo.toml, and Common Cargo Commands

1. What is a Crate?

Basic concept: A crate is Rust’s compilation unit and code organization unit, similar to a package, library, or module in other languages.

A crate can be: ① binary crate – an executable program. ② library crate – a library used by other programs.

Crate types:

// 1. Binary crate - has a main function
fn main() {
    println!("Hello, world!");
}

// 2. Library crate - provides functionality for other crates
pub fn add(a: i32, b: i32) -> i32 {
    a + b
}

2. What is Cargo.toml?

Basic concept: Cargo.toml is the configuration file for a Rust project, similar to pom.xml in Java, pyproject.toml or setup.py in Python, and package.json in Node.js.

Basic structure:

[package]
name = "my_project"           # project name
version = "0.1.0"             # version
edition = "2021"              # Rust edition
authors = ["Your Name <[email protected]>"]
description = "A sample Rust project"
license = "MIT"

[dependencies]               # dependencies
serde = "1.0"                 # serialization library
tokio = { version = "1.0", features = ["full"] }
reqwest = "0.11"

[dev-dependencies]            # development dependencies
criterion = "0.4"

[build-dependencies]          # build dependencies
cc = "1.0"

[[bin]]                       # binary target
name = "my_app"
path = "src/main.rs"

[lib]                         # library target
name = "my_lib"
path = "src/lib.rs"

Example from the lance-namespace project’s Cargo.toml:

// From lance-namespace Cargo.toml
[package]
name = "lance-namespace"
version = "0.0.14"
edition = "2021"
authors = ["Lance Namespace Contributors"]
description = "Lance Namespace Rust Client - A unified interface for managing namespaces and tables"
license = "Apache-2.0"
repository = "https://github.com/lancedb/lance-namespace"
documentation = "https://docs.rs/lance-namespace"
readme = "README.md"
keywords = ["lance", "namespace", "table", "database"]
categories = ["database"]

[dependencies]
async-trait = "0.1"
thiserror = "1.0"
bytes = "1.5"
reqwest = { version = "0.12", features = ["json"] }
lance = "0.31"
opendal = { version = "0.54", features = ["services-fs", "services-s3", "services-gcs", "services-azblob"] }
arrow = "55.2"
serde = { version = "1.0", features = ["derive"] }
serde_json = "1.0"
url = "2.5"

# Use models from the reqwest client
lance-namespace-reqwest-client = { workspace = true }

[dev-dependencies]
tokio = { version = "1.35", features = ["full"] }
wiremock = "0.6"
tempfile = "3.20"

3. Cargo Commands

Common commands:

# Create a new project
cargo new my_project        # binary project
cargo new --lib my_lib     # library project

# Build the project
cargo build                # debug build
cargo build --release      # release build

# Run the project
cargo run                  # run binary project
cargo run --bin my_app     # run a specific binary

# Test
cargo test                 # run tests

# Check code
cargo check                # quick syntax check
cargo clippy               # code quality lint

# Documentation
cargo doc                  # generate docs
cargo doc --open           # generate and open docs

# Publish
cargo publish              # publish to crates.io

Project structure example:

my_rust_project/
├── Cargo.toml               # configuration file
├── Cargo.lock               # lock file for dependencies
├── src/
│   ├── main.rs              # binary crate entry point
│   ├── lib.rs               # library crate entry point
│   └── bin/
│       └── another.rs       # additional binary
├── tests/                   # integration tests
│   └── integration_test.rs
├── examples/                # example code
│   └── example.rs
└── benches/                 # benchmark tests
    └── benchmark.rs