Skip to content

Commit

Permalink
Define binary and library crates more explicitly
Browse files Browse the repository at this point in the history
Fixes #2820.
  • Loading branch information
carols10cents committed Mar 29, 2022
1 parent db3a9cf commit 1966d0c
Showing 1 changed file with 20 additions and 26 deletions.
46 changes: 20 additions & 26 deletions src/ch07-01-packages-and-crates.md
Original file line number Diff line number Diff line change
@@ -1,12 +1,25 @@
## Packages and Crates

The first parts of the module system we’ll cover are packages and crates. A
crate is a binary or library. The *crate root* is a source file that the Rust
compiler starts from and makes up the root module of your crate (we’ll explain
modules in depth in the [“Defining Modules to Control Scope and
Privacy”][modules]<!-- ignore --> section). A *package* is one or more crates
that provide a set of functionality. A package contains a *Cargo.toml* file
that describes how to build those crates.
The first parts of the module system we’ll cover are packages and crates.

A *package* is one or more crates that provide a set of functionality. A
package contains a *Cargo.toml* file that describes how to build those crates.

A *crate* can be a binary crate or a library crate. *Binary crates* are
programs you can compile to an executable that you can run, such as a
command-line program or a server. They must have a function called `main` that
defines what happens when the executable runs. All the crates we've created so
far have been binary crates.

*Library crates* don't have a `main` function, and they don't compile to an
executable. They define functionality intended to be shared with multiple
projects. For example, the `rand` crate we used in [Chapter 2][rand]<!-- ignore
--> provides functionality that generates random numbers.

The *crate root* is a source file that the Rust compiler starts from and makes
up the root module of your crate (we’ll explain modules in depth in the
[“Defining Modules to Control Scope and Privacy”][modules]<!-- ignore -->
section).

Several rules determine what a package can contain. A package can contain
at most one library crate. It can contain as many binary crates
Expand Down Expand Up @@ -41,24 +54,5 @@ and *src/lib.rs*, it has two crates: a binary and a library, both with the same
name as the package. A package can have multiple binary crates by placing files
in the *src/bin* directory: each file will be a separate binary crate.

A crate will group related functionality together in a scope so the
functionality is easy to share between multiple projects. For example, the
`rand` crate we used in [Chapter 2][rand]<!-- ignore --> provides functionality
that generates random numbers. We can use that functionality in our own
projects by bringing the `rand` crate into our project’s scope. All the
functionality provided by the `rand` crate is accessible through the crate’s
name, `rand`.

Keeping a crate’s functionality in its own scope clarifies whether particular
functionality is defined in our crate or the `rand` crate and prevents
potential conflicts. For example, the `rand` crate provides a trait named
`Rng`. We can also define a `struct` named `Rng` in our own crate. Because a
crate’s functionality is namespaced in its own scope, when we add `rand` as a
dependency, the compiler isn’t confused about what the name `Rng` refers to. In
our crate, it refers to the `struct Rng` that we defined. We would access the
`Rng` trait from the `rand` crate as `rand::Rng`.

Let’s move on and talk about the module system!

[modules]: ch07-02-defining-modules-to-control-scope-and-privacy.html
[rand]: ch02-00-guessing-game-tutorial.html#generating-a-random-number

0 comments on commit 1966d0c

Please sign in to comment.