Write a "practical" Rust guide

[brson]

I've been convinced recently that Rust is missing crucial documentation of a particular nature: using Rust in practice. I would like to have such a standalone guide, and these are some ideas about what should be in it.

This is a guide that runs through creating an entire Rust project from installation, using the tools, writing code, through deployment, touching on the practical aspects of coding Rust, not glossing over whatever ugly bits are necessary to do real work.

Some of the topics I might expect include:

• Installation
• Running rustc
• lib.rs/bin.rs/mod.rs conventions
• Evolving a project from a single file to multi-file/mod/directory
• Picking the correct types for various problems
• Obtaining and using other crates
• Setting up a build system (not cargo to start, cargo when it's ready)
• Working with the compiler to find the correct algorithms. Show typical ways you might concieve the solution incorrectly and how the compiler helps guide you to the correct one. Particularly re: borrowck.
• Common Rust patterns (like?)
• Rust CI, other community resources?
• Using rust-bindgen to create bindings that don't already exist
• Error handling
• Practical corner cases and workarounds of various types, e.g.
  • #[path], #[link_args]?

There's some overlap here with the current tutorial, which I think is good, since I want to find new homes for most of the content there.

[Manishearth]

I think most Rust newbies go through a phase where they're fighting with the compiler (when it comes to pointers, lifetimes, etc). If we can have a practical guide that smoothens out this phase, that would be pretty nice :)

[chridou]

It should also present practical cases, where (sample(?)) Rust concepts are combined, like pattern matching nested enums with references(and mutability, ref keyword).

Or how to design functions that take mutable arguments and immutable ones. As a beginner it took some time to figure out why I can't pass something mutable to something that requires something immutable since at first one might thing: Well, it doesn't get modified, so it should work...

In most cases you are able to find a simple example, but when combining them one gets beaten up by the compiler. This is just my experience as a newbie.

In summary, I think the common(or just in my case) newbie problem is, that you make assumptions that are simply not true when starting with Rust.

BTW, I am willing to help, in case you need some "Newbie-Perspective".

Ah, another thing: Take care of those who come from VM-Lamguages like C# and Java....

[kud1ing]

I am quite impatient and my sparetime is limited. That's why i like the format of https://gobyexample.com/
It does not force you into the lengthy linear flow of a full tutorial, but allows you to cherry-pick the interesting bits.

Also this format may allow us to fold tutorial and FAQ/Recipes into one.

[chridou]

@kud1ing
That's something rust definetely needs, too. I just had a quick look at it, but I think it doesn't "put things together".
That "gobyexample" is something that should be linked from the tutorial and api docs, I think.

[brson]

Go by Example is cool indeed, and I'd be happy to have something similar in the main repo. I remember when it was publicized a few months ago several people started an equivalent for Rust.

[adrientetar]

I can give up rust-tuts if it's of any use (unless @steveklabnik, @cmr or @spicyj disagree).

cc @plaindocs

[kud1ing]

Does https://github.com/japaric/rust-by-example fulfill this issue?

[thehydroimpulse]

@kud1ing It shows you code examples, not how to get up and going with Rust. I'd imagine such a "Practical Rust Guide" would get you from 0 to hero.

[kud1ing]

@thehydroimpulse Isn't this covered by http://static.rust-lang.org/doc/master/tutorial.html#getting-started ?

If not, could it be added to "Rust by example"?

[thehydroimpulse]

@kud1ing That really only covers the first bullet above. There's still a lack of docs on how to setup a Rust project from scratch. Right now people are basically just going to ask on IRC or figure it out themselves.

[kud1ing]

On one hand we have the longer tutorial plus manual plus special topic guides.
On the other hand we have the cherry-picking "Rust by example" where people can drive their own pace or just compare Rust aspects with other programming languages.

What is the scope of this issue exactly? Writing a new document that does what better?
Being more complete than the longer tutorials or being finer grained than "Rust by example"?
Why not add to the existing documentation forms?

[thehydroimpulse]

@kud1ing Well, this is for official documentation, which rust by examples is not. Also, rust by examples only show examples for different elements in the language, it's not really documentation, just some sugar to give you a fuller picture on how to do X.

I believe this issue is describing exactly what's listed in the bullets above. Many of which are not currently covered by the tutorial.

[kud1ing]

rust by examples only show examples for different elements in the language

I also shows how to run rustc, which is an item in the list above.

I believe this issue is describing exactly what's listed in the bullets above.

I think there are some implicite assumptions here, that should be made explicite. For example: the scope, the form, what makes something "real documentation" vs "sugar", why this needs to be a completely new format and can not be integrated in the existing documentation forms. I don't see this motivated in the bullet list.

My experience is that a task must be well-defined and understood first, otherwise the solution will not be optimal.

[thehydroimpulse]

@kud1ing I'm assuming this practical walkthrough would be just another guide. So there isn't any new "forms" being created.

I'd describe "real documentation" as something crucial. Something that can be depended upon and referenced. The latter two things are mainly for official documentation.

Sugar would be defined as "not really needed but helpful". Things like more elaborate examples on certain aspects of Rust would be such a thing.

In terms of a practical guide, it would be a place where people who have perhaps learned some basics and want to know how to do things. Like how to begin a new Rust project, file/folder conventions, using other libraries, etc... (all the stuff in that list)

The tutorial is more for a breakdown of the specific Rust features, constructs, etc... explained one-by-one. That doesn't help you organize a new project.

Does that make sense?

[thestinger]

Rust really doesn't mandate any specific file/folder structure. There's no right way to do it and the language doesn't have an opinion on it.

[richo]

Except insofar as mod.rs and lib.rs which are specialcased, no?

[steveklabnik]

This will be called "the tutorial" ;)