Filesystem Hierarchy

The module content can be omitted:

mod garden;

The garden module content is found at:

  • src/garden.rs (modern Rust 2018 style)
  • src/garden/mod.rs (older Rust 2015 style)

Similarly, a garden::vegetables module can be found at:

  • src/garden/vegetables.rs (modern Rust 2018 style)
  • src/garden/vegetables/mod.rs (older Rust 2015 style)

The crate root is in:

  • src/lib.rs (for a library crate)
  • src/main.rs (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.

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

// Harvest the produce in the garden that is ready.
fn harvest(garden: &mut Garden) { todo!() }

  • The change from module/mod.rs to module.rs doesn’t preclude the use of submodules in Rust 2018. (It was mandatory in Rust 2015.)

    The following is valid:

    src/
├── main.rs
├── top_module.rs
└── top_module/
    └── sub_module.rs

  • The main reason for the change is to prevent many files named mod.rs, which can be hard to distinguish in IDEs.

  • Rust will look for modules in modulename/mod.rs and modulename.rs, but this can be changed with a compiler directive:

    #[path = "some/path.rs"]
mod some_module { }

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