skip to content

Cargo.toml Manifest

Cargo.toml's [package] table names the crate, its edition and minimum Rust version, and its targets decide what gets built. Interviewers ask how a library and binaries share one package.

on this pageshow

explore

questions

5

In a Cargo.toml [package] table, what do name, version, edition, rust-version and license do, and which key is actually required?

level: juniorimportance: must knowfreq 70%

answer

  1. one key Cargo cannot do without
  2. a historical fallback edition
  3. 0.0.0 when the version is missing
  4. a bare toolchain floor, not a range
  5. SPDX expressions with OR and AND

basics

~20 s

Only name is required: it names the package and its default targets. version defaults to 0.0.0, a missing edition falls back to 2015 with a warning, rust-version is the oldest supported toolchain, and license is metadata a registry needs.

solid answer

~40 s

Cargo needs only `name`: it identifies the package as a dependency and is the default name of its library and binary targets (the library swaps dashes for underscores). `version` is a three-part SemVer version; since Cargo 1.75 it is optional and defaults to `0.0.0`, but publishing needs it. `edition` picks the Rust edition for every target in the package, and when it is missing Cargo assumes **2015** and warns, which is why `cargo new` always writes `edition = "2024"`. `rust-version` is a bare version such as `"1.85"` naming the oldest toolchain you support; Cargo refuses older compilers. `license` holds an SPDX expression such as `"MIT OR Apache-2.0"` (or `license-file` points at a text); crates.io insists on one of them.

code

toml · 7 lines
toml
[package]
name = "geo-tiles"
version = "0.4.2"
edition = "2024"
rust-version = "1.85"
license = "MIT OR Apache-2.0"
description = "Slippy-map tile maths and seeding tools"

go deeper

for a junior

Recall that name is the one required key, that cargo new writes the current edition for you, and that a library named geo-tiles is used in code as geo_tiles.

for a middle

Explain each default: version falls back to 0.0.0, a missing edition means 2015 with a warning, and rust-version is a bare version Cargo checks against the active rustc.

for a senior

In review, catch a hand-written manifest with no edition, a rust-version below the edition's floor, and licence metadata missing before a release rather than at publish time.

for a principal

Treat the header as a contract: the edition and rust-version you set decide which toolchains your users must run, so they deserve the same scrutiny as a public API change.

