New guide: crates and modules

[steveklabnik]

This is an almost-done draft of a guide on crates and modules. This is a hard guide to get right, I had to remove a chunk of the Guide because it was confusing.

I've also pushed up https://github.com/steveklabnik/phrases which has matching code. Whenever we finish this guide, I think it'd be good to have a sample crate like this in the rust-lang org for people to compare against. The hardest part of a guide like this is that it depends on multiple files being correct, and being able to point to a repository would be very helpful.

Things yet to do:

1. external crates via cargo
2. documentation

I'm super open to still revising this if it's still confusing. There's been a lot of Reddit discussion about the module system, and I tried to incorporate those posts and the comments into this.

[steveklabnik]

Oh, and paralell compilation via splitting things up into multiple crates needs to be added.

[alexcrichton]

I've only read one sentence, and I'm already excited!

[alexcrichton]

🌴

[bkloster]

A definition of "compilation unit" would be good here. If I understood the following paragraphs correctly, it seems to be a bit different from translation unit or C#'s use of the term.

[steveklabnik]

agreed.

[charlieflowers]

This helped me a lot. However, I was still confused when trying to "cargo-ize" a project I've been working on for a while. I could not figure out how to let module A use module B, and to let my lib.rs use them both.

Then I came across this statement in an online discussion, and everything became clear. I'm sharing it here in case it helps you capture and squash forever the source of my confusion: "You compile a crate, not files. foo.rs is just mod foo { ... } factored out. foo/bar.rs is just mod foo { mod bar {...} }. They have no meaning without the crate root."

[charlieflowers]

Let me clarify the confusion I have now resolved, in the hopes it can improve the guide. I was coming from a C# mindset (I imagine Java would be similar). If I have module A that uses module B, and I want my library to use both of them, then why can't module A say, within its own source file, to import module B? In fact, if I start out by coding module A and then module B (but not the library using them yet), that approach is exactly right: module A will say "mod moduleB;".

But once I make a library, I have to remove that line from module A. Instead, my lib.rs will say "mod moduleA;" and "mod moduleB;". At first, this feels entirely wrong to a C# developer because, if module A depends on module B, it should simply be able to say so!

The reason this is confusing from a C# mindset is that C# developers are not used to explicitly stating what they want inside of a "crate." They don't have to think about a crate concept at all. If my C# exe needs to use library Foo, and Foo uses Bar, I don't have to say anything about Bar in my exe.

But in Rust, in my "crate file," I must explicitly state all the things that will be included in the crate. Once I got that point, everything was clear to me. (I'm sure there are nuances I'm unaware of ... maybe this comment will help you capture and elucidate them too).

I assume Rust wants you to explicitly state what's in your crate in order to give you greater control, and also probably so you don't have the C++ "headers being loaded multiple times" problem. But that might be something to address too.

[renato-zannon]

But once I make a library, I have to remove that line from module A. Instead, my lib.rs will say "mod moduleA;" and "mod moduleB;". At first, this feels entirely wrong to a C# developer because, if module A depends on module B, it should simply be able to say so!

I'm a Ruby developer, and I second this confusion. It took me a lot of head scratching before I stopped trying to simulate require using mod foo;.

[aturon]

What's the status on this PR? Good to go?

[steveklabnik]

@aturon the conventions question is still open, and i should either remove the header or fill out the 'documenting crates' section. What do you think?

[steveklabnik]

I've squashed this up, and as long as we're okay with the convention, I think it's good to go.

[alexcrichton]

Looks good to me, two minor nits and otherwise r=me:

• Would you be ok leaving out the multi-line import for now? We can add it back in once we have a convention around it (and it seems like it's a kinda just tacked on anyway right now)
• Can you run rustdoc --test over this guide? I think some examples will need to be marked with ignore.

[steveklabnik]

how embarrassing 😦 😓 😅

fixed. :)