From 1966d0ca22d3c3c3967aa635dd097bbc93d18ad6 Mon Sep 17 00:00:00 2001 From: "Carol (Nichols || Goulding)" Date: Mon, 28 Mar 2022 20:32:41 -0400 Subject: [PATCH] Define binary and library crates more explicitly Fixes #2820. --- src/ch07-01-packages-and-crates.md | 46 +++++++++++++----------------- 1 file changed, 20 insertions(+), 26 deletions(-) diff --git a/src/ch07-01-packages-and-crates.md b/src/ch07-01-packages-and-crates.md index d4411a06ad..cc5d8cca73 100644 --- a/src/ch07-01-packages-and-crates.md +++ b/src/ch07-01-packages-and-crates.md @@ -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] 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] 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] +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 @@ -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] 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