(Modules) Tracking issue for the `mod.rs` changes

[Centril]

This is a sub-tracking issue for the RFC "Clarify and streamline paths and visibility" (rust-lang/rfcs#2126)
dealing with the mod.rs changes.

• Implement the RFC, [RFC 2126] permit foo.rs or foo/mod.rs to support submodules like foo/bar.rs #45385
• Adjust documentation (see instructions on forge)
• Stabilization PR (see instructions on forge)

Unresolved questions:

None

Summary

A foo.rs and foo/ subdirectory may coexist; mod.rs is no longer needed when placing submodules in a subdirectory.

[joshtriplett]

Of the various module changes, this one seems quite clear, uncontroversial, and ready to commit to.

@rfcbot fcp merge

[rfcbot]

Team member @joshtriplett has proposed to merge this. The next step is review by the rest of the tagged teams:

• @aturon
• @cramertj
• @eddyb
• @joshtriplett
• @nikomatsakis
• @nrc
• @pnkfelix
• @scottmcm
• @withoutboats

No concerns currently listed.

Once a majority of reviewers approve (and none object), this will enter its final comment period. If you spot a major issue that hasn't been raised at any point in this process, please speak up!

See this document for info about what commands tagged team members can give me.

[sanmai-NL]

@joshtriplett: gave your post a thumbs down for the record, because you didn’t support your statement that it’s uncontroversial, while I can think of a few questions around this.

Multiple equivalent module configuration mechanisms

So both foo/mod.rs and foo.rs are going to be supported? I wouldn’t look forward to that. From a teachability perspective, the possibility of two ways to do the same thing even if one way is perhaps more straightforward is not an improvement. The newer, easier way will perhaps not be reflected in the ecosystem for some time to come so new programmers will not necessarily be inclined to use the newer, easier way.

Common submodules and module configuration

What is clearer:

A (now)

foo/mod.rs
foo/tests.rs

B (possibility after this change)

foo.rs
foo/tests.rs

A possible limitation here is that directories and files are often sorted separately in IDEs (e.g., IntelliJ IDEA) and filesystem explorers (e.g., Gnome Files) so there may be a large visual gap between foo.rs and its related foo/.

Non-code resources and module configuration

include_bytes! and include_str! look up resources relative to the current module’s directory. This means a mod.rs-like config would perhaps be clearer, similar to example B in my previous point.

[joshtriplett]

@sanmai-NL I didn't intend to suggest that there was unanimity, just that unlike some of the other module changes, there hasn't been widespread objection or disagreement, such as in the various edition feedback threads. Addressing your points specifically:

Multiple equivalent module configuration mechanisms

The intention is to primarily point people to foo.rs. We want to keep foo/mod.rs for compatibility, so this change doesn't break existing projects. And we can provide appropriate lints (for people who want to write idiomatic Rust 2018 code) that encourage renaming the files accordingly, to help migrate the ecosystem. So I wouldn't expect this to bifurcate the ecosystem.

Common submodules and module configuration

Today, foo::bar could map to either foo/bar/mod.rs or foo/bar.rs depending on whether it has submodules. Similarly, foo::bar::baz maps to foo/bar/baz.rs or foo/bar/baz/mod.rs. That inconsistency makes it more difficult to look at a path in code and map it to the filesystem. So, I'd suggest that it's clearer to look at foo::bar and always know that you just mentally map each :: to / and append .rs.

Non-code resources and module configuration

Depends on your interpretation of where the module lives. While some other languages do have facilities similar to mod.rs, most tend to put code associated with a module named "foo" in a file foo.ext, and when that file includes something it would do so relative to the directory containing that file. This is a subjective difference.

More importantly, because of the inconsistency in the previous point, with today's system if you want to add a submodule to an existing module, you'd have to move the module to mod.rs, which would then change the location that include_bytes! and similar start from. With this change, you don't have to move the file to add submodules, so those paths always consistently start from the same place.

[rfcbot]

🔔 This is now entering its final comment period, as per the review above. 🔔

[Nemo157]

I just want to report some experience trying this out. On a relatively small (4 relevant sub-modules) new crate for futures I used the new form exclusively. As a CLI only programmer I found the interference with tab completion to really break my workflow, enough so that I eventually gave up and reverted to the old form.