## What the `[package]` table is Every Cargo package has one manifest, `Cargo.toml`, written in TOML. Its `[package]` table is the package's identity card: Cargo reads it before it compiles anything, and other tools (registries, `cargo metadata`, documentation hosts) read the same keys. The table carries many optional keys, but five of them come up in nearly every review of a new crate: `name`, `version`, `edition`, `rust-version` and `license`. | Key | Required by Cargo? | When it is missing | Who relies on it | |---|---|---|---| | `name` | **yes** | the manifest fails to parse: `missing field package.name` | dependents, default target names | | `version` | no (since Cargo 1.75) | `0.0.0` | the resolver, `cargo publish` | | `edition` | no | the **2015** edition, plus a warning | rustc, for every target | | `rust-version` | no | no toolchain check at all | Cargo's toolchain check, `cargo add`, the resolver | | `license` | no | nothing locally | crates.io (or `license-file`) | ## `name` and `version` - **`name`** may use letters, digits, `-` and `_`. It is the name another package writes in its `[dependencies]`, and it becomes the default name of the inferred targets: the binary built from `src/main.rs` keeps the name as written (`geo-tiles`), while the library's crate name replaces dashes with underscores (`geo_tiles`), because a Rust path cannot contain a dash. `cargo new` adds stricter checks, such as rejecting Rust keywords. - **`version`** follows SemVer with exactly three numeric parts, optionally a pre-release (`1.0.0-alpha.11`) and build metadata after `+`, which Cargo generally ignores. A two-part value such as `"0.1"` is rejected at parse time. Before Cargo 1.75 the key was mandatory; now an unpublished internal tool can omit it and Cargo reports version `0.0.0`. ## `edition`: the key with the dangerous default The edition selects which edition of the Rust language rustc applies to **every** target in the package: library, binaries, examples, tests and benches. Editions are opt-in and per crate, so a 2024 crate can depend on a 2015 one. 1. `cargo new` and `cargo init` write the current edition, `"2024"`. 2. If the key is absent, Cargo falls back to **2015** for backward compatibility and prints `` `package.edition` is unspecified, defaulting to `2015` while the latest is `2024` ``. 3. An edition newer than the running Cargo knows (say `"2027"`) is a hard error naming the editions it supports. The fallback matters because a hand-written manifest silently compiles under the oldest rules: code that uses `async` as a variable name still builds, and newer edition behaviour is simply absent. What each edition changes in the language is the subject of the Rust editions material; on the manifest side the rule is short: always write the key. ## `rust-version` and `license` - **`rust-version`** declares the minimum supported Rust version (MSRV) as a bare version, `"1.85"` or `"1.85.1"`, never a requirement such as `"^1.85"`. When the active `rustc` is older, Cargo stops with an error before compiling; `--ignore-rust-version` overrides it. Cargo also rejects a value lower than the edition needs: the 2024 edition requires 1.85, the 2021 edition 1.56. - **`license`** is an SPDX 2.3 expression: `OR` lets users choose (`"MIT OR Apache-2.0"`), `AND` obliges them to comply with both, and `WITH` attaches an exception. A non-standard licence goes in a file named by `license-file` instead. Cargo itself does not need either key to build; crates.io requires one of them, plus `description`, before it accepts a publish. - **`authors`** is deprecated and optional; leaving it out costs nothing. ## Where the values surface in code Cargo hands the `[package]` values to rustc as environment variables when it compiles each crate, so code can read them at compile time with `env!`: - `CARGO_PKG_NAME` and `CARGO_PKG_VERSION` (plus `CARGO_PKG_VERSION_MAJOR`, `_MINOR`, `_PATCH` and `_PRE`) are the usual source of a tool's `--version` output, so the manifest stays the single place the version lives; - `CARGO_PKG_RUST_VERSION`, `CARGO_PKG_LICENSE` and `CARGO_PKG_DESCRIPTION` mirror the other keys, empty when the key is unset. `println!("{} {}", env!("CARGO_PKG_NAME"), env!("CARGO_PKG_VERSION"))` in the `geo-tiles` binary prints `geo-tiles 0.4.2`; bumping `version` in `Cargo.toml` is all a release needs to change. ## A complete header A library-plus-tools package might start like this, and `cargo metadata` reports exactly these values back: ```toml [package] name = "geo-tiles" version = "0.4.2" edition = "2024" rust-version = "1.85" license = "MIT OR Apache-2.0" description = "Slippy-map tile maths and seeding tools" ``` Reading a header in review, check three things first: the edition is present and current, the version has three parts, and `rust-version` is at least the edition's floor. Everything else in `[package]` is either target control (`default-run`, `autobins`) or publishing metadata.

  • Why does a library named geo-tiles get imported as geo_tiles?
    The package name may contain dashes, but a Rust path cannot, so Cargo derives the library's crate name by replacing dashes with underscores. Binaries keep the dashed name because it is only a file name. A `[lib] name = "..."` entry can set a different crate name explicitly.
  • What happens if rust-version is lower than the edition allows?
    Cargo refuses to parse the manifest. With `edition = "2024"` and `rust-version = "1.80"` it reports that rust-version 1.80 is incompatible with the version (1.85.0) required by the specified edition (2024), because no 1.80 compiler could build a 2024-edition crate.
  • Does Cargo need license or description to build the package?
    No. Both are metadata: Cargo builds without them, and `cargo package` only warns about missing description-style metadata. crates.io is what rejects a publish without `license` or `license-file` and without `description`.

  • Cargo refuses to build a package whose manifest lacks an edition key.
  • A missing edition means the newest edition Cargo knows.
  • version is mandatory in every Cargo.toml, even for unpublished tools.
  • rust-version accepts a requirement such as ^1.80, like a dependency.
  • The library crate name keeps the dashes from the package name.

Assumes Cargo 1.99.1; package.version has been optional (default 0.0.0) since Cargo 1.75, and the 2024 edition needs Rust 1.85.

open as a page

In a Cargo package with src/lib.rs, src/main.rs and two files in src/bin/, which targets does Cargo build, and how do the binaries reach the library?

level: middleimportance: must knowfreq 60%

basics

~20 s

Cargo discovers one library from src/lib.rs and a binary from src/main.rs plus one per file in src/bin/. Each binary is a separate crate that links the library and calls its public API by crate name, for example geo_tiles::tiles_per_edge.

open as a page

In a Cargo.toml [lib] table, what do crate-type values lib, rlib, cdylib and staticlib produce, and what breaks when only cdylib is listed?

level: middleimportance: should knowfreq 35%

basics

~20 s

lib (the default) and rlib emit a Rust library for Rust crates; cdylib a shared library for other languages; staticlib an archive bundling every dependency. Listing only cdylib leaves the package's own binaries and tests nothing to link.

open as a page

A Cargo.toml [[bin]] named tile-admin has required-features = ["admin"]; why does cargo build skip it silently, and how do you keep it compiling?

level: seniorimportance: should knowfreq 25%

basics

~20 s

required-features makes Cargo skip the target whenever a listed feature is off, so cargo build without --features admin never compiles it. Only naming it with --bin errors. CI must build with the feature, or the tool silently rots.

open as a page

A Cargo.toml declares rust-version = "1.80", yet users on Rust 1.80 hit compile errors inside the crate; what does rust-version actually make Cargo enforce?

level: seniorimportance: should knowfreq 35%

basics

~20 s

Cargo enforces rust-version as a floor: it refuses a rustc older than the declared version, for the package and its dependencies. It never checks that the code avoids newer APIs, so the claim can silently go false.

open as a page