Introduction

As you write large programs, organizing your code will become increasingly important. By grouping related functionality and separating code with distinct features, you’ll clarify where to find code that implements a particular feature and where to go to change how a feature works.

• A package can contain multiple binary crates and optionally one library crate.
• As a package grows, you can extract parts into separate crates that become external dependencies.

Rust has a number of features that allow you to manage your code’s organization, including which details are exposed, which details are private, and what names are in each scope in your programs. These features, sometimes collectively referred to as the module system, include:

• Packages: A Cargo feature that lets you build, test, and share crates
• Crates: A tree of modules that produces a library or executable
• Modules and use: Let you control the organization, scope, and privacy of paths
• Paths: A way of naming an item, such as a struct, function, or module

Packages and Crates

⇒ A crate is the smallest amount of code that the Rust compiler considers at a time.

• Crates can contain modules, and the modules may be defined in other files that get compiled with the crate
• A crate can come in two forms
  • Binary Crate - Binary crates are programs you can compile to an executable that you can run, such as a command-line program or a server. Each 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 Crate - Library crates don’t have a main function, and they don’t compile into an executable. Instead, they define functionality intended to be shared with multiple projects. For example, the rand crate
• Most of the time when Rustaceans say “crate”, they mean library crate, and they use “crate” interchangeably with the general programming concept of a “library".
• The *crate root* is a source file that the Rust compiler starts from and makes up the root module of your crate.

⇒ A package is a bundle of one or more crates that provides a set of functionalities. A package contains a Cargo.toml file that describes how to build those crates.

• Cargo is actually a package that contains the binary crate for the command-line tool you’ve been using to build your code
• A package can contain as many binary crates as you like, but at most only one library crate. A package must contain at least one crate, whether that’s a library or binary crate.

After we run cargo new, we use ls to see what Cargo creates.

• Cargo follows a convention that src/main.rs is the crate root of a binary crate with the same name as the package
• Likewise, Cargo knows that if the package directory contains src/lib.rs, the package contains a library crate with the same name as the package, and src/lib.rs is its crate root. Cargo passes the crate root files to rustc to build the library or binary.

<aside> 📌 A package can have multiple binary crates by placing files in the *src/bin* directory: each file will be a separate binary crate.

</aside>

Modules

Grouping Related Code in Modules

• Modules let us organize code within a crate for readability and easy reuse.
• Modules also allow us to control the privacy of items, because code within a module is private by default.
• Private items are internal implementation details not available for outside use.

<aside> 📌 Create a new library named restaurant by running cargo new restaurant --lib

</aside>

mod front_of_house {
    mod hosting {
        fn add_to_waitlist() {}

        fn seat_at_table() {}
    }

    mod serving {
        fn take_order() {}

        fn serve_order() {}

        fn take_payment() {}
    }
}

Inside modules, we can place other modules, as in this case with the modules hosting and serving.

Modules can also hold definitions for other items, such as structs, enums, constants, traits, and functions.

we mentioned that src/main.rs and src/lib.rs are called crate roots. The reason for their name is that the contents of either of these two files form a module named crate at the root of the crate’s module structure, known as the module tree.

Listing 7-2 shows the module tree for the structure in Listing 7-1.

crate
 └── front_of_house
     ├── hosting
     │   ├── add_to_waitlist
     │   └── seat_at_table
     └── serving
         ├── take_order
         ├── serve_order
         └── take_payment

Notice that the entire module tree is rooted under the implicit module named crate.

Defining Modules to Control Scope and Privacy

paths that allow you to name items;

the use keyword that brings a path into scope;

and the pub keyword to make items public.

Modules Cheat Sheet

• Start from the crate root: When compiling a crate, the compiler first looks in the crate root file (usually src/lib.rs for a library crate or src/main.rs for a binary crate) for code to compile.

• Declaring modules: In the crate root file, you can declare new modules; say, you declare a “garden” module with mod garden;. The compiler will look for the module’s code in these places:
  • Inline, within curly brackets that replace the semicolon following mod garden
  • In the file src/garden.rs
  • In the file src/garden/mod.rs
• Declaring submodules: In any file other than the crate root, you can declare submodules. For example, you might declare mod vegetables; in src/garden.rs. The compiler will look for the submodule’s code within the directory named for the parent module in these places:
  • Inline, directly following mod vegetables, within curly brackets instead of the semicolon
  • In the file src/garden/vegetables.rs
  • In the file src/garden/vegetables/mod.rs
• Paths to code in modules: Once a module is part of your crate, you can refer to code in that module from anywhere else in that same crate, as long as the privacy rules allow, using the path to the code. For example, an Asparagus type in the garden vegetables module would be found at crate::garden::vegetables::Asparagus.
• Private vs public: Code within a module is private from its parent modules by default. To make a module public, declare it with pub mod instead of mod. To make items within a public module public as well, use pub before their declarations.
• use keyword: Within a scope, the use keyword creates shortcuts to items to reduce the repetition of long paths. In any scope that can refer to crate::garden::vegetables::Asparagus, you can create a shortcut with use crate::garden::vegetables::Asparagus; and from then on you only need to write Asparagus to make use of that type in the scope.

Here we create a binary crate named backyard that illustrates these rules. The crate’s directory, also named backyard, contains these files and directories:

backyard
├── Cargo.lock
├── Cargo.toml
└── src
    ├── garden
    │   └── vegetables.rs
    ├── garden.rs
    └── main.rs

The crate root file in this case is src/main.rs, and it contains:

Filename: src/main.rs

use crate::garden::vegetables::Asparagus;

pub mod garden;

fn main() {
    let plant = Asparagus {};
    println!("I'm growing {:?}!", plant);
}

The pub mod garden; line tells the compiler to include the code it finds in src/garden.rs, which is:

Filename: src/garden.rs

pub mod vegetables;

Here, pub mod vegetables; means the code in src/garden/vegetables.rs is included too. That code is:

#[derive(Debug)]
pub struct Asparagus {}

Paths for Referring to an Item in the Module Tree

⇒ path: To show Rust where to find an item in a module tree.

A path can take two forms:

• An absolute path is the full path starting from a crate root; for code from an external crate, the absolute path begins with the crate name, and for code from the current crate, it starts with the literal crate.
• A relative path starts from the current module and uses self, super, or an identifier in the current module.

separated by double colons (::).