]> git.proxmox.com Git - rustc.git/blame - src/doc/book/nostarch/chapter07.md
New upstream version 1.63.0+dfsg1
[rustc.git] / src / doc / book / nostarch / chapter07.md
CommitLineData
5e7ed085
FG
1<!-- DO NOT EDIT THIS FILE.
2
3This file is periodically generated from the content in the `/src/`
4directory, so all fixes need to be made in `/src/`.
5-->
6
7[TOC]
8
9# Managing Growing Projects with Packages, Crates, and Modules
10
923072b8
FG
11As you write large programs, organizing your code will become increasingly
12important. By grouping related functionality and separating code with distinct
13features, you’ll clarify where to find code that implements a particular
14feature and where to go to change how a feature works.
5e7ed085
FG
15
16The programs we’ve written so far have been in one module in one file. As a
923072b8
FG
17project grows, you should organize code by splitting it into multiple modules
18and then multiple files. A package can contain multiple binary crates and
5e7ed085
FG
19optionally one library crate. As a package grows, you can extract parts into
20separate crates that become external dependencies. This chapter covers all
923072b8
FG
21these techniques. For very large projects comprising a set of interrelated
22packages that evolve together, Cargo provides *workspaces*, which we’ll cover
23in the “Cargo Workspaces” section in Chapter 14.
24
25We’ll also discuss encapsulating implementation details, which lets you reuse
26code at a higher level: once you’ve implemented an operation, other code can
27call your code via its public interface without having to know how the
28implementation works. The way you write code defines which parts are public for
29other code to use and which parts are private implementation details that you
30reserve the right to change. This is another way to limit the amount of detail
31you have to keep in your head.
5e7ed085
FG
32
33A related concept is scope: the nested context in which code is written has a
34set of names that are defined as “in scope.” When reading, writing, and
35compiling code, programmers and compilers need to know whether a particular
36name at a particular spot refers to a variable, function, struct, enum, module,
37constant, or other item and what that item means. You can create scopes and
38change which names are in or out of scope. You can’t have two items with the
39same name in the same scope; tools are available to resolve name conflicts.
40
41Rust has a number of features that allow you to manage your code’s
42organization, including which details are exposed, which details are private,
43and what names are in each scope in your programs. These features, sometimes
44collectively referred to as the *module system*, include:
45
46* **Packages:** A Cargo feature that lets you build, test, and share crates
47* **Crates:** A tree of modules that produces a library or executable
48* **Modules** and **use:** Let you control the organization, scope, and
49 privacy of paths
50* **Paths:** A way of naming an item, such as a struct, function, or module
51
52In this chapter, we’ll cover all these features, discuss how they interact, and
53explain how to use them to manage scope. By the end, you should have a solid
54understanding of the module system and be able to work with scopes like a pro!
55
56## Packages and Crates
57
5e7ed085
FG
58The first parts of the module system we’ll cover are packages and crates.
59
923072b8
FG
60<!-- Do you have a general definition of a crate we can add, or is it too
61dependent on whether it's a binary or library crate? /LC -->
62<!-- I've struggled to come up with something that isn't just "smaller than a
63package but bigger than a module"... "reusable" or "what you specify as a
64dependency" only applies to library crates... this definition I've added here
65gets a little bit into how the compiler sees crates, which might be too much
66detail? What do you think about this next paragraph? /Carol -->
67<!-- JT, what do you think? /LC -->
68<!-- I think this works.
69
70Carol - I'm wondering a bit if "packages" above helps the reader build the
71mental model or if it's kind of an implementation detail for cargo (we could
72say we "package crates"). You're definitely the expert here, but I wonder if we
73can simplify down to Crates/Modules/Paths and mention that we'll introduce some
74of the techniques the tooling uses to work with these later. /JT -->
75<!-- I feel like we need to explain the `[package]` section in *Cargo.toml*,
76and explain what the container is when you have a library and one or more
77binaries in one directory, and that's a package. It is a little weird because
78people hardly ever talk in terms of packages, only in terms of crates, but I
79think it's better to have the discussion of package here. /Carol -->
80
81A *crate* is the smallest amount of code that the Rust compiler considers at a
82time. Even if you run `rustc` rather than `cargo` and pass a single source code
83file (as we did all the way back in the “Writing and Running a Rust Program”
84section of Chapter 1), the compiler considers that file to be a crate. Crates
85can contain modules, and the modules may be defined in other files that get
86compiled with the crate, as we’ll see in the coming sections.
87
88A crate can come in one of two forms: a binary crate or a library crate.
89*Binary crates* are programs you can compile to an executable that you can run,
90such as a command-line program or a server. Each must have a function called
91`main` that defines what happens when the executable runs. All the crates we’ve
92created so far have been binary crates.
5e7ed085
FG
93
94*Library crates* don’t have a `main` function, and they don’t compile to an
923072b8
FG
95executable. Instead, they define functionality intended to be shared with
96multiple projects. For example, the `rand` crate we used in Chapter 2 provides
97functionality that generates random numbers. Most of the time when Rustaceans
98say “crate”, they mean library crate, and they use “crate” interchangeably with
99the general programming concept of a “library".
5e7ed085
FG
100
101The *crate root* is a source file that the Rust compiler starts from and makes
102up the root module of your crate (we’ll explain modules in depth in the
103“Defining Modules to Control Scope and Privacy” section).
104
923072b8
FG
105A *package* is a bundle of one or more crates that provides a set of
106functionality. A package contains a *Cargo.toml* file that describes how to
107build those crates. Cargo is actually a package that contains the binary crate
108for the command-line tool you’ve been using to build your code. The Cargo
109package also contains a library crate that the binary crate depends on. Other
110projects can depend on the Cargo library crate to use the same logic the Cargo
111command-line tool uses.
112
113A package can contain as many binary crates as you like, but at most only one
114library crate. A package must contain at least one crate, whether that’s a
115library or binary crate.
5e7ed085
FG
116
117Let’s walk through what happens when we create a package. First, we enter the
118command `cargo new`:
119
120```
121$ cargo new my-project
122 Created binary (application) `my-project` package
123$ ls my-project
124Cargo.toml
125src
126$ ls my-project/src
127main.rs
128```
129
923072b8
FG
130<!-- I can't remember if we warned folks we were going to use unix commands. May
131want to throw in the Windows command here too, so they feel welcome. /JT -->
132<!-- I don't think JT has seen chapter 1 yet, we address that there /Carol -->
133
134After we run `cargo new`, we use `ls` to see what Cargo creates. In the project
135directory, there’s a *Cargo.toml* file, giving us a package. There’s also a
136*src* directory that contains *main.rs*. Open *Cargo.toml* in your text editor,
137and note there’s no mention of *src/main.rs*. Cargo follows a convention that
138*src/main.rs* is the crate root of a binary crate with the same name as the
139package. Likewise, Cargo knows that if the package directory contains
140*src/lib.rs*, the package contains a library crate with the same name as the
141package, and *src/lib.rs* is its crate root. Cargo passes the crate root files
142to `rustc` to build the library or binary.
5e7ed085
FG
143
144Here, we have a package that only contains *src/main.rs*, meaning it only
145contains a binary crate named `my-project`. If a package contains *src/main.rs*
146and *src/lib.rs*, it has two crates: a binary and a library, both with the same
147name as the package. A package can have multiple binary crates by placing files
148in the *src/bin* directory: each file will be a separate binary crate.
149
150## Defining Modules to Control Scope and Privacy
151
152In this section, we’ll talk about modules and other parts of the module system,
153namely *paths* that allow you to name items; the `use` keyword that brings a
154path into scope; and the `pub` keyword to make items public. We’ll also discuss
155the `as` keyword, external packages, and the glob operator.
156
157First, we’re going to start with a list of rules for easy reference when you’re
158organizing your code in the future. Then we’ll explain each of the rules in
159detail.
160
923072b8 161### Modules Cheat Sheet
5e7ed085 162
923072b8 163<!--WHEN TRANSFERRED TO WORD, DECIDE ON BOX OR NOT -->
5e7ed085 164
923072b8
FG
165Here we provide a quick reference on how modules, paths, the `use` keyword, and
166the `pub` keyword work in the compiler, and how most developers organize their
167code. We’ll be going through examples of each of these rules throughout this
168chapter, but this is a great place to refer to as a reminder of how modules
169work.
5e7ed085
FG
170
171- **Start from the crate root**: When compiling a crate, the compiler first
172 looks in the crate root file (usually *src/lib.rs* for a library crate or
923072b8
FG
173 *src/main.rs* for a binary crate) for code to compile.
174 <!-- I may be asking a silly question here... but what is the compiler looking
175 for in the crate root file? just things to start compiling? /LC -->
176 <!-- That's exactly it-- it's the starting point of compilation, and the
177 compiler will only find files if they're connected to the crate root somehow.
178 Do you think that should be mentioned here? Is there something about this
179 explanation that would make you feel more confident about the concept? /Carol
180 -->
181 <!-- I've added "for things to compile" -- I wanted to make sure the reader
182 knew they weren't missing anything, that there wasn't a particular thing
183 being looked for that the reader wasn't aware of /LC -->
184 <!-- I changed "things" to "code" to be more precise /Carol -->
185- **Declaring modules**: In the crate root file, you can declare new modules;
186say, you declare a “garden” module with `mod garden;`. The compiler will look
187for the module’s code in these places:
188
189 - Inline, within curly brackets that replace the semicolon following `mod
190 garden`
191 <!-- instead of or after the semicolon? Or is all of this instead of a
192 semicolon? /LC -->
193 <!-- Curly brackets and everything within them instead of the semicolon.
194 I'm not sure a pithy way to make that distinction clearer? /Carol -->
195 <!-- JT, would "Inline, within curly brackets that replace the semicolon
196 following `mod garden` be clearer/accurate? /LC -->
197 <!-- I wonder if we should order it where this cheatsheet happens after
198 we show more examples. Most of the time, you'll use the `mod` keyword to
199 pull files in as you refactor out into separate files. Sometimes you'll use
200 it for those key cases, like grouping tests. Showing those examples and then
201 going into the resolution may be a bit easier.
202
203 To your question - I think of this as something that could be more of
204 a warning. If you want to use `mod foo`, then be sure you haven't already
205 declared a module called that in the current file. If you do, the compiler
206 will see it first before it looks for a file with that name. /JT -->
207 <!-- I feel pretty strongly that the cheat sheet needs to go first, so that
208 after a reader's first time through the book, when they go back to the
209 modules chapter to try and figure out why their modules aren't working,
210 they get this first rather than having to read through or skip through the
211 examples when they're already frustrated.
212
213 I also don't feel like the "warning" way of talking about this belongs
214 here. I almost added a section called "common mistakes" or "pitfalls" or
215 "troubleshooting", and I think talking about what you *don't* want to do
216 would belong there...
217
218 Liz, I'm fine with your suggested wording and I've made that change. /Carol
219 -->
220
5e7ed085
FG
221 - In the file *src/garden.rs*
222 - In the file *src/garden/mod.rs*
923072b8
FG
223- **Declaring submodules**: In any file other than the crate root, you can
224 declare submodules. For example, you might declare `mod vegetables;` in
225 *src/garden.rs*. The compiler will look for the submodule’s code within the
226 directory named for the parent module in these places:
5e7ed085
FG
227 - Inline, directly following `mod vegetables`, within curly brackets instead
228 of the semicolon
229 - In the file *src/garden/vegetables.rs*
230 - In the file *src/garden/vegetables/mod.rs*
923072b8
FG
231- **Paths to code in modules**: Once a module is part of your crate, you can
232 refer to code in that module from anywhere else in that same crate, as long
233 as the privacy rules allow, using the path to the code. For example, an
234 `Asparagus` type in the garden vegetables module would be found at
235 `crate::garden::vegetables::Asparagus`.
5e7ed085
FG
236- **Private vs public**: Code within a module is private from its parent
237 modules by default. To make a module public, declare it with `pub mod`
238 instead of `mod`. To make items within a public module public as well, use
239 `pub` before their declarations.
240- **The `use` keyword**: Within a scope, the `use` keyword creates shortcuts to
241 items to reduce repetition of long paths. In any scope that can refer to
242 `crate::garden::vegetables::Asparagus`, you can create a shortcut with `use
923072b8
FG
243 crate::garden::vegetables::Asparagus;` and from then on you only need to
244 write `Asparagus` to make use of that type in the scope.
5e7ed085 245
923072b8 246Here we create a binary crate named `backyard` that illustrates these rules. The
5e7ed085
FG
247crate’s directory, also named `backyard`, contains these files and directories:
248
249```
250backyard
251├── Cargo.lock
252├── Cargo.toml
253└── src
254 ├── garden
255 │   └── vegetables.rs
256 ├── garden.rs
257 └── main.rs
258```
259
923072b8 260The crate root file in this case is *src/main.rs*, and it contains:
5e7ed085
FG
261
262Filename: src/main.rs
263
264```
265use crate::garden::vegetables::Asparagus;
266
267pub mod garden;
268
269fn main() {
270 let plant = Asparagus {};
271 println!("I'm growing {:?}!", plant);
272}
273```
274
923072b8 275The `pub mod garden;` line tells the compiler to include the code it finds in
5e7ed085
FG
276*src/garden.rs*, which is:
277
278Filename: src/garden.rs
279
280```
281pub mod vegetables;
282```
283
923072b8
FG
284Here, `pub mod vegetables;` means the code in *src/garden/vegetables.rs* is
285included too. That code is:
5e7ed085
FG
286
287```
288#[derive(Debug)]
289pub struct Asparagus {}
290```
291
292Now let’s get into the details of these rules and demonstrate them in action!
293
294### Grouping Related Code in Modules
295
923072b8
FG
296*Modules* let us organize code within a crate for readability and easy reuse.
297Modules also allow us to control the *privacy* of items, because code within a
298module is private by default. Private items are internal implementation details
299not available for outside use. We can choose to make modules and the items
300within them public, which exposes them to allow external code to use and depend
301on them.
5e7ed085
FG
302
303As an example, let’s write a library crate that provides the functionality of a
304restaurant. We’ll define the signatures of functions but leave their bodies
923072b8
FG
305empty to concentrate on the organization of the code, rather than the
306implementation of a restaurant.
5e7ed085
FG
307
308In the restaurant industry, some parts of a restaurant are referred to as
309*front of house* and others as *back of house*. Front of house is where
923072b8
FG
310customers are; this encompasses where the hosts seat customers, servers take
311orders and payment, and bartenders make drinks. Back of house is where the
312chefs and cooks work in the kitchen, dishwashers clean up, and managers do
313administrative work.
5e7ed085 314
923072b8
FG
315To structure our crate in this way, we can organize its functions into nested
316modules. Create a new library named `restaurant` by running `cargo new --lib
317restaurant`; then enter the code in Listing 7-1 into *src/lib.rs* to define
318some modules and function signatures. Here’s the front of house section:
5e7ed085
FG
319
320Filename: src/lib.rs
321
322```
323mod front_of_house {
324 mod hosting {
325 fn add_to_waitlist() {}
326
327 fn seat_at_table() {}
328 }
329
330 mod serving {
331 fn take_order() {}
332
333 fn serve_order() {}
334
335 fn take_payment() {}
336 }
337}
338```
339
340Listing 7-1: A `front_of_house` module containing other modules that then
341contain functions
342
923072b8
FG
343We define a module with the `mod` keyword followed by the name of the module
344(in this case, `front_of_house`). The body of the module then goes inside curly
345brackets. Inside modules, we can place other modules, as in this case with the
346modules `hosting` and `serving`. Modules can also hold definitions for other
347items, such as structs, enums, constants, traits, and—as in Listing
3487-1—functions.
5e7ed085
FG
349
350By using modules, we can group related definitions together and name why
923072b8
FG
351they’re related. Programmers using this code can navigate the code based on the
352groups rather than having to read through all the definitions, making it easier
353to find the definitions relevant to them. Programmers adding new functionality
354to this code would know where to place the code to keep the program organized.
5e7ed085
FG
355
356Earlier, we mentioned that *src/main.rs* and *src/lib.rs* are called crate
357roots. The reason for their name is that the contents of either of these two
358files form a module named `crate` at the root of the crate’s module structure,
359known as the *module tree*.
360
361Listing 7-2 shows the module tree for the structure in Listing 7-1.
362
363```
364crate
365 └── front_of_house
366 ├── hosting
367 │ ├── add_to_waitlist
368 │ └── seat_at_table
369 └── serving
370 ├── take_order
371 ├── serve_order
372 └── take_payment
373```
374
375Listing 7-2: The module tree for the code in Listing 7-1
376
923072b8
FG
377This tree shows how some of the modules nest inside one another; for example,
378`hosting` nests inside `front_of_house`. The tree also shows that some modules
379are *siblings* to each other, meaning they’re defined in the same module;
380`hosting` and `serving` are siblings defined within `front_of_house`. If module
381A is contained inside module B, we say that module A is the *child* of module B
382and that module B is the *parent* of module A. Notice that the entire module
383tree is rooted under the implicit module named `crate`.
5e7ed085
FG
384
385The module tree might remind you of the filesystem’s directory tree on your
386computer; this is a very apt comparison! Just like directories in a filesystem,
387you use modules to organize your code. And just like files in a directory, we
388need a way to find our modules.
389
390## Paths for Referring to an Item in the Module Tree
391
392To show Rust where to find an item in a module tree, we use a path in the same
923072b8
FG
393way we use a path when navigating a filesystem. To call a function, we need to
394know its path.
5e7ed085
FG
395
396A path can take two forms:
397
923072b8
FG
398* An *absolute path* is the full path starting from a crate root; for code
399 from an external crate, the absolute path begins with the crate name, and for
400 code from the current crate, it starts with the literal `crate`.
5e7ed085
FG
401* A *relative path* starts from the current module and uses `self`, `super`, or
402 an identifier in the current module.
403
404Both absolute and relative paths are followed by one or more identifiers
405separated by double colons (`::`).
406
923072b8
FG
407Returning to Listing 7-1, say we want to call the `add_to_waitlist` function.
408This is the same as asking: what’s the path of the `add_to_waitlist` function?
409Listing 7-3 contains Listing 7-1 with some of the modules and functions
410removed.
411
412We’ll show two ways to call the `add_to_waitlist` function from a new function
413`eat_at_restaurant` defined in the crate root. These paths are correct, but
414there’s another problem remaining that will prevent this example from compiling
415as-is. We’ll explain why in a bit.
416
417The `eat_at_restaurant` function is part of our library crate’s public API, so
418we mark it with the `pub` keyword. In the “Exposing Paths with the `pub`
419Keyword” section, we’ll go into more detail about `pub`.
5e7ed085
FG
420
421Filename: src/lib.rs
422
423```
424mod front_of_house {
425 mod hosting {
426 fn add_to_waitlist() {}
427 }
428}
429
430pub fn eat_at_restaurant() {
431 // Absolute path
432 crate::front_of_house::hosting::add_to_waitlist();
433
434 // Relative path
435 front_of_house::hosting::add_to_waitlist();
436}
437```
438
923072b8
FG
439<!-- We should probably let the reader know the above is expected to fail a
440little earlier. /JT -->
441<!-- I've rearranged a bit /Carol -->
442
5e7ed085
FG
443Listing 7-3: Calling the `add_to_waitlist` function using absolute and relative
444paths
445
446The first time we call the `add_to_waitlist` function in `eat_at_restaurant`,
447we use an absolute path. The `add_to_waitlist` function is defined in the same
448crate as `eat_at_restaurant`, which means we can use the `crate` keyword to
923072b8
FG
449start an absolute path. We then include each of the successive modules until we
450make our way to `add_to_waitlist`. You can imagine a filesystem with the same
451structure: we’d specify the path `/front_of_house/hosting/add_to_waitlist` to
452run the `add_to_waitlist` program; using the `crate` name to start from the
453crate root is like using `/` to start from the filesystem root in your shell.
5e7ed085
FG
454
455The second time we call `add_to_waitlist` in `eat_at_restaurant`, we use a
456relative path. The path starts with `front_of_house`, the name of the module
457defined at the same level of the module tree as `eat_at_restaurant`. Here the
458filesystem equivalent would be using the path
923072b8
FG
459`front_of_house/hosting/add_to_waitlist`. Starting with a module name means
460that the path is relative.
5e7ed085
FG
461
462Choosing whether to use a relative or absolute path is a decision you’ll make
923072b8
FG
463based on your project, and depends on whether you’re more likely to move item
464definition code separately from or together with the code that uses the item.
465For example, if we move the `front_of_house` module and the `eat_at_restaurant`
466function into a module named `customer_experience`, we’d need to update the
467absolute path to `add_to_waitlist`, but the relative path would still be valid.
468However, if we moved the `eat_at_restaurant` function separately into a module
469named `dining`, the absolute path to the `add_to_waitlist` call would stay the
470same, but the relative path would need to be updated.
471
472Our preference in general is to specify absolute paths because it’s more likely
473we’ll want to move code definitions and item calls independently of each other.
5e7ed085
FG
474
475Let’s try to compile Listing 7-3 and find out why it won’t compile yet! The
476error we get is shown in Listing 7-4.
477
478```
479$ cargo build
480 Compiling restaurant v0.1.0 (file:///projects/restaurant)
481error[E0603]: module `hosting` is private
482 --> src/lib.rs:9:28
483 |
4849 | crate::front_of_house::hosting::add_to_waitlist();
485 | ^^^^^^^ private module
486 |
487note: the module `hosting` is defined here
488 --> src/lib.rs:2:5
489 |
4902 | mod hosting {
491 | ^^^^^^^^^^^
492
493error[E0603]: module `hosting` is private
494 --> src/lib.rs:12:21
495 |
49612 | front_of_house::hosting::add_to_waitlist();
497 | ^^^^^^^ private module
498 |
499note: the module `hosting` is defined here
500 --> src/lib.rs:2:5
501 |
5022 | mod hosting {
503 | ^^^^^^^^^^^
504```
505
506Listing 7-4: Compiler errors from building the code in Listing 7-3
507
508The error messages say that module `hosting` is private. In other words, we
509have the correct paths for the `hosting` module and the `add_to_waitlist`
510function, but Rust won’t let us use them because it doesn’t have access to the
923072b8
FG
511private sections. In Rust, all items (functions, methods, structs, enums,
512modules, and constants) are private to parent modules by default. If you want
513to make an item like a function or struct private, you put it in a module.
514
515Items in a parent module can’t use the private items inside child modules, but
516items in child modules can use the items in their ancestor modules. This is
517because child modules wrap and hide their implementation details, but the child
518modules can see the context in which they’re defined. To continue with our
519metaphor, think of the privacy rules as being like the back office of a
520restaurant: what goes on in there is private to restaurant customers, but
521office managers can see and do everything in the restaurant they operate.
5e7ed085
FG
522
523Rust chose to have the module system function this way so that hiding inner
524implementation details is the default. That way, you know which parts of the
923072b8
FG
525inner code you can change without breaking outer code. However, Rust does give
526you the option to expose inner parts of child modules’ code to outer ancestor
527modules by using the `pub` keyword to make an item public.
5e7ed085
FG
528
529### Exposing Paths with the `pub` Keyword
530
531Let’s return to the error in Listing 7-4 that told us the `hosting` module is
532private. We want the `eat_at_restaurant` function in the parent module to have
533access to the `add_to_waitlist` function in the child module, so we mark the
534`hosting` module with the `pub` keyword, as shown in Listing 7-5.
535
536Filename: src/lib.rs
537
538```
539mod front_of_house {
540 pub mod hosting {
541 fn add_to_waitlist() {}
542 }
543}
544
545pub fn eat_at_restaurant() {
546 // Absolute path
547 crate::front_of_house::hosting::add_to_waitlist();
548
549 // Relative path
550 front_of_house::hosting::add_to_waitlist();
551}
552```
553
554Listing 7-5: Declaring the `hosting` module as `pub` to use it from
555`eat_at_restaurant`
556
557Unfortunately, the code in Listing 7-5 still results in an error, as shown in
558Listing 7-6.
559
560```
561$ cargo build
562 Compiling restaurant v0.1.0 (file:///projects/restaurant)
563error[E0603]: function `add_to_waitlist` is private
564 --> src/lib.rs:9:37
565 |
5669 | crate::front_of_house::hosting::add_to_waitlist();
567 | ^^^^^^^^^^^^^^^ private function
568 |
569note: the function `add_to_waitlist` is defined here
570 --> src/lib.rs:3:9
571 |
5723 | fn add_to_waitlist() {}
573 | ^^^^^^^^^^^^^^^^^^^^
574
575error[E0603]: function `add_to_waitlist` is private
576 --> src/lib.rs:12:30
577 |
57812 | front_of_house::hosting::add_to_waitlist();
579 | ^^^^^^^^^^^^^^^ private function
580 |
581note: the function `add_to_waitlist` is defined here
582 --> src/lib.rs:3:9
583 |
5843 | fn add_to_waitlist() {}
585 | ^^^^^^^^^^^^^^^^^^^^
586```
587
588Listing 7-6: Compiler errors from building the code in Listing 7-5
589
590What happened? Adding the `pub` keyword in front of `mod hosting` makes the
591module public. With this change, if we can access `front_of_house`, we can
592access `hosting`. But the *contents* of `hosting` are still private; making the
593module public doesn’t make its contents public. The `pub` keyword on a module
923072b8
FG
594only lets code in its ancestor modules refer to it, not access its inner code.
595Because modules are containers, there’s not much we can do by only making the
596module public; we need to go further and choose to make one or more of the
597items within the module public as well.
5e7ed085
FG
598
599The errors in Listing 7-6 say that the `add_to_waitlist` function is private.
600The privacy rules apply to structs, enums, functions, and methods as well as
601modules.
602
603Let’s also make the `add_to_waitlist` function public by adding the `pub`
604keyword before its definition, as in Listing 7-7.
605
606Filename: src/lib.rs
607
608```
609mod front_of_house {
610 pub mod hosting {
611 pub fn add_to_waitlist() {}
612 }
613}
614
615pub fn eat_at_restaurant() {
616 // Absolute path
617 crate::front_of_house::hosting::add_to_waitlist();
618
619 // Relative path
620 front_of_house::hosting::add_to_waitlist();
621}
622```
623
624Listing 7-7: Adding the `pub` keyword to `mod hosting` and `fn add_to_waitlist`
625lets us call the function from `eat_at_restaurant`
626
923072b8
FG
627Now the code will compile! To see why adding the `pub` keyword lets us use
628these paths in `add_to_waitlist` with respect to the privacy rules, let’s look
629at the absolute and the relative paths.
5e7ed085
FG
630
631In the absolute path, we start with `crate`, the root of our crate’s module
923072b8
FG
632tree. The `front_of_house` module is defined in the crate root. While
633`front_of_house` isn’t public, because the `eat_at_restaurant` function is
634defined in the same module as `front_of_house` (that is, `eat_at_restaurant`
635and `front_of_house` are siblings), we can refer to `front_of_house` from
636`eat_at_restaurant`. Next is the `hosting` module marked with `pub`. We can
637access the parent module of `hosting`, so we can access `hosting`. Finally, the
638`add_to_waitlist` function is marked with `pub` and we can access its parent
639module, so this function call works!
5e7ed085
FG
640
641In the relative path, the logic is the same as the absolute path except for the
642first step: rather than starting from the crate root, the path starts from
643`front_of_house`. The `front_of_house` module is defined within the same module
644as `eat_at_restaurant`, so the relative path starting from the module in which
645`eat_at_restaurant` is defined works. Then, because `hosting` and
646`add_to_waitlist` are marked with `pub`, the rest of the path works, and this
647function call is valid!
648
649If you plan on sharing your library crate so other projects can use your code,
923072b8
FG
650your public API is your contract with users of your crate that determines how
651they can interact with your code. There are many considerations around managing
652changes to your public API to make it easier for people to depend on your
653crate. These considerations are out of the scope of this book; if you’re
654interested in this topic, see The Rust API Guidelines at
5e7ed085
FG
655*https://rust-lang.github.io/api-guidelines/*.
656
5e7ed085
FG
657
658> #### Best Practices for Packages with a Binary and a Library
659>
660> We mentioned a package can contain both a *src/main.rs* binary crate root as
661> well as a *src/lib.rs* library crate root, and both crates will have the
923072b8
FG
662> package name by default. Typically, packages with this pattern of containing
663> both a library and a binary crate will have just
5e7ed085
FG
664> enough code in the binary crate to start an executable that calls code with
665> the library crate. This lets other projects benefit from the most
666> functionality that the package provides, because the library crate’s code can
667> be shared.
668>
669> The module tree should be defined in *src/lib.rs*. Then, any public items can
670> be used in the binary crate by starting paths with the name of the package.
671> The binary crate becomes a user of the library crate just like a completely
672> external crate would use the library crate: it can only use the public API.
673> This helps you design a good API; not only are you the author, you’re also a
674> client!
675>
676> In Chapter 12, we’ll demonstrate this organizational practice with a
677> command-line program that will contain both a binary crate and a library
678> crate.
679
680### Starting Relative Paths with `super`
681
923072b8
FG
682We can construct relative paths that begin in the parent module, rather than
683the current module or the crate root, by using `super` at the start of the
684path. This is like starting a filesystem path with the `..` syntax. Using
685`super` allows us to reference an item that we know is in the parent module,
686which can make rearranging the module tree easier when the module is closely
687related to the parent, but the parent might be moved elsewhere in the module
688tree someday.
5e7ed085
FG
689
690Consider the code in Listing 7-8 that models the situation in which a chef
691fixes an incorrect order and personally brings it out to the customer. The
692function `fix_incorrect_order` defined in the `back_of_house` module calls the
693function `deliver_order` defined in the parent module by specifying the path to
694`deliver_order` starting with `super`:
695
696Filename: src/lib.rs
697
698```
699fn deliver_order() {}
700
701mod back_of_house {
702 fn fix_incorrect_order() {
703 cook_order();
704 super::deliver_order();
705 }
706
707 fn cook_order() {}
708}
709```
710
711Listing 7-8: Calling a function using a relative path starting with `super`
712
713The `fix_incorrect_order` function is in the `back_of_house` module, so we can
714use `super` to go to the parent module of `back_of_house`, which in this case
715is `crate`, the root. From there, we look for `deliver_order` and find it.
716Success! We think the `back_of_house` module and the `deliver_order` function
717are likely to stay in the same relationship to each other and get moved
718together should we decide to reorganize the crate’s module tree. Therefore, we
719used `super` so we’ll have fewer places to update code in the future if this
720code gets moved to a different module.
721
722### Making Structs and Enums Public
723
724We can also use `pub` to designate structs and enums as public, but there are a
923072b8
FG
725few details extra to the usage of `pub` with structs and enums. If we use `pub`
726before a struct definition, we make the struct public, but the struct’s fields
727will still be private. We can make each field public or not on a case-by-case
728basis. In Listing 7-9, we’ve defined a public `back_of_house::Breakfast` struct
729with a public `toast` field but a private `seasonal_fruit` field. This models
730the case in a restaurant where the customer can pick the type of bread that
731comes with a meal, but the chef decides which fruit accompanies the meal based
732on what’s in season and in stock. The available fruit changes quickly, so
733customers can’t choose the fruit or even see which fruit they’ll get.
5e7ed085
FG
734
735Filename: src/lib.rs
736
737```
738mod back_of_house {
739 pub struct Breakfast {
740 pub toast: String,
741 seasonal_fruit: String,
742 }
743
744 impl Breakfast {
745 pub fn summer(toast: &str) -> Breakfast {
746 Breakfast {
747 toast: String::from(toast),
748 seasonal_fruit: String::from("peaches"),
749 }
750 }
751 }
752}
753
754pub fn eat_at_restaurant() {
755 // Order a breakfast in the summer with Rye toast
756 let mut meal = back_of_house::Breakfast::summer("Rye");
757 // Change our mind about what bread we'd like
758 meal.toast = String::from("Wheat");
759 println!("I'd like {} toast please", meal.toast);
760
761 // The next line won't compile if we uncomment it; we're not allowed
762 // to see or modify the seasonal fruit that comes with the meal
763 // meal.seasonal_fruit = String::from("blueberries");
764}
765```
766
767Listing 7-9: A struct with some public fields and some private fields
768
769Because the `toast` field in the `back_of_house::Breakfast` struct is public,
770in `eat_at_restaurant` we can write and read to the `toast` field using dot
771notation. Notice that we can’t use the `seasonal_fruit` field in
772`eat_at_restaurant` because `seasonal_fruit` is private. Try uncommenting the
773line modifying the `seasonal_fruit` field value to see what error you get!
774
775Also, note that because `back_of_house::Breakfast` has a private field, the
776struct needs to provide a public associated function that constructs an
777instance of `Breakfast` (we’ve named it `summer` here). If `Breakfast` didn’t
778have such a function, we couldn’t create an instance of `Breakfast` in
779`eat_at_restaurant` because we couldn’t set the value of the private
780`seasonal_fruit` field in `eat_at_restaurant`.
781
782In contrast, if we make an enum public, all of its variants are then public. We
783only need the `pub` before the `enum` keyword, as shown in Listing 7-10.
784
785Filename: src/lib.rs
786
787```
788mod back_of_house {
789 pub enum Appetizer {
790 Soup,
791 Salad,
792 }
793}
794
795pub fn eat_at_restaurant() {
796 let order1 = back_of_house::Appetizer::Soup;
797 let order2 = back_of_house::Appetizer::Salad;
798}
799```
800
801Listing 7-10: Designating an enum as public makes all its variants public
802
803Because we made the `Appetizer` enum public, we can use the `Soup` and `Salad`
923072b8
FG
804variants in `eat_at_restaurant`.
805
806Enums aren’t very useful unless their variants are public; it would be annoying
807to have to annotate all enum variants with `pub` in every case, so the default
808for enum variants is to be public. Structs are often useful without their
809fields being public, so struct fields follow the general rule of everything
810being private by default unless annotated with `pub`.
5e7ed085
FG
811
812There’s one more situation involving `pub` that we haven’t covered, and that is
813our last module system feature: the `use` keyword. We’ll cover `use` by itself
814first, and then we’ll show how to combine `pub` and `use`.
815
816## Bringing Paths into Scope with the `use` Keyword
817
923072b8
FG
818Having to write out the paths to call functions can feel inconvenient and
819repetitive. In Listing 7-7, whether we chose the absolute or relative path to
820the `add_to_waitlist` function, every time we wanted to call `add_to_waitlist`
821we had to specify `front_of_house` and `hosting` too. Fortunately, there’s a
822way to simplify this process: we can create a shortcut to a path with the `use`
823keyword once, and then use the shorter name everywhere else in the scope.
5e7ed085
FG
824
825In Listing 7-11, we bring the `crate::front_of_house::hosting` module into the
826scope of the `eat_at_restaurant` function so we only have to specify
827`hosting::add_to_waitlist` to call the `add_to_waitlist` function in
828`eat_at_restaurant`.
829
830Filename: src/lib.rs
831
832```
833mod front_of_house {
834 pub mod hosting {
835 pub fn add_to_waitlist() {}
836 }
837}
838
839use crate::front_of_house::hosting;
840
841pub fn eat_at_restaurant() {
842 hosting::add_to_waitlist();
843}
844```
845
846Listing 7-11: Bringing a module into scope with `use`
847
848Adding `use` and a path in a scope is similar to creating a symbolic link in
849the filesystem. By adding `use crate::front_of_house::hosting` in the crate
850root, `hosting` is now a valid name in that scope, just as though the `hosting`
851module had been defined in the crate root. Paths brought into scope with `use`
852also check privacy, like any other paths.
853
5e7ed085
FG
854Note that `use` only creates the shortcut for the particular scope in which the
855`use` occurs. Listing 7-12 moves the `eat_at_restaurant` function into a new
856child module named `customer`, which is then a different scope than the `use`
923072b8 857statement, so the function body won’t compile:
5e7ed085
FG
858
859Filename: src/lib.rs
860
861```
862mod front_of_house {
863 pub mod hosting {
864 pub fn add_to_waitlist() {}
865 }
866}
867
868use crate::front_of_house::hosting;
869
870mod customer {
871 pub fn eat_at_restaurant() {
872 hosting::add_to_waitlist();
873 }
874}
875```
876
877Listing 7-12: A `use` statement only applies in the scope it’s in
878
879The compiler error shows that the shortcut no longer applies within the
880`customer` module:
881
882```
883error[E0433]: failed to resolve: use of undeclared crate or module `hosting`
884 --> src/lib.rs:11:9
885 |
88611 | hosting::add_to_waitlist();
887 | ^^^^^^^ use of undeclared crate or module `hosting`
888
889warning: unused import: `crate::front_of_house::hosting`
890 --> src/lib.rs:7:5
891 |
8927 | use crate::front_of_house::hosting;
893 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
894 |
895 = note: `#[warn(unused_imports)]` on by default
896```
897
898Notice there’s also a warning that the `use` is no longer used in its scope! To
899fix this problem, move the `use` within the `customer` module too, or reference
900the shortcut in the parent module with `super::hosting` within the child
901`customer` module.
902
903### Creating Idiomatic `use` Paths
904
905In Listing 7-11, you might have wondered why we specified `use
906crate::front_of_house::hosting` and then called `hosting::add_to_waitlist` in
907`eat_at_restaurant` rather than specifying the `use` path all the way out to
908the `add_to_waitlist` function to achieve the same result, as in Listing 7-13.
909
910Filename: src/lib.rs
911
912```
913mod front_of_house {
914 pub mod hosting {
915 pub fn add_to_waitlist() {}
916 }
917}
918
919use crate::front_of_house::hosting::add_to_waitlist;
920
921pub fn eat_at_restaurant() {
922 add_to_waitlist();
923}
924```
925
926Listing 7-13: Bringing the `add_to_waitlist` function into scope with `use`,
927which is unidiomatic
928
929Although both Listing 7-11 and 7-13 accomplish the same task, Listing 7-11 is
930the idiomatic way to bring a function into scope with `use`. Bringing the
931function’s parent module into scope with `use` means we have to specify the
932parent module when calling the function. Specifying the parent module when
933calling the function makes it clear that the function isn’t locally defined
934while still minimizing repetition of the full path. The code in Listing 7-13 is
935unclear as to where `add_to_waitlist` is defined.
936
937On the other hand, when bringing in structs, enums, and other items with `use`,
938it’s idiomatic to specify the full path. Listing 7-14 shows the idiomatic way
939to bring the standard library’s `HashMap` struct into the scope of a binary
940crate.
941
942Filename: src/main.rs
943
944```
945use std::collections::HashMap;
946
947fn main() {
948 let mut map = HashMap::new();
949 map.insert(1, 2);
950}
951```
952
953Listing 7-14: Bringing `HashMap` into scope in an idiomatic way
954
955There’s no strong reason behind this idiom: it’s just the convention that has
956emerged, and folks have gotten used to reading and writing Rust code this way.
957
958The exception to this idiom is if we’re bringing two items with the same name
959into scope with `use` statements, because Rust doesn’t allow that. Listing 7-15
960shows how to bring two `Result` types into scope that have the same name but
961different parent modules and how to refer to them.
962
963Filename: src/lib.rs
964
965```
966use std::fmt;
967use std::io;
968
969fn function1() -> fmt::Result {
970 // --snip--
971}
972
973fn function2() -> io::Result<()> {
974 // --snip--
975}
976```
977
978Listing 7-15: Bringing two types with the same name into the same scope
979requires using their parent modules.
980
981As you can see, using the parent modules distinguishes the two `Result` types.
982If instead we specified `use std::fmt::Result` and `use std::io::Result`, we’d
983have two `Result` types in the same scope and Rust wouldn’t know which one we
984meant when we used `Result`.
985
986### Providing New Names with the `as` Keyword
987
988There’s another solution to the problem of bringing two types of the same name
989into the same scope with `use`: after the path, we can specify `as` and a new
923072b8
FG
990local name, or *alias*, for the type. Listing 7-16 shows another way to write
991the code in Listing 7-15 by renaming one of the two `Result` types using `as`.
5e7ed085
FG
992
993Filename: src/lib.rs
994
995```
996use std::fmt::Result;
997use std::io::Result as IoResult;
998
999fn function1() -> Result {
1000 // --snip--
1001}
1002
1003fn function2() -> IoResult<()> {
1004 // --snip--
1005}
1006```
1007
1008Listing 7-16: Renaming a type when it’s brought into scope with the `as` keyword
1009
1010In the second `use` statement, we chose the new name `IoResult` for the
1011`std::io::Result` type, which won’t conflict with the `Result` from `std::fmt`
1012that we’ve also brought into scope. Listing 7-15 and Listing 7-16 are
1013considered idiomatic, so the choice is up to you!
1014
1015### Re-exporting Names with `pub use`
1016
1017When we bring a name into scope with the `use` keyword, the name available in
1018the new scope is private. To enable the code that calls our code to refer to
1019that name as if it had been defined in that code’s scope, we can combine `pub`
1020and `use`. This technique is called *re-exporting* because we’re bringing
1021an item into scope but also making that item available for others to bring into
1022their scope.
1023
1024Listing 7-17 shows the code in Listing 7-11 with `use` in the root module
1025changed to `pub use`.
1026
1027Filename: src/lib.rs
1028
1029```
1030mod front_of_house {
1031 pub mod hosting {
1032 pub fn add_to_waitlist() {}
1033 }
1034}
1035
1036pub use crate::front_of_house::hosting;
1037
1038pub fn eat_at_restaurant() {
1039 hosting::add_to_waitlist();
1040}
1041```
1042
1043Listing 7-17: Making a name available for any code to use from a new scope with
1044`pub use`
1045
1046Before this change, external code would have to call the `add_to_waitlist`
1047function by using the path
1048`restaurant::front_of_house::hosting::add_to_waitlist()`. Now that this `pub
1049use` has re-exported the `hosting` module from the root module, external code
1050can now use the path `restaurant::hosting::add_to_waitlist()` instead.
1051
1052Re-exporting is useful when the internal structure of your code is different
1053from how programmers calling your code would think about the domain. For
1054example, in this restaurant metaphor, the people running the restaurant think
1055about “front of house” and “back of house.” But customers visiting a restaurant
1056probably won’t think about the parts of the restaurant in those terms. With
1057`pub use`, we can write our code with one structure but expose a different
1058structure. Doing so makes our library well organized for programmers working on
1059the library and programmers calling the library. We’ll look at another example
1060of `pub use` and how it affects your crate’s documentation in the “Exporting a
1061Convenient Public API with `pub use`” section of Chapter 14.
1062
1063### Using External Packages
1064
1065In Chapter 2, we programmed a guessing game project that used an external
1066package called `rand` to get random numbers. To use `rand` in our project, we
1067added this line to *Cargo.toml*:
1068
1069Filename: Cargo.toml
1070
1071```
1072rand = "0.8.3"
1073```
1074
1075Adding `rand` as a dependency in *Cargo.toml* tells Cargo to download the
1076`rand` package and any dependencies from *https://crates.io/* and make `rand`
1077available to our project.
1078
1079Then, to bring `rand` definitions into the scope of our package, we added a
1080`use` line starting with the name of the crate, `rand`, and listed the items we
1081wanted to bring into scope. Recall that in the “Generating a Random Number”
1082section in Chapter 2, we brought the `Rng` trait into scope and called the
1083`rand::thread_rng` function:
1084
1085```
1086use rand::Rng;
1087
1088fn main() {
1089 let secret_number = rand::thread_rng().gen_range(1..101);
1090}
1091```
1092
1093Members of the Rust community have made many packages available at
1094*https://crates.io/*, and pulling any of them into your package involves these
1095same steps: listing them in your package’s *Cargo.toml* file and using `use` to
1096bring items from their crates into scope.
1097
923072b8 1098Note that the standard `std` library is also a crate that’s external to our
5e7ed085
FG
1099package. Because the standard library is shipped with the Rust language, we
1100don’t need to change *Cargo.toml* to include `std`. But we do need to refer to
1101it with `use` to bring items from there into our package’s scope. For example,
1102with `HashMap` we would use this line:
1103
1104```
1105use std::collections::HashMap;
1106```
1107
1108This is an absolute path starting with `std`, the name of the standard library
1109crate.
1110
1111### Using Nested Paths to Clean Up Large `use` Lists
1112
1113If we’re using multiple items defined in the same crate or same module,
1114listing each item on its own line can take up a lot of vertical space in our
1115files. For example, these two `use` statements we had in the Guessing Game in
1116Listing 2-4 bring items from `std` into scope:
1117
1118Filename: src/main.rs
1119
1120```
1121// --snip--
1122use std::cmp::Ordering;
1123use std::io;
1124// --snip--
1125```
1126
1127Instead, we can use nested paths to bring the same items into scope in one
1128line. We do this by specifying the common part of the path, followed by two
1129colons, and then curly brackets around a list of the parts of the paths that
1130differ, as shown in Listing 7-18.
1131
1132Filename: src/main.rs
1133
1134```
1135// --snip--
1136use std::{cmp::Ordering, io};
1137// --snip--
1138```
1139
1140Listing 7-18: Specifying a nested path to bring multiple items with the same
1141prefix into scope
1142
1143In bigger programs, bringing many items into scope from the same crate or
1144module using nested paths can reduce the number of separate `use` statements
1145needed by a lot!
1146
1147We can use a nested path at any level in a path, which is useful when combining
1148two `use` statements that share a subpath. For example, Listing 7-19 shows two
1149`use` statements: one that brings `std::io` into scope and one that brings
1150`std::io::Write` into scope.
1151
1152Filename: src/lib.rs
1153
1154```
1155use std::io;
1156use std::io::Write;
1157```
1158
1159Listing 7-19: Two `use` statements where one is a subpath of the other
1160
1161The common part of these two paths is `std::io`, and that’s the complete first
1162path. To merge these two paths into one `use` statement, we can use `self` in
1163the nested path, as shown in Listing 7-20.
1164
1165Filename: src/lib.rs
1166
1167```
1168use std::io::{self, Write};
1169```
1170
1171Listing 7-20: Combining the paths in Listing 7-19 into one `use` statement
1172
1173This line brings `std::io` and `std::io::Write` into scope.
1174
1175### The Glob Operator
1176
1177If we want to bring *all* public items defined in a path into scope, we can
923072b8 1178specify that path followed by the `*` glob operator:
5e7ed085
FG
1179
1180```
1181use std::collections::*;
1182```
1183
1184This `use` statement brings all public items defined in `std::collections` into
1185the current scope. Be careful when using the glob operator! Glob can make it
1186harder to tell what names are in scope and where a name used in your program
1187was defined.
1188
1189The glob operator is often used when testing to bring everything under test
1190into the `tests` module; we’ll talk about that in the “How to Write Tests”
1191section in Chapter 11. The glob operator is also sometimes used as part of the
1192prelude pattern: see the standard library documentation for more information on
1193that pattern.
1194
1195## Separating Modules into Different Files
1196
1197So far, all the examples in this chapter defined multiple modules in one file.
1198When modules get large, you might want to move their definitions to a separate
1199file to make the code easier to navigate.
1200
923072b8
FG
1201For example, let’s start from the code in Listing 7-17 that had multiple
1202restaurant modules. We’ll extract modules into files instead of having all the
1203modules defined in the crate root file. In this case, the crate root file is
1204*src/lib.rs*, but this procedure also works with binary crates whose crate root
1205file is *src/main.rs*.
5e7ed085
FG
1206
1207First, we’ll extract the `front_of_house` module to its own file. Remove the
1208code inside the curly brackets for the `front_of_house` module, leaving only
1209the `mod front_of_house;` declaration, so that *src/lib.rs* contains the code
1210shown in Listing 7-21. Note that this won’t compile until we create the
1211*src/front_of_house.rs* file in Listing 7-22.
1212
1213Filename: src/lib.rs
1214
1215```
1216mod front_of_house;
1217
1218pub use crate::front_of_house::hosting;
1219
1220pub fn eat_at_restaurant() {
1221 hosting::add_to_waitlist();
1222}
1223```
1224
1225Listing 7-21: Declaring the `front_of_house` module whose body will be in
1226*src/front_of_house.rs*
1227
1228Next, place the code that was in the curly brackets into a new file named
1229*src/front_of_house.rs*, as shown in Listing 7-22. The compiler knows to look
923072b8
FG
1230in this file because it came across the module declaration in the crate root
1231with the name `front_of_house`.
5e7ed085
FG
1232
1233Filename: src/front_of_house.rs
1234
1235```
1236pub mod hosting {
1237 pub fn add_to_waitlist() {}
1238}
1239```
1240
1241Listing 7-22: Definitions inside the `front_of_house` module in
1242*src/front_of_house.rs*
1243
923072b8
FG
1244Note that you only need to load a file using a `mod` declaration *once* in your
1245module tree. Once the compiler knows the file is part of the project (and knows
1246where in the module tree the code resides because of where you’ve put the `mod`
1247statement), other files in your project should refer to the loaded file’s code
1248using a path to where it was declared, as covered in the “Paths for Referring
1249to an Item in the Module Tree” section. In other words, `mod` is *not* an
1250“include” operation that you may have seen in other programming languages.
1251
1252Next, we’ll extract the `hosting` module to its own file. The process
5e7ed085 1253is a bit different because `hosting` is a child module of `front_of_house`, not
923072b8
FG
1254of the root module. We’ll place the file for `hosting` in a new directory that
1255will be named for its ancestors in the module tree, in this case
1256*src/front_of_house/*.
5e7ed085
FG
1257
1258To start moving `hosting`, we change *src/front_of_house.rs* to contain only the
1259declaration of the `hosting` module:
1260
1261Filename: src/front_of_house.rs
1262
1263```
1264pub mod hosting;
1265```
1266
923072b8
FG
1267Then we create a *src/front_of_house* directory and a file *hosting.rs* to
1268contain the definitions made in the `hosting` module:
5e7ed085
FG
1269
1270Filename: src/front_of_house/hosting.rs
1271
1272```
1273pub fn add_to_waitlist() {}
1274```
1275
1276If we instead put *hosting.rs* in the *src* directory, the compiler would
923072b8
FG
1277expect the *hosting.rs* code to be in a `hosting` module declared in the crate
1278root, and not delcared as a child of the `front_of_house` module. The
1279compiler’s rules for which files to check for which modules’ code means the
1280directories and files more closely match the module tree.
5e7ed085 1281
5e7ed085
FG
1282
1283> ### Alternate File Paths
1284>
923072b8
FG
1285> So far we’ve covered the most idiomatic file paths the Rust compiler uses,
1286> but Rust also supports an older style of file path. For a module named
1287> `front_of_house` declared in the crate root, the compiler will look for the
1288> module’s code in:
5e7ed085
FG
1289>
1290> * *src/front_of_house.rs* (what we covered)
923072b8 1291> * *src/front_of_house/mod.rs* (older style, still supported path)
5e7ed085
FG
1292>
1293> For a module named `hosting` that is a submodule of `front_of_house`, the
1294> compiler will look for the module’s code in:
1295>
1296> * *src/front_of_house/hosting.rs* (what we covered)
923072b8 1297> * *src/front_of_house/hosting/mod.rs* (older style, still supported path)
5e7ed085 1298>
923072b8
FG
1299> If you use both styles for the same module, you’ll get a compiler error. Using
1300> a mix of both styles for different modules in the same project is allowed, but
5e7ed085
FG
1301> might be confusing for people navigating your project.
1302>
1303> The main downside to the style that uses files named *mod.rs* is that your
1304> project can end up with many files named *mod.rs*, which can get confusing
1305> when you have them open in your editor at the same time.
1306
923072b8
FG
1307We’ve moved each module’s code to a separate file, and the module tree remains
1308the same. The function calls in `eat_at_restaurant` will work without any
1309modification, even though the definitions live in different files. This
1310technique lets you move modules to new files as they grow in size.
5e7ed085
FG
1311
1312Note that the `pub use crate::front_of_house::hosting` statement in
1313*src/lib.rs* also hasn’t changed, nor does `use` have any impact on what files
1314are compiled as part of the crate. The `mod` keyword declares modules, and Rust
1315looks in a file with the same name as the module for the code that goes into
1316that module.
1317
1318## Summary
1319
1320Rust lets you split a package into multiple crates and a crate into modules
1321so you can refer to items defined in one module from another module. You can do
1322this by specifying absolute or relative paths. These paths can be brought into
1323scope with a `use` statement so you can use a shorter path for multiple uses of
1324the item in that scope. Module code is private by default, but you can make
1325definitions public by adding the `pub` keyword.
1326
1327In the next chapter, we’ll look at some collection data structures in the
1328standard library that you can use in your neatly organized code.