Cargo & dependencies

my_project/
├── Cargo.toml        ← the manifest: name, version, dependencies, features
├── Cargo.lock        ← exact versions chosen (generated, do not edit by hand)
├── src/
│   ├── main.rs       ← entry point of a binary
│   ├── lib.rs        ← root of a library (optional)
│   └── bin/
│       └── tool.rs   ← extra binary
├── tests/            ← integration tests
├── examples/         ← runnable examples (cargo run --example name)
├── benches/          ← benchmarks
├── build.rs          ← script run before compilation (optional)
└── target/           ← build output (do not commit)

Cargo finds these files by itself from their location: no declaration is needed as long as you follow this structure.

[package]
name = "my_project"
version = "0.1.0"
edition = "2024"
rust-version = "1.85"
authors = ["Your Name <[email protected]>"]
description = "A short description"
license = "MIT OR Apache-2.0"
repository = "https://github.com/me/my_project"
readme = "README.md"
keywords = ["web", "framework"]
categories = ["web-programming::http-server"]

[package]
name = "runique"
version.workspace = true
edition.workspace = true
rust-version.workspace = true
license.workspace = true

See section 10.

[dependencies]
# Short form: a version from crates.io
serde_json = "1.0"

# Inline table form: version + options
serde = { version = "1.0", features = ["derive"] }

# Without the default features, then pick yours
imagesize = { version = "0.15", default-features = false, features = ["heif"] }

# Optional: compiled only if a feature asks for it
sea-orm = { version = "2.0", optional = true }

# From git (branch, tag or commit)
my_crate = { git = "https://github.com/user/my_crate" }
my_crate2 = { git = "https://github.com/user/my_crate", branch = "dev" }
my_crate3 = { git = "https://github.com/user/my_crate", tag = "v1.2.0" }
my_crate4 = { git = "https://github.com/user/my_crate", rev = "a1b2c3d" }

# From a local folder
utils = { path = "../utils" }

# Local during development, crates.io when publishing
derive_form = { path = "../derive_form", version = "4.0.0" }

# Rename a dependency: it is used under the name `json` in the code
json = { package = "serde_json", version = "1.0" }

cargo add serde --features derive        # [dependencies]
cargo add tokio -F full                  # -F is short for --features
cargo add pretty_assertions --dev        # [dev-dependencies]
cargo add cc --build                     # [build-dependencies]
cargo add sea-orm --optional             # optional = true
cargo add imagesize --no-default-features -F heif
cargo add utils --path ../utils
cargo remove serde

cargo add writes the latest version compatible with your rust-version.

sea-orm = "=2.0.4"

Pinning is useful when a crate breaks compatibility without changing its breaking digit (it happens), or when two crates must stay exactly aligned (sea-orm and sea-orm-migration). The price: your crate cannot live alongside another one that asks for sea-orm = "2.0.5", because Cargo cannot pick a version that satisfies both.

[dev-dependencies]
pretty_assertions = "1.4"
reqwest = { version = "0.13", features = ["json"] }

Used only by tests, examples and benchmarks. They are never compiled into the shipped library, and they are not downloaded by those who depend on your crate.

Extra use: enabling a feature only for tests.

[dependencies]
runique = { version = "4.0", features = ["postgres"] }

[dev-dependencies]
runique = { version = "4.0", features = ["test-utils"] }

During cargo test, the two declarations are merged: postgres and test-utils are both active. With cargo build, only postgres is.

[build-dependencies]
cc = "1.0"
toml = "1"

Used by build.rs, a program compiled and run before your crate (generate code, compile C, read a configuration file). They are not available in src/. If you need the same crate in both, declare it in both sections (Runique does this for toml).

[target.'cfg(unix)'.dependencies]
libc = "0.2"

[target.'cfg(windows)'.dependencies]
windows-sys = "0.59"

[target.'cfg(target_arch = "wasm32")'.dependencies]
getrandom = { version = "0.3", features = ["wasm_js"] }

They are compiled only for the target platform. The code that uses them guards itself with the same #[cfg(unix)].

[patch.crates-io]
sea-orm = { git = "https://github.com/SeaQL/sea-orm", branch = "master" }

Replaces sea-orm everywhere in the tree, including when it is an indirect dependency. What it is for: testing a fix that is not published yet. It only applies to the root project (it is ignored when your crate is used as a dependency).

# Root Cargo.toml
[workspace.dependencies]
time = "=0.3.55"

This line forces nothing as long as no member writes time.workspace = true. To pin an indirect dependency (one you do not use yourself), you must declare it directly in the relevant member: this is what Runique does for time, otherwise cargo install would pick a newer version incompatible with cookie.

[features]
default = ["json"]                    # 1. other features of your crate
json = ["dep:serde_json"]             # 2. an optional dependency
derive = ["serde/derive"]             # 3. a feature of a dependency
full = ["json", "derive", "async"]    # group of features
async = ["dep:tokio", "tokio/rt"]     # combination
admin = []                            # 4. nothing else: only code under #[cfg]

