Filesystem Hierarchy

Omitting the module content will tell Rust to look for it in another file:

mod garden;

This tells rust that the garden module content is found at src/ Similarly, a garden::vegetables module can be found at src/garden/

The crate root is in:

  • src/ (for a library crate)
  • src/ (for a binary crate)

Modules defined in files can be documented, too, using “inner doc comments”. These document the item that contains them – in this case, a module.

//! This module implements the garden, including a highly performant germination
//! implementation.

// Re-export types from this module.
pub use seeds::SeedPacket;
pub use garden::Garden;

/// Sow the given seed packets.
pub fn sow(seeds: Vec<SeedPacket>) { todo!() }

/// Harvest the produce in the garden that is ready.
pub fn harvest(garden: &mut Garden) { todo!() }
  • Before Rust 2018, modules needed to be located at module/ instead of, and this is still a working alternative for editions after 2018.

  • The main reason to introduce as alternative to filename/ was because many files named can be hard to distinguish in IDEs.

  • Deeper nesting can use folders, even if the main module is a file:

    └── top_module/
  • The place rust will look for modules can be changed with a compiler directive:

    #[path = "some/"]
    mod some_module;

    This is useful, for example, if you would like to place tests for a module in a file named, similar to the convention in Go.