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
tomodule.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
andmodulename.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.