FAQ docs request: What is the distinction between 'crate' and 'package'?

[frewsxcv]

I spoke with @steveklabnik a couple nights ago and they informed that the terms 'crate' and 'package' are different concepts in the context of cargo. Someone in the #rust-tools channel on IRC just asked what the differences are. It might be worth clarifying this in the Frequently Asked Questions section (or maybe a different section?).

I'd be happy to write-up something for this, but I actually don't recall the distinctions from the conversation :)

[frewsxcv]

For reference, the questions the user asked on IRC:

terminology question: what is the difference between a "crate" and a "package"?
`cargo metadata` list `packages` for instance, and Cargo.toml has a `package` section as well
but rustc only builds crates (--crate-type, --crate-name), and in Rust files you also declare "extern crate foo"
and it they refer to the same thing: the "foo" crate will be listed as a "package" by `cargo metadata`
is there a subtle distinction?

[steveklabnik]

It's confusing because we don't often use the terms in a clear way.

A cargo.toml is associated with a package, which is why it has [package] at the top. A package can have 0-1 library and 0-n binary crates, minimum 1.

[fmdkdd]

So the package is the "source" from which crates are created? And when I say "extern crate foo" in a Rust file, I'm actually referring to the rlib crate that's built by cargo after downloading the foo package from crates.io because I added the dependency on that package in the Cargo.toml?

So, when I choose a target with cargo build --bin foo, am I building the binary crate "foo"? Are targets for cargo the same as crates? Or can there be targets that do not end up building crates?

(I was the one who asked the question on IRC).

[matklad]

So, when I choose a target with cargo build --bin foo, am I building the binary crate "foo"?

Yes.

Are targets for cargo the same as crates?

Yes. Library, binaries, exercises, integration tests all are different targets/crates.

So the package is the "source" from which crates are created?

Yes. It's a Cargo.toml plus the Rust source code.

And when I say "extern crate foo" in a Rust file, I'm actually referring to the rlib crate that's built by cargo after downloading the foo package from crates.io because I added the dependency on that package in the Cargo.toml?

Yes. Cargo downloads the package named foo from crates.io, builds its library target (crate) and wires it in to the corresponding extern crate declaration. An interesting thing to note that crate names (foo) are controlled by cargo during the build process. That is, the binary for the library does not know its name at all.

[fmdkdd]

@steveklabnik @matklad Okay thank you. I think I am less confused now ;)

[joshtriplett]

So, the *.crate files on crates.io contain the source for Cargo packages, not Cargo crates?

[steveklabnik]

Well both. That is, packages contain one or more crates. The Cargo.toml contains configuration for the whole package, under [package], and then for each specific crate under [lib] or [[bin]].