Logo Questions Linux Laravel Mysql Ubuntu Git Menu
 

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

Tags:

module

rust

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?

like image 927
Liam Marshall Avatar asked Oct 18 '14 00:10

Liam Marshall


People also ask

Is a Rust file a module?

Rust relies on a module tree in order to resolve all parts necessary to build. As covered before, the (crate) root of that tree is our src/main.rs file.

What does Pub mod do in Rust?

pub(super) makes an item visible to the parent module. This is equivalent to pub(in super) . pub(self) makes an item visible to the current module. This is equivalent to pub(in self) or not using pub at all.

How do you import a module in Rust?

To import the module, we use the keyword mod , followed by the file name without the . rs extension. When a module is imported, it allows us to use any code that's marked as public in the file we're importing the module from. Note that the module must be imported before we use any of its code.

Are Runescape Mods deprecated?

In Rust 2018, mod.rs is no longer needed. This eliminates the special name, and if you have a bunch of files open in your editor, you can clearly see their names, instead of having a bunch of tabs named mod.rs.


2 Answers

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)

like image 28
Romain Vincent Avatar answered Sep 23 '22 19:09

Romain Vincent


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.

like image 192
Jorge Israel Peña Avatar answered Sep 24 '22 19:09

Jorge Israel Peña