[dependencies]
serde = "1.0"
serde_json = { version = "1.0", optional = true }
tokio = { version = "1", optional = true }

[features]
default = ["orm"]

Enabled automatically unless the user writes default-features = false (or --no-default-features). Keep it small: everything listed there will be compiled for all your users, and they can only remove it as a whole.

[dependencies]
serde_json = { version = "1.0", optional = true }

Notation 1: without dep:, Cargo automatically creates a feature named serde_json. Users can enable it directly (features = ["serde_json"]), and this name becomes part of your public API.

[features]
json = ["serde_json"]       # json enables the implicit serde_json feature

Notation 2: with dep: (Rust 1.60+), the implicit feature is no longer created. Only json is visible.

[features]
json = ["dep:serde_json"]

The second form is preferable: you choose the exposed names, and you can replace serde_json with another crate without breaking anyone. Runique uses it: orm = ["dep:sea-orm", "dep:sea-orm-migration"].

[features]
serde = ["dep:serde", "chrono?/serde"]

[dependencies]
serde = { version = "1.0", optional = true }
chrono = { version = "0.4", optional = true }

• "chrono/serde" enables chrono's serde and forces chrono to be compiled.
• "chrono?/serde" enables chrono's serde only if chrono is already enabled elsewhere.

What it is for: "if you use dates, make them serialisable", without forcing dates on someone who only wants serde.

[dependencies]
runique = { version = "4.0", features = ["postgres", "admin"] }

cargo build --features "json,async"      # features of the current package
cargo build -F json -F async             # same
cargo build --features runique/admin     # feature of a dependency, from the command line
cargo build --all-features               # all of them (careful: section 9)
cargo build --no-default-features        # no default feature
cargo build --no-default-features -F json

#[cfg(feature = "json")]
pub mod json {
    pub fn parse(input: &str) -> serde_json::Value {
        serde_json::from_str(input).unwrap_or_default()
    }
}

#[cfg(feature = "admin")]
pub fn with_admin(self) -> Self { self }

Without the feature, the module does not exist: it is neither compiled, nor checked, nor present in the binary. A user who calls my_project::json::parse without the feature gets "cannot find module json".

Direct consequence: an error inside a #[cfg(feature = "x")] block only shows up if you compile with x. So you must test every combination that matters (this is why Runique's CI builds several batches of features).

#[cfg(all(feature = "postgres", feature = "admin"))]
fn a() {}

#[cfg(any(feature = "sqlite", feature = "postgres"))]
fn b() {}

#[cfg(not(feature = "admin"))]
fn c() {}

#[cfg(all(unix, not(test)))]
fn d() {}

fn engine() -> &'static str {
    if cfg!(feature = "postgres") {
        "postgres"
    } else {
        "sqlite"
    }
}

cfg!(...) is replaced at compile time by true or false. Unlike #[cfg], both branches are compiled and so must be valid even when the feature is absent. You cannot call a function there that only exists under the feature.

#[derive(Debug, Clone)]
#[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
pub struct Point {
    pub x: i32,
    pub y: i32,
}

Point only implements Serialize if the user enables serde. What it is for: offering integration with a crate without forcing it.

#[cfg(feature = "orm")]
use sea_orm::DatabaseConnection;

pub struct Engine {
    pub name: String,
    #[cfg(feature = "orm")]
    pub db: DatabaseConnection,
}

Careful: a field or an enum variant under #[cfg] changes the shape of the type. User code that builds Engine { name } will stop compiling the day someone else in the tree enables orm (section 8). For a public type, prefer a field that is always present, or a constructor.

[package.metadata.docs.rs]
features = ["all-databases"]
# or: all-features = true

docs.rs builds your documentation with these features; without this section, only the default features are documented and all the code under #[cfg(feature)] is missing from the docs.

[package]
edition = "2024"      # resolver 3 by default

# In a workspace, it is declared at the root:
[workspace]
resolver = "3"

A virtual workspace (a root without [package]) has no edition: you must write resolver explicitly, otherwise Cargo falls back to resolver 1 and prints a warning.

cargo tree                       # dependency tree
cargo tree -i serde              # who depends on serde (inverted tree)
cargo tree -e features           # shows the features enabled on each edge
cargo tree -e features -i serde  # who enables which feature of serde
cargo tree -d                    # crates in several versions
cargo tree --no-default-features -F postgres   # the tree for a precise combination

#[cfg(all(feature = "postgres", feature = "sqlite"))]
compile_error!("features `postgres` and `sqlite` are exclusive: pick a single engine");

The build stops with a clear message, instead of inconsistent behaviour or an obscure type error.

Runique does exactly this for sqlite, postgres and mysql, with an explicit escape hatch:

#[cfg(all(
    not(doc),
    not(feature = "all-databases"),
    feature = "postgres",
    feature = "sqlite"
))]
compile_error!("features `postgres` and `sqlite` are mutually exclusive");

• not(doc): cargo doc and docs.rs can document all the engines;
• all-databases: a feature you have to ask for by name, for tools that talk to all three engines.

