Define the meaning of crate

[elahn]

The meaning of the term "crate" could be inferred, but stating it explicitly may lead to less confusion.

[steveklabnik]

packages and crates are different. a package is a collection of crates...

[carols10cents]

We do define crate in the first place that we actually say the word crate: https://github.com/rust-lang/book/blame/master/src/ch02-00-guessing-game-tutorial.md#L311

And we're changing this slightly on this unmerged PR that will be merged soon: https://github.com/rust-lang/book/pull/192/files#diff-72abe2e4f06575ae5318165fb3b3e5a5R346

@steveklabnik is the definition in the 2nd place i just linked to wrong?

[carols10cents]

Ok i lied, it's not the first place we say "crate"... but we do define it eventually. Maybe we should move this text up then.

[steveklabnik]

To be clear, I'm all about making this more clear, it's just that it's complicated, so we kinda skirted around it because it's really complicated to get into this early in the book.

A crate is what we call a package of Rust code.

Yeah, so this definition is problematic because "package" does mean something specific in terms of Cargo, but you're using it in a general sense here.

Historically speaking, a "compilation unit" is the definition we use. This comes from C and C++, which has three phases of "here's my source" to "here's something I run":

1. Preprocessing, this is where cpp (the c preprocessor, not "c plus plus", oh my) does #include and all that jazz
2. Compiling, taking the output of preprocessing and turning it into an object file
3. Linking, taking one or many object files, putting them together, and getting an ELF binary or .exe

Rust doesn't have a preprocessing step in this sense, and we call out to a system linker, so rustc only really does step 2. And I believe that technically, it's "translation unit", even though most people say "compilation unit."

So yeah, in some sense, a crate is "that pile of source code you pass the root of to rustc", but that feels too circular to be good. "compilation unit" is technically precise, but is gibberish to a lot of people. And a "package" is "one or more crates", which confusingly, gets wrapped up by cargo package into a file which ends in .crate, but is secretly a tarball.

Whew!

Soooooooooooooooooo yeah, I don't know how to be both technically precise, yet accessible.

[carols10cents]

Ok, so I've decided that instead of merging this, I'm adding the same definition of crate to the actual first place we use the word. I'm going to adjust the version that's on the PR I mentioned to say something like "Remember we said that a crate is... binary crates are.. library crates are...". But thank you for pointing this out, @elahn!! ☝️ 👇 👈 👉

Also, thank you for that long and insightful comment @steveklabnik -- it's in the book now!