Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

First draft of crates and modules chapter #110

Closed
wants to merge 3 commits into from
+479 −1
Closed

First draft of crates and modules chapter #110

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
c898990
writer's block
steveklabnik May 20, 2016
e88f12a
Add first draft of crates and modules chapter
steveklabnik Jun 3, 2016
8c48ff5
fix some nits
steveklabnik Jun 7, 2016
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
Next
writer's block
  • Loading branch information
@steveklabnik
steveklabnik committed May 20, 2016
commit c898990fe4a416fceef7d0163ac0d5278fda24e3
2 src/SUMMARY.md
View file
Open in desktop
@@ -32,7 +32,7 @@
- [Option]()
- [if let]()

- [Crates & Modules]()
- [Packages, Crates, & Modules](packages-crates-and-modules.md)

- [Error Handling]()

53 src/packages-crates-and-modules.md
View file
Open in desktop
@@ -0,0 +1,53 @@
# Packages, Crates, & Modules

Now that we've got a better understanding of some of the fundamentals, let's
change gears a bit. Let's talk about the structure of larger Rust programs
and libraries. This will also help you understand the standard library and
its organization, as it is itself a large Rust library!

Rust's system works a bit differently than other languages' that you may have
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The apostrophe in languages' can probably be removed. Alternatively you could say Rust's system works a bit differently than package management of other languages that you may have used in the past.

used in the past. It's worth reading this section carefully; sometimes new
Rustaceans have incorrect expectations based on previous experience.

## Some terminology

First, let's talk about some vocabulary:

* **Crates** are Rust's 'unit of compilation': a library or binary
* **Packages** are a collection of crates
* **Modules** allow you to create namespaces within a crate
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

"namespace" is another piece of terminology that's not well-defined here. Is there a way to explain "module" without reference to "namespace". Presumably most people already have a fuzzy notion of it that should work well enough?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm sympathetic, but unsure how to word it. I would argue the fuzzy understanding might be why people have so much trouble here; they assume that Rust's system works just like whatever random language they're coming from.

Hm.


Everything forms a tree-like hierarchy: a package contains one or more crates,
and crates contain one or more modules.

Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more. 

- Everything forms a tree-like hierarchy: a package contains one or more crates,
- and crates contain one or more modules.
+ A package contains one or more crates, and crates contain one or more modules.

We'll start in the middle, though, as in some sense, crates are what's
fundamental here. We can't talk about a collection of crates without knowing
what a crate is! Let's talk about crates.

## Crates

A 'crate' is Rust's name for a library or binary. We mean 'binary' in the sense
of 'executable program' here: both libraries and binaries are compiled into
machine code.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'd just say "a crate is Rust's name for a package (like a "gem" in Ruby or a "jar" in Java)" or something to that effect.

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't that more of "package"? Ruby gems can hold one or more binaries, and zero or one libraries, like a Rust package.


We've already made a number of crates as we've worked through the book! Each of
the examples we've made is a crate. The simplest crates have only one file: our
`lib.rs` or `main.rs`, depending on if we're making a library or an executable.

In the bullet-point above, we defined a crate as a 'unit of compilation'. In
other words, Rust compiles each crate as a whole. You won't get parallel
compiles of a single crate. But, if your crate has dependencies, Cargo will
compile all of those dependencies in parallel, as they're separate crates.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What are we trying to explain here?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Historically "unit of compilation" is the term we've used to explain "crate". So I'm trying to explain what that means. Maybe it can be done better somehow?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this is a distraction. Saying that it's a "library or binary" is good enough at this point IMO.


There's one more term related to crates: 'the crate root'. We'll talk about
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

If we're not gonna define it here, let's skip mentioning it.

that more in the 'modules' section below.

Let's make this a bit more concrete. Let's make a simple crate, and then, over
the rest of this section, explore the package, crate, and module system by
changing it. More specifically, let's make a crate that

## Packages

## Modules