# Root Cargo.toml (virtual workspace: no [package])
[workspace]
members = [
    "runique/runique_dsl",
    "runique/derive_form",
    "runique",
    "demo-app",
]
resolver = "3"

[workspace.package]
version = "4.0.0"
edition = "2024"
rust-version = "1.94"
license = "MIT"

[workspace.dependencies]
serde = { version = "1.0", features = ["derive"] }
tokio = { version = "1", features = ["full"] }
derive_form = { path = "runique/derive_form", version = "4.0.0" }

members accepts wildcards (members = ["crates/*"]) and exclude removes folders.

# runique/Cargo.toml
[package]
name = "runique"
version.workspace = true
edition.workspace = true

[dependencies]
serde.workspace = true
# Inherit and add: features are added to those of the workspace
tokio = { workspace = true, features = ["test-util"] }
# Inherit and make optional
sea-orm = { workspace = true, optional = true }
derive_form.workspace = true

What you can add to an inherited dependency: features (added), optional. You cannot change the version or remove a feature.

# Implicit: src/lib.rs, src/main.rs, src/bin/*.rs, examples/*.rs are found automatically.

# Explicit: different name or path
[lib]
name = "runique"
path = "src/lib.rs"

[[bin]]
name = "runique"
path = "src/bin/runique.rs"

[[example]]
name = "demo"
required-features = ["admin"]

[[bin]] (double brackets) is an array: you can declare several.

[[bin]]
name = "admin-tool"
required-features = ["admin"]

The binary is only built if the feature is active. Without it, cargo build skips it without an error.

[profile.release]
opt-level = 3          # 0, 1, 2, 3, "s" (size), "z" (minimal size)
lto = "fat"            # link-time optimisation: faster binary, slower build
codegen-units = 1      # less parallelism, better optimisation
strip = true           # removes symbols: smaller binary
panic = "abort"        # no stack unwinding: smaller, but no more catch_unwind
debug = false

[profile.dev]
opt-level = 0
debug = true
incremental = true

[profile.dev.package."*"]
opt-level = 2

All the dependencies are optimised, your code stays at opt-level = 0 (fast build). What it is for: some crates are unusable in debug. Hashing a password with argon2 can take several seconds without optimisation and a few dozen milliseconds with it.

[profile.profiling]
inherits = "release"
debug = true

cargo build --profile profiling

fn main() {
    // Value read at run time: with a hard-coded constant,
    // the compiler would detect the overflow and refuse to compile.
    let x: u8 = std::env::args().count() as u8 + 254;
    let y = x + 1;     // dev: panics "attempt to add with overflow"
                       // release: equals 0 (wrap-around), no error
}

Profiles only belong to the root project: those declared in your dependencies are ignored.

[lints.rust]
unsafe_code = "forbid"
missing_docs = "warn"

[lints.clippy]
unwrap_used = "warn"
pedantic = { level = "warn", priority = -1 }
module_name_repetitions = "allow"

# root
[workspace.lints.clippy]
unwrap_used = "warn"

# member
[lints]
workspace = true

cargo new my_project          # new binary
cargo new my_lib --lib        # new library
cargo init                    # in an existing folder

cargo check                   # analyses and type-checks without producing a binary: the fastest
cargo build                   # builds in debug
cargo build --release         # builds in release
cargo run -- arg1 arg2        # builds, runs, passes the arguments after --

cargo test                    # all tests
cargo test test_name          # tests whose name contains this text
cargo test -- --nocapture     # show the println! output of tests

cargo clippy --all-targets -- -D warnings   # linter, warnings as errors
cargo fmt                     # format
cargo fmt --check             # check without modifying (CI)

cargo doc --open              # local documentation
cargo tree                    # dependency tree
cargo update                  # update Cargo.lock
cargo clean                   # empty target/

cargo install ripgrep         # install a published binary
cargo install --path .        # install the binary of the current project

cargo login <your_token>      # once
cargo package --list          # files that will be uploaded
cargo publish --dry-run       # checks that the package builds on its own
cargo publish

a = "1.2"                                        # >=1.2.0, <2.0.0
b = "0.3"                                        # >=0.3.0, <0.4.0
c = "=2.0.4"                                     # exactly
d = { version = "1", features = ["x"] }
e = { version = "1", default-features = false }
f = { version = "1", optional = true }
g = { path = "../g", version = "1" }
h = { git = "https://...", tag = "v1" }
i = { package = "real_name", version = "1" }     # renaming
j.workspace = true

[features]
default = ["a"]
a = []                       # code under #[cfg(feature = "a")]
b = ["dep:opt_crate"]        # optional dependency without an implicit feature
c = ["serde/derive"]         # feature of a dependency
d = ["chrono?/serde"]        # only if chrono is already active

#[cfg(feature = "a")]            // the code disappears without the feature
if cfg!(feature = "a") { }       // compiled in all cases, value fixed
#[cfg_attr(feature = "s", derive(serde::Serialize))]
#[cfg(all(feature = "x", feature = "y"))]
compile_error!("x and y are exclusive");