Package Crate Module

Comprehension

一个 package 至多只能有一个 library crate，但能有多个 binary crate

• module 和 pub

  mod front_of_house {
      // 其他 module 引用这里的嵌套 module，需要有 pub 修饰
      pub mod hosting {
          // 其他 module 引用这里的 fn 也需要有 pub 修饰
          pub fn add_to_waitlist() {}
      }
  
      // 引用嵌套 struct 也需要有 pub 修饰
      pub struct Breakfast {
          // struct 内的 field 默认都是 private，外部访问也需要 pub 修饰
          pub toast: String,
          seasonal_fruit: String,
      }
  
      impl Breakfast {
          pub fn summer(toast: &str) -> Breakfast {
              Breakfast {
                  toast: String::from(toast),
                  seasonal_fruit: String::from("peaches"),
              }
          }
      }
  }
  
  pub fn eat_at_restaurant() {
      // Absolute path
      crate::front_of_house::hosting::add_to_waitlist();
  
      // Relative path
      front_of_house::hosting::add_to_waitlist();
  }
  

• module 和 use

  // 类似于 C++ 的 using namespace
  mod front_of_house {
      pub mod hosting {
          pub fn add_to_waitlist() {}
      }
  }
  use crate::front_of_house::hosting;
  pub fn eat_at_restaurant() {
      hosting::add_to_waitlist();
      hosting::add_to_waitlist();
      hosting::add_to_waitlist();
  }
  
  // 支持 use 的时候用 pub 修饰，也称 Re-exporting，外部使用时可直接 hosting::xxx
  pub use crate::front_of_house::hosting;
  
  // 可以简化 use
  use std::cmp::Ordering;
  use std::io;
  use std::{cmp::Ordering, io};
  
  // 简化时可以用 self
  use std::io;
  use std::io::Write;
  use std::io::{self, Write};
  
  // 可以用 * 引入所有 module
  use std::collections::*;
  

当用 mod a; 时，会读取同级目录下的 a 文件夹/文件

Origin

https://doc.rust-lang.org/book/ch07-00-managing-growing-projects-with-packages-crates-and-modules.html

…

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.

Several rules determine what a package can contain. A package can contain at most one library crate. It can contain as many binary crates as you’d like, but it must contain at least one crate (either library or binary).

…

Separating Modules into Different Files

So far, all the examples in this chapter defined multiple modules in one file. When modules get large, you might want to move their definitions to a separate file to make the code easier to navigate.

For example, let’s start from the code in Listing 7-17 and move the front_of_house module to its own file src/front_of_house.rs by changing the crate root file so it contains the code shown in Listing 7-21. In this case, the crate root file is src/lib.rs, but this procedure also works with binary crates whose crate root file is src/main.rs.

Filename: src/lib.rs

mod front_of_house;

pub use crate::front_of_house::hosting;

pub fn eat_at_restaurant() {
    hosting::add_to_waitlist();
    hosting::add_to_waitlist();
    hosting::add_to_waitlist();
}

Listing 7-21: Declaring the front_of_house module whose body will be in src/front_of_house.rs

And src/front_of_house.rs gets the definitions from the body of the front_of_house module, as shown in Listing 7-22.

Filename: src/front_of_house.rs

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

Listing 7-22: Definitions inside the front_of_house module in src/front_of_house.rs

Using a semicolon after mod front_of_house rather than using a block tells Rust to load the contents of the module from another file with the same name as the module. To continue with our example and extract the hosting module to its own file as well, we change src/front_of_house.rs to contain only the declaration of the hosting module:

Filename: src/front_of_house.rs

pub mod hosting;

Then we create a src/front_of_house directory and a file src/front_of_house/hosting.rs to contain the definitions made in the hosting module:

Filename: src/front_of_house/hosting.rs

pub fn add_to_waitlist() {}

The module tree remains the same, and the function calls in eat_at_restaurant will work without any modification, even though the definitions live in different files. This technique lets you move modules to new files as they grow in size.

Note that the pub use crate::front_of_house::hosting statement in src/lib.rs also hasn’t changed, nor does use have any impact on what files are compiled as part of the crate. The mod keyword declares modules, and Rust looks in a file with the same name as the module for the code that goes into that module.