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?
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.
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.
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.
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.
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:
mod.rs
, inside of the utils
folderutils.rs
(same name as the folder), at the same level as the utils
folderWhatever 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)
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:
something.rs
in the same directorymod.rs
in a folder called something
in the same directoryIt then uses the contents of either of those files to use as the contents of the module declaration.
If you love us? You can donate to us via Paypal or buy me a coffee so we can maintain and grow! Thank you!
Donate Us With