src/doc/book/src/ch07-00-managing-growing-projects-with-packages-crates-and-modules.md

   1 # Managing Growing Projects with Packages, Crates, and Modules
   2
   3 As you write large programs, organizing your code will become increasingly
   4 important. By grouping related functionality and separating code with distinct
   5 features, you’ll clarify where to find code that implements a particular
   6 feature and where to go to change how a feature works.
   7
   8 The programs we’ve written so far have been in one module in one file. As a
   9 project grows, you should organize code by splitting it into multiple modules
  10 and then multiple files. A package can contain multiple binary crates and
  11 optionally one library crate. As a package grows, you can extract parts into
  12 separate crates that become external dependencies. This chapter covers all
  13 these techniques. For very large projects comprising a set of interrelated
  14 packages that evolve together, Cargo provides *workspaces*, which we’ll cover
  15 in the [“Cargo Workspaces”][workspaces]<!-- ignore --> section in Chapter 14.
  16
  17 We’ll also discuss encapsulating implementation details, which lets you reuse
  18 code at a higher level: once you’ve implemented an operation, other code can
  19 call your code via its public interface without having to know how the
  20 implementation works. The way you write code defines which parts are public for
  21 other code to use and which parts are private implementation details that you
  22 reserve the right to change. This is another way to limit the amount of detail
  23 you have to keep in your head.
  24
  25 A related concept is scope: the nested context in which code is written has a
  26 set of names that are defined as “in scope.” When reading, writing, and
  27 compiling code, programmers and compilers need to know whether a particular
  28 name at a particular spot refers to a variable, function, struct, enum, module,
  29 constant, or other item and what that item means. You can create scopes and
  30 change which names are in or out of scope. You can’t have two items with the
  31 same name in the same scope; tools are available to resolve name conflicts.
  32
  33 Rust has a number of features that allow you to manage your code’s
  34 organization, including which details are exposed, which details are private,
  35 and what names are in each scope in your programs. These features, sometimes
  36 collectively referred to as the *module system*, include:
  37
  38 * **Packages:** A Cargo feature that lets you build, test, and share crates
  39 * **Crates:** A tree of modules that produces a library or executable
  40 * **Modules** and **use:** Let you control the organization, scope, and
  41   privacy of paths
  42 * **Paths:** A way of naming an item, such as a struct, function, or module
  43
  44 In this chapter, we’ll cover all these features, discuss how they interact, and
  45 explain how to use them to manage scope. By the end, you should have a solid
  46 understanding of the module system and be able to work with scopes like a pro!
  47
  48 [workspaces]: ch14-03-cargo-workspaces.html