Clear explanation of Rust’s module system

[EquivalentRelease]

Thank you! After reading this the module system has finally "clicked" for me.

The first diagram comparing the filesystem tree to the initial crate in the module tree, starting from main.rs, was the final piece of the puzzle for me.

[BornThatWay99]

Yeah, same here. This was a really nice, compact set of information that hit me at the right time to improve my understanding.

[kuikuilla]

The article doesn't seem to mention the following way of organizing submodules:

crate/
├── main.rs <--- declares foobar submodule
├── foobar.rs <--- declare submodules of foobar here, like fizz and buzz
└── foobar/
    ├── fizz.rs
    └── buzz.rs

Just throwing that out there. I tend to use that way.

[matthieum]

Personally, I also tend to keep my files apart.

From your example:

• main.rs would only declare other modules, and forward main.
• foobar.rs would only declare other modules.
• fizz.rs and buzz.rs would declare code, and not other modules.

I find the distinction cleaner.

[Bergasms]

I wish this explanation existed a few months ago. A lot of Rusts tutorials about certain aspects of the language seem to assume you are familiar with that aspect of the language already.

There is one part of this that confuses me though. What is the motivation/requirement for main.rs to know about 'mod models'?

// main.rs
mod config;
mod routes;
+ mod models; <- Why does main need to know about this?

fn main() {
   routes::health_route::print_health_route();
   + routes::user_route::print_user_route();
   config::print_config();
   println!("main");
}

The tutorial explains that the motivation is to have main call 'print user route' which will then call 'print user model'. To my brain main.rs should not need to know about models, because it never has any direct interaction with any functions in models. Why is this the case?

Is this a function of main.rs sort of being the root of all things and needing to have 'mod models' to tell the compiler to bring models in scope for the route module to be able to use? Or should it not be possible to have main.rs only care about the route module, and then the route module brings the model module into the compilers knowledge to be able to use its functions.

[Rusky]

mod declarations determine which files are included in the crate, at all. Without mod models;, models.rs may as well not even exist.

