In Rust, what is the purpose of a mod.rs file?

Question

In some Rust projects I've seen (i.e pczarn/rustboot), I've seen mod.rs files in directories for whatever reason. I've not been able to find documentation about this, and I've seen it in many other Rust projects. What is the purpose of a mod.rs file, and when should I use it?

Answer 1

I find modules are particularly poorly explained in documentations of many languages, despite being a base requirement.

If you know python or javascript

You may think of mod.rs as __init__.py in python or index.js in javascript. But there is a bit more to it in rust.

In Rust, folders are not immediately ready to use as modules.

You have to explicitly inform rust that they are available at a certain path in the file system.

That's the purpose of mod.rs.

---

You may also use a file with the same name as the folder. It should be clearer with an example:

src     utils         bar.rs         foo.rs     main.rs 

At this point, the compiler doesn't know about foo.rs and bar.rs.

To expose them, you need to use either of the following options:

• a file named mod.rs, inside of the utils folder
• a file named utils.rs (same name as the folder), at the same level as the utils folder

Whatever option you choose, the file must then explicitly expose files that should be usable outside of the utils folder.

To expose both bar and foo, the content of mod.rs (or utils.rs) should be:

pub mod bar; pub mod foo; 

Based on what solution you choose, the resulting file structure should be:

With mod.rs:

src     utils         bar.rs         foo.rs         mod.rs     main.rs 

With <folder_name>.rs:

src     utils         bar.rs         foo.rs     utils.rs     main.rs 

---

Usage in main.rs:

mod utils; use utils::{foo, bar}; 

---

EDIT:

It is now recommended to use the latter solution (<folder_name>.rs).

From the Rust reference:

Note: Previous to rustc 1.30, using mod.rs files was the way to load a module with nested children. It is encouraged to use the new naming convention as it is more consistent, and avoids having many files named mod.rs within a project.

(Thanks to MarkusToman for bringing this to my attention)

Answer 2

Imagine the following directory structure:

 code/   `- main.rs    - something/      `- mod.rs 

If in main.rs you do mod something;, then it'll look in the something/mod.rs file to use as the contents of the module declaration for something.

The alternative to this is to have a something.rs file in the code/ directory.

So to recap, when you write an empty module declaration such as mod something;, it looks either in:

• a file called something.rs in the same directory
• a file called mod.rs in a folder called something in the same directory

It then uses the contents of either of those files to use as the contents of the module declaration.