src/doc/book/src/ch07-05-separating-modules-into-different-files.md

   1 ## Separating Modules into Different Files
   2
   3 So far, all the examples in this chapter defined multiple modules in one file.
   4 When modules get large, you might want to move their definitions to a separate
   5 file to make the code easier to navigate.
   6
   7 For example, let’s start from the code in Listing 7-17 and extract modules into
   8 files instead of having all the modules defined in the crate root file. In this
   9 case, the crate root file is *src/lib.rs*, but this procedure also works with
  10 binary crates whose crate root file is *src/main.rs*.
  11
  12 First, we’ll extract the `front_of_house` module to its own file. Remove the
  13 code inside the curly brackets for the `front_of_house` module, leaving only
  14 the `mod front_of_house;` declaration, so that *src/lib.rs* contains the code
  15 shown in Listing 7-21. Note that this won’t compile until we create the
  16 *src/front_of_house.rs* file in Listing 7-22.
  17
  18 <span class="filename">Filename: src/lib.rs</span>
  19
  20 ```rust,ignore,does_not_compile
  21 {{#rustdoc_include ../listings/ch07-managing-growing-projects/listing-07-21-and-22/src/lib.rs}}
  22 ```
  23
  24 <span class="caption">Listing 7-21: Declaring the `front_of_house` module whose
  25 body will be in *src/front_of_house.rs*</span>
  26
  27 Next, place the code that was in the curly brackets into a new file named
  28 *src/front_of_house.rs*, as shown in Listing 7-22. The compiler knows to look
  29 in this file because of the module declaration it found in the crate root with
  30 the name `front_of_house`.
  31
  32 <span class="filename">Filename: src/front_of_house.rs</span>
  33
  34 ```rust,ignore
  35 {{#rustdoc_include ../listings/ch07-managing-growing-projects/listing-07-21-and-22/src/front_of_house.rs}}
  36 ```
  37
  38 <span class="caption">Listing 7-22: Definitions inside the `front_of_house`
  39 module in *src/front_of_house.rs*</span>
  40
  41 Note that you only need to load the contents of a file using a `mod`
  42 declaration once somewhere in your module tree. Once the compiler knows the
  43 file is part of the project (and knows where in the module tree the code
  44 resides because of where you’ve put the `mod` statement), other files in your
  45 project should refer to the code in that file using a path to where it was
  46 declared as covered in the [“Paths for Referring to an Item in the Module
  47 Tree”][paths]<!-- ignore --> section. In other words, `mod` is *not* an
  48 “include” operation that other programming languages have.
  49
  50 Next, we’ll extract the `hosting` module to its own file as well. The process
  51 is a bit different because `hosting` is a child module of `front_of_house`, not
  52 of the root module. The file for `hosting` will be in a directory named for its
  53 place in the module tree.
  54
  55 To start moving `hosting`, we change *src/front_of_house.rs* to contain only the
  56 declaration of the `hosting` module:
  57
  58 <span class="filename">Filename: src/front_of_house.rs</span>
  59
  60 ```rust,ignore
  61 {{#rustdoc_include ../listings/ch07-managing-growing-projects/no-listing-02-extracting-hosting/src/front_of_house.rs}}
  62 ```
  63
  64 Then we create a *src/front_of_house* directory and a file
  65 *src/front_of_house/hosting.rs* to contain the definitions made in the
  66 `hosting` module:
  67
  68 <span class="filename">Filename: src/front_of_house/hosting.rs</span>
  69
  70 ```rust,ignore
  71 {{#rustdoc_include ../listings/ch07-managing-growing-projects/no-listing-02-extracting-hosting/src/front_of_house/hosting.rs}}
  72 ```
  73
  74 If we instead put *hosting.rs* in the *src* directory, the compiler would
  75 expect that code to be in a `hosting` module declared in the crate root, not as
  76 a child of the `front_of_house` module. The rules the compiler follows to know
  77 what files to look in for modules’ code means the directories and files more
  78 closely match the module tree.
  79
  80 > ### Alternate File Paths
  81 >
  82 > This section covered the most idiomatic file paths the Rust compiler uses;
  83 > but an older file path is also still supported.
  84 >
  85 > For a module named `front_of_house` declared in the crate root, the compiler
  86 > will look for the module’s code in:
  87 >
  88 > * *src/front_of_house.rs* (what we covered)
  89 > * *src/front_of_house/mod.rs* (older, still supported path)
  90 >
  91 > For a module named `hosting` that is a submodule of `front_of_house`, the
  92 > compiler will look for the module’s code in:
  93 >
  94 > * *src/front_of_house/hosting.rs* (what we covered)
  95 > * *src/front_of_house/hosting/mod.rs* (older, still supported path)
  96 >
  97 > If you use both for the same module, you’ll get a compiler error. Using
  98 > different styles for different modules in the same project is allowed, but
  99 > might be confusing for people navigating your project.
 100 >
 101 > The main downside to the style that uses files named *mod.rs* is that your
 102 > project can end up with many files named *mod.rs*, which can get confusing
 103 > when you have them open in your editor at the same time.
 104
 105 Moving each module’s code to a separate file is now complete, and the module
 106 tree remains the same. The function calls in `eat_at_restaurant` will work
 107 without any modification, even though the definitions live in different files.
 108 This technique lets you move modules to new files as they grow in size.
 109
 110 Note that the `pub use crate::front_of_house::hosting` statement in
 111 *src/lib.rs* also hasn’t changed, nor does `use` have any impact on what files
 112 are compiled as part of the crate. The `mod` keyword declares modules, and Rust
 113 looks in a file with the same name as the module for the code that goes into
 114 that module.
 115
 116 ## Summary
 117
 118 Rust lets you split a package into multiple crates and a crate into modules
 119 so you can refer to items defined in one module from another module. You can do
 120 this by specifying absolute or relative paths. These paths can be brought into
 121 scope with a `use` statement so you can use a shorter path for multiple uses of
 122 the item in that scope. Module code is private by default, but you can make
 123 definitions public by adding the `pub` keyword.
 124
 125 In the next chapter, we’ll look at some collection data structures in the
 126 standard library that you can use in your neatly organized code.
 127
 128 [paths]: ch07-03-paths-for-referring-to-an-item-in-the-module-tree.html