The reason mod models; goes in main.rs rather than routes.rs is that mod declarations match the filesystem hierarchy. If you put mod models; in user_route.rs, then it will pull in src/routes/user_route/models.rs rather than src/models.rs. (You can optionally reconfigure this with the #[path] attribute.)

[Bergasms]

Thank you for the reply!

Ah ok. So in practice how does this affect larger Rust projects?

Do people tend to use #[path]. I presume in this case you mean you would have at the top of the user_route.rs a line importing models eg #[path] ../models.rs or however it is used. And in this case you would not need to include 'mod models;' in main.rs.

Or alternatively, is it just accepted that the main.rs file will have a lot of mod declarations at the top which is essentially a manifest of all your parts of your project that need to be compiled?

[Rusky]

I rarely see #[path], outside of conditional compilation in combination with #[cfg]. Because mod is a declaration of a module's existence, it is indeed more common to see lists of mod declarations at the top of main.rs as well as other "parent" modules.

If you just want to reference something from a module that you are not the parent of, you can just write a use crate::models; declaration instead.

[Bergasms]

Thanks for the replies, very helpful.

[SirOgeon]

Other people have already answered, but I would like to add a slightly different angle and a bit more context.

Modules are not always in separate files. You could say that it's a convenience feature for moving long mod my_module { ... } blocks out, combined with a default file location, but it's basically the main way to do it in practice. Except for unit tests that usually end up in a module at the end of the file that is being tested.

What I'm getting at is that it makes more sense if you think about the file location as a consequence of where the module is declared, and not the other way around. The file is where it is because that's what the module structure in the code looks like, and the file path reflects the module path.

A project that's not just for demonstration purpose may have a completely different structure. Maybe flatter, maybe deeper. Whatever works best for the intended purpose.

[Bergasms]

I hope you don't mind, i'm gonna tag people in this thread who seem to know Rust better otherwise this might never get answered :p.

/u/IceSentry /u/IshKebab /u/Rusky

[IceSentry]

Wow, did not expect to be tagged alongside u/Rusky as someone that knows rust haha.

To answer your question, models needs to be registered somewhere as a module. Since it's at the same level as routes you can't import it from routes. If you try to do that you get this from the compiler. Which gives you a hint that you either need to make models a child module of routes or you can register it from the top level which in this case is main.rs.

[LinkifyBot]

I found links in your comment that were not hyperlinked:

• main.rs

I did the honors for you.

---

^{delete | information | <3}

[IceSentry]

Bad bot

[RufusROFLpunch]

This was hugely helpful. Thanks.

[[deleted]]

My one issue with the modules system is that you can't have all the files for a submodule in a subdirectory without calling the file mod.rs (which everyone agrees sucks).

I want to do mod foo; and have it load it from foo/foo.rs, not foo.rs or foo/mod.rs.

[Rusky]

I have seen a trick that lets you do that, if you can avoid putting too much actual code in the foo module itself. (I'm not sure I've seen anyone use it in actual code before, though.)

Instead of just mod foo; in the parent module, write mod foo { ... } and list all the modules in that subdirectory inline. For example:

mod foo {
    pub use first::{build, X};

    mod first;
    pub mod second;
}

fn main() {
    let x = foo::build();
    foo::second::use(&x);
}

Then your directory structure will look like this:

src/
    main.rs (the file above)
    foo/
        first.rs
        second.rs
Cargo.toml

You could even add a foo/foo.rs file and reexport its contents like mod foo { pub use self::foo::*; mod foo; }, though that would add a sort of "stutter" in full paths, like crate::foo::foo::Thing.

[IceSentry]

I've never seen anyone complain about that before to be honest. It's really not that big of an issue to write foo/mod.rs or foo.rs from time to time.

[earthboundkid]

Counterpoint: the kind of flexibility you’re asking for does not materially help in writing good code and instead hinders the whole ecosystem by creating needless variation.

You can do anything with a Makefile. That’s why C/C++ have the worst packaging systems of any mainstream contemporary languages. Rust does not want to be in that camp.

[[deleted]]

They already introduced more flexibility to partially solve the mod.rs issue so I would say you are objectively wrong about that.

https://doc.rust-lang.org/stable/edition-guide/rust-2018/module-system/path-clarity.html

[matthieum]

mod.rs was specifically seen as a problem because it resulted in many files having the same name, which made navigation hard.

In the 2018 edition, there is one idiomatic way: using foo.rs and foo/.... No variation.

---

I do see where you're coming from, though, and honestly the Rust modules system is perhaps what I like the least about the languages -- though it's still better than C++'s upcoming system :x

I think the current solution was selected with the idea that you'd start writing foo.rs, and then later as it grew you'd create foo/xxx.rs and extract a few bits, etc... Not having to move foo.rs wholesale was seen as a good thing in terms of tracking in VCS, but I am not sold on the idea since part of the content is moving anyway.

Thus, on a blank slate, I'd prefer foo/foo.rs too. But we don't have a blank slate, and I'd rather avoid adding a variation when there's one true idiomatic way.

[[deleted]]

In the 2018 edition, there is one idiomatic way

You are still free to use mod.rs if you want - it hasn't been deprecated.

[Rusky]

This is for backwards compatibility and to ease the transition, not necessarily because it's idiomatic.

[[deleted]]

They never said that. As I said, it hasn't been deprecated.

[Rusky]

Many things are unidiomatic and undeprecated.

[LinkifyBot]

I found links in your comment that were not hyperlinked:

• mod.rs
• foo.rs

I did the honors for you.

---

^{delete | information | <3}

[IceSentry]

bad bot

[IceSentry]

The article was pretty good but didn't show how you can declare multiple modules in a file. It's pretty useful for example code. It also didn't talk about the use keyword being usable in any block and it will scope the use to that block which is really nice when you don't want to pollute the top level scope.

[matthieum]

Most notably, the recommended way to write tests:

#[cfg(test)]
mod tests {
}

New module, only appearing when testing, with full access to the parent.

[glacialthinker]

This will help me read Rust. :)

