Book: Multi-file projects not explained?

[ahowlett1965]

I read the post https://github.com/rust-lang/book/issues/328 with considerable interest as I (38 years experience) was having exactly the same issues with "large" projects as donaldcallen, namely my inability to just add multiple source files to a potentially large Rust project.

Rather than revisit that debate, can I suggest that the book would benefit from a section like this:

---

Writing large, multi-file projects
The idiomatic Rust paradigm for projects with multiple files differs from those of traditional languages like C & Python, where a project of any size would typically contain many source files. The Rust approach is to break the source up by creating many crates (--lib), with one source file per library. These libraries are then used in the main (--bin) crate, and of course libraries may use code in other libraries.

---

If there is a convention for the name of the --bin file, eg main.rs, that would be a great place to add it, but I've not yet noticed such a convention.

There doesn't seem to be a neat place to put such a section- Adding it as 1.4 might work, as might Appendix H. I think it should appear in the list of sections and not just as a footnote so that it is more findable when people are searching the table of contents in their browser.

Please correct me where my understanding is wrong- I have only spent 1-2 days on Rust so far!

[steveklabnik]

A few things:

The Rust approach is to break the source up by creating many crates (--lib), with one source file per library.

Library crates often have way more than one file per library.

If there is a convention for the name of the --bin file, eg main.rs, that would be a great place to add it, but I've not yet noticed such a convention.

It is main.rs, and it's covered in chapter 1, section 3.

Rather than revisit that debate, can I suggest that the book would benefit from a section like this:

What do you think about Chapter 7.2? it's focused on multi-file projects.

[ahowlett1965]

Thanks for your points. I recognise my poor understanding of rust, so please feel free to correct my proposed text in any way you see fit. :-)
I am, however, a world-class expert on the difficulties I had! If I said that the explanation I now have is compatible with the documentation, but compatibility is not sufficient: The purpose of the documentation is to help the ignorant (that's me!) to understand, which it didn't. Section 7.2 seems to cover alot of ground about how to arrange things, but again it's compatible with the idiomatic rust way of working rather than screaming "make lots of libraries, with one crate per library, and potentially several source files per library crate". The title, "Modules and use to control scope" didn't do anything to make me explore that section further, which is why I think a section with a title that includes something like "large projects" or "multi-file projects" would have been really helpful, even if the content was only a few lines long.
I don't know that I have much more to add to this. I really appreciate the documentation and the time people have spent creating and updating it, but in this regard I didn't get what I needed.

[carols10cents]

So Chapter 7 is being revised heavily right now; I'm still working on revisions as a result of feedback from our editors at nostarch but I'll be keeping your feedback here in mind as well.

What if chapter 7 was called "Managing large projects with packages, crates, and modules", a paragraph describing the overall strategy of splitting modules into many files and then crates into multiple crates as they grow was added to the start of that chapter, and there was a 7.4 section called "separating modules into different files"? Does that sound helpful?

If all that is hard to imagine, I'll ping you when we have those revisions up in a readable format :)

[ahowlett1965]

That would probably be perfect. I am an experienced developer who has only just started with Rust. I knew that I needed to create lots of source files, and I couldn't figure out how to do so in a --bin crate, and I spent quite a while trying to find how to fit them in.
Your proposed title would attract my attention. Box ticked excellently.
Your proposed intro giving the idea that multiple crates with multiple source files was the way to go? Another box ticked excellently.
Your 7.4 "separating modules into different files" also seems good.
But I am a bit handicapped by my ignorance of rust, a problem I am working hard to overcome!
Thank you, I am encouraged.
I have some proof-reading experience and am happy to go over your proposal when you're ready. The English I've read so far has been very good (I am picky, usually finding loads of errors, so this is a real compliment!).

[carols10cents]

Thank you so much @ahowlett1965! I've just made a PR for edits that I'd love to get your feedback on-- the markdown version and the diff are a bit... ugly to read, so I also put the proposed new version of chapter 7 up on my fork's gh-pages here: https://carols10cents.github.io/book/ch07-00-managing-growing-projects-with-packages-crates-and-modules.html

Please let me know if this is better or worse and if you have any further suggestions on how to improve this chapter!!