3

I come from a Java background and have recently started with Rust.

The official Rust doc is pretty self-explanatory except the chapter that explains Crates and Packages.

The official doc complicates it with so many ORs and ANDs while explaining the two.

This reddit post explains it a little better, but is not thorough.

What is the exact difference between a Crate and Package in Rust? Where/When do we use them?

Much thanks!

2
  • You don't have to BOLD links and images and other phrases. Bold is only used for text, and only when needed for emphasis. You also don't need to repeat tag information in the title (in Rust) when you've added a tag for Rust. You also don't need to code-format Rust or add an image to the word - anyone who can answer your question doesn't need an image or link to it, and it's not code that needs formatting.
    – Ken White
    Jul 5, 2021 at 5:16
  • 2
    "Crate" is the compiler's unit of compilation. "Package" is not a concept the compiler knows anything about: it is purely an artefact of Cargo (Rust's default build tool: you can use other build tools if you prefer). A "package" (defined by the Cargo.toml file) links together related crates: zero or more "binary" crates, at most one "library" crate (defined in the same package), and zero or more "dependency" crates (defined in external packages).
    – eggyal
    Jul 5, 2021 at 9:22

1 Answer 1

9

Crates

From the perspective of the Rust compiler, "crate" is the name of the compilation unit. A crate consists of an hierarchy of modules in one or multiple files. This is in contrast to most "traditional" compiled languages like Java, C or C++, where the compilation unit is a single file.

From the perspective of an user, this definition isn't really helpful. Indeed, in most cases, you will need to distinguish between two types of crates:

  • binary crates can be compiled to executables by the Rust compiler. For example, Cargo, the Rust package manager, is a binary crate translated by the Rust compiler to the executable that you use to manage your project.
  • library crates are what you'd simply call libraries in other languages. A binary crate can depend on library crates to use functionality supplied by the libraries.

Packages

The concept of packages does not originate in the Rust compiler, but in Cargo, the Rust package manager. At least for simple projects, a package is also what you will check into version control.

A package consists of one or multiple crates, but no more than one library crate.

Creating packages

  • to create a new package consisting of one binary crate, you can run cargo new
  • to create a new package consisting of one library crate, you can run cargo new --lib
  • to create a package consisting of a library as well as one or multiple binaries, you can run either cargo new or cargo new --lib and then modify the package directory structure to add the other crate

When should you use crates, and when should you use packages?

As you can see now, this question doesn't really make sense – you should and must always use both. A package can't exist without at least one crate, and a crate is (at least if you are using Cargo) always part of a package.

Therefore, a better question is this:

When should you put multiple crates into one package?

There are multiple reasons to have more than one crate in a package. For example:

  • If you have a binary crate, it is idiomatic to have the "business logic" in a library in the same package. This has multiple advantages:
  • If you have a library crate that generates some files (a database engine or something like that), you may want to have a helper binary to inspect those files

Note that if you have a very big project, you may instead want to use the workspace feature of Cargo in these cases.

0

Your Answer

Reminder: Answers generated by Artificial Intelligence tools are not allowed on Stack Overflow. Learn more

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.