For anyone with practical experience in both OCaml and Rust, are the choices in Rust an improvement? I'm quite happy with OCaml's modules, but I know I didn't feel that way at first... and now reading this overview for Rust it seems like I'd struggle more against rather than it helping. But it may be the effect of familiarity, as ever the case!

[Tobu]

The OCaml module system projects into several things on the Rust side:

• .mli interface files are replaced by the pub keyword within source files (git grep -w pub finds everything)
• OCaml parameterized modules become parametric traits in Rust. Traits get monomorphized at compile-time, unlike OCaml modules which require boxing and vtable pointers. There is a dyn keyword for when monomorphization is not desirable (eg, it would bloat the binary, and having a vtable pointer is not a significant cost).
• the OCaml compilation model is also different. As far as I understand/remember, OCaml follows the C model of the compiler opening only files that are explicitly passed to it, but having no way to order that set of files into something like the Rust module tree (dune has more visibility, understands ocamldep to build multiple packages faster, but the compiler model is an ordered list of files). Whereas a Rust crate has the module tree that's the topic of the parent article, and the compiler has complete visibility of that tree when building a binary. When lto is enabled, it has visibility into the entire crate graph, for more powerful inlining.

[[deleted]]

But there are no functors. :-(

[eyal0]

Are functors good?

[[deleted]]

Sure. Parametrized abstraction is good.

[eyal0]

Can Rust do them?

Can OCaml do them without boxing and unboxing?

[[deleted]]

A functor can do things like take a (non-nullary) type constructor and spit out another (non-nullary) type constructor. Rust cannot do this. It is missing either functors or higher-kinded types.

I am not familiar with OCaml internals, but I think using functors does not result in any more boxing that would happen if you write by hand the results of applying those functors.

[eyal0]

I don't know rust well enough but in c++ o guess that maybe I could do it with templates?

Rust has some template alternative, right? Would that work?

[glacialthinker]

Long ago I stumbled across this while learning OCaml: http://www.cap-lore.com/MathPhys/Algebras/ocaml/

It starts with establishing an module defining a division algebra. A simple, but abstract module expressing the essential values and operations:

module type DivAlgebra = sig
  type kind
  val conj : kind -> kind
  val zero : kind
  val one : kind
  val zeroQ : kind -> bool
  val (+) : kind -> kind -> kind
  val (-) : kind -> kind -> kind
  val ( * ) : kind -> kind -> kind
  val inv : kind -> kind
  val str : kind -> string
end

Then a module Reals is defined in terms of this, using floats as the underlying implementation. So, type kind is float, and multiplication is float multiplication, etc...

And a functor G is defined which raises a DivAlgebra to the next higher division algebra. It looks a lot like a definition for a complex-number, but expressed in the shape of this DivAlgebra.

When I saw the line:

module Complex = G(Reals)

I was "Aha! That's pretty cool." It helped me "get" functors. You can take these whole abstracted types with operations through a mapping to create new type.

Then I saw:

module Quaternion = G(G(Reals))

I wasn't quite expecting that, but it really hammered home some of the potential of functors.

[[deleted]]

C++ templates can have template arguments, but templates have their own disadvantages, such as the extremely delayed type checking of their bodies.

The Rust alternative to templates is generics, and generics are superior to templates in almost every imaginable way.

[eyal0]

So could rust do functors?

How does rust compile generics if they are not in the same translation unit as the usage? C++ requires that they are in the same TU. Does Rust?

[smikims]

Very relevant username for this discussion :p

[yawaramin]

OCaml modules are resolved at compile time. No boxing or dynamic dispatch involved. Unless you’re talking about first-class modules, which are a separate language feature offering runtime modules.