learning-modules.md

• "Importing functionality and importing namespace are two steps: mod and use"
• "I had far more issues divding my code into multiple files and modules than in any other language I worked up to now."
• "to me the rust module system is surprisingly counter-intuitive, having not used anything similar"
• "I started writing multi-file Rust today, and I think the way it currently works is completely counterintuitive to newcomers. Documentation is no substitute for sane defaults."
• "At the moment all imports come from the root of the crate by default in order to remove ambiguities when resolving paths. How about making working relative to the current module the default?"
  • "This might make things less surprising – I still get tripped up by having to use self:: for working relative to the current" module
• "i'm the same in that every time i pick it up after a break, what it does is completely surprising"
• "The biggest pain IMO is splitting a module across multiple files. Right now you need reexports or include!, the first being verbose and error-prone (without glob reexports) and the second being a hack, or just deal with introducing unnecessarily deep/wide heirarchies. Phrased another way, we currently have a way to write mods independant of files mod foo { contents }, but not a way to write files independant of mods."
• "The filesystem is always going to be there and we'll be putting code inside files inside folders forever; might as well have that hierarchy be reflected as modules/packages and reduce confusion."
• "If we could sum up the Rust module system with "mod defines the modules structure, use brings names into scope" and expect people to figure the rest out from just that one sentence, no one would complain. But such a simplification papers over the module file lookup rules, the use-always-comes-before-mods rules, the visibility interactions etc. Unfortunately the module system can't be so succinctly explained because it's far more complex than that."
• "I've had zero problems making anything work, except for maybe a few minutes of confusion the first time I tried using a crate and mixing things together with my own modules, along with a minute or two getting my head around super:: etc."
• "As a somewhat advanced user, Rust is maybe my twelfth programming language, and literally the only part I had trouble with was the module system"
  • "Same here, it took me a while to figure it out coming from everything else. "
• "The module system is confusing."
• "Personally, what confused and still confuses me the most are namespaces in module(?) path, when to use "self", when to use "super", when you can avoid using anything"
• "I deeply agree with the premise that the Rust module system is too confusing."
  • "Having to specify extern crate for Cargo dependencies. This feels like boilerplate/make-work. Why is this necessary?"
  • "Confusion on when to use self and super. Are we relative to the crate root, or relative to the current module, and in what contexts?"
  • "specifying things in the source code that could somewhat trivially be derived from directory layout also feels like boilerplate/make-work to some extent"
• "Most of the module problems in #rust that I've seen arise from:"
  • "use paths working differently from inline paths"
  • "exactly how privacy works"
  • "the fact that you can have modules both inline and as separate files"
  • "The rules are not too confusing, but they're not things you will easily figure out on your own and folks usually get lost in a spiral of trial-and-error where they come up with bad explanations for things."
• "I don't mind Rust's module system, but I can see where it's confusing—the module hierarchy mostly follows the filesystem hierarchy, but if you seen foo.rs and bar.rs side-by-side, it's not obvious what the hierarchy is: foo.rs might contain mod bar;, bar.rs might contain mod foo;, or some other file might contain mod foo; mod bar; making them siblings."
• "My biggest problem was figuring out how to refer to types defined in sibling modules. Once I figured out :: to get back to the crate root I was golden." 0 "I was quickly able to gasp the file structure and how that all works, but I while I know enough to get it to work, I still struggle to understand what each line is doing."
• "Coming from Java and Python, I've found Rust's module system to be pretty confusing. It definitely tripped me up in my early days to the point where my learning progress was totally stalled for a while."
  • "Things I've struggled with:"
    • "Understanding what extern crate is actually doing."
    • "How to refer to the module loaded by extern crate after it's imported, and why this is a separate step from extern crate."
    • "Understanding how mod blah; and the existence of blah.rs combine to be equivalent to mod blah { /* contents of blah.rs */ }"
    • "self/super. When am I doing relative imports and when am I doing absolute imports? Why must some imports be relative while others can be absolute?"
  • "But it is frustrating to me that extern and mod are both necessary for importing external code. Shouldn't the modules be in my build path because of the build tool (cargo or whatever) and I not have to worry about adding things to the build path using extern? Couldn't we assume that any build tool will be competent at adding dependent libraries to the build path since that's what such tools are there for?"
• "it's mainly the pathing that's confusing me though (when am I using relative vs. absolute? And when should I use which?)."
• "When I was learning it it just seemed extremely unintuitive."
• "It was hard to understand at first, especially after C++, but now I'm fine and like it."
• Stack overflow question on splitting module into files
• "For imports, the namespace hierarchy should have a one-to-one correspondence with the file and directory hierarchy."
• "This was my experience, too. I had to keep checking other crates to see what was expected from me, and managed to finally understand through trial-and-error.The problem with this is that I'm not likely to remember how modules work a few months after finishing a Rust project. I reckon core aspects of a language should be so simple that they don't need any work memorising them."
• "The main issue with Rust's module system is that your own modules and crates live in the same namespace."
• "The Rust module system is a little bit weird. As far as I can tell, this is the result of two things:"
  • "'use' statements are relative to the root of the crate, not the current module. To work around this, you can write 'use self::name' or 'use super::name' for relative imports. Annoying but no big deal."
  • "If you import a symbol into module 'a', it doesn't also get added to 'a::b'. I don't know why I keep expecting this."

• I'm writing an application. Inside main.rs I can write

  extern crate foo;
  use foo::Bar;
  

  If I create a module and use the same crate, I need to write:

  extern crate foo;
  

  use self::foo::Bar;

  This always surprises me and I never found anything explicit written on the Book.