jeffa.io

Rust Packages vs Crates



Rust Packages vs Crates

It is a common misconception that packages are crates and visa versa. I will admit that this is a pet peeve. But for Rust coders, it is important to know the difference because otherwise you are denied an understanding of how Rust code is organized, shared and consumed.

Crate

A crate, like a module inside of a crate, is a means of organizing code.

A crate is either a binary or a library.

A crate is not published independently, but rather as a member of its package.

The compiler knows what a crate is and uses crates as namespaces for items. If std::hash::Hash is not in scope, you can define your own trait called Hash.

Package

A package is a wrapper for at least one crate.

A package is publishable.

A package can contain one or zero library crates.

A package can contain any number of binary crates.

When you add a package to your dependencies, you consume the one library crate inside of that package.

When you use cargo run or cargo install without specificying a crate, you consume the one binary crate in that package.

When you use cargo run –bin or cargo install –bin followed by a crate name, you consume the specified binary crate in that package.

Why Is There Confusion About This?

I think the reason people get mixed up is because crates.io is actually a repository for packages. If you find a library on crates.io, you add the package to the dependencies in your Cargo.toml file. You don’t have to specificy the crate because a package can only have one library crate. If the default repository were called “packages.io”, this may be less of an issue.

As always, The Book is there as an easy-to-read authority that clears up these little confusions.

The Rust Programming Language: Packages and Crates