Add Steve Klabnik's 'A 30-minute Introduction to Rust'

[brson]

This is intended to be the first thing somebody new to the language reads about Rust. It is supposed to be simple and intriguing, to give the user an idea of whether Rust is appropriate for them, and to hint that there's a lot of cool stuff to learn if they just keep diving deeper.

I'm particularly happy with the sequence of concurrency examples.

[brson]

cc @steveklabnik

[brson]

Some things I don't love:

• that the first code example is C++ is kinda bad; better to show Rust in a Rust tutorial
• the first para of 'owning concurrency', starting with 'concurrency is an incredibly hot topic ..' is weak

[brson]

I took a big liberty changing RWLocks to Mutex, thinking Mutexes are probably more common. This way may not be better though.

[brson]

The diff leaves a lot to be desired. I'll add linebreaks to the md.

[brson]

also thank you @stevekbl

[brson]

-kblnik

[steveklabnik]

Haha!

I also agree that the C++ example could be better.

[thestinger]

I think it should be done in unsafe Rust rather than C or C++. It can mention that this is a problem in most other languages with the same control over memory allocation but I don't think we should compare to specific other languages. It's only going to inspire a lot of bickering about whether or not the examples really reflect how modern C++ is written, etc.

[thestinger]

FWIW, I had originally written some unsafe examples for the tutorial leading up to the demonstration of the safe Rust features replacing them. I thought this was a great way of doing it, but there was a lot of complaining about the unsafe examples requiring low-level knowledge to understand (even though that's kind of the point) and they were removed... I still think it's a great way of leading up to the introduction of features like lifetimes, destructors and move semantics though.

[steveklabnik]

I agree that in general, we should stay Rust only, but this is a special case.

[thestinger]

What's the advantage of using C instead of unsafe Rust?

[steveklabnik]

I think that "You've used systems languages, here are their pitfalls. Now see how Rust fixes that!" is significantly better than "Here's the bad way of writing Rust. Now here's good Rust!"

The audience of this piece are C and C++ programmers who have heard something about Rust, and want to see if it makes sense for them. Directly comparing against what they currently use is a great way to demonstrate the value of Rust.

[thestinger]

I don't think the generic documentation should be targeted specifically at C programmers. It makes sense to have documentation aimed at specific groups of people, but not as the general introduction to the language. It also needs to cater to the audience it's aimed at.

The documentation comparing against C and C++ would need to be quite different, because raw pointers in C++ are viewed in a similar light to how we view unsafe. It needs to explain how Rust improves on move semantics, destructors and references. It doesn't improve on C++ smart pointers beyond having safe move semantics and the ability to mark data as task-local - but for C programmers, this is a new concept and a huge step up.

[thestinger]

IMO, pretending that C and C++ are in the same situation is only going to drive away C++ programmers before they give the language a chance. They'll just assume it's solving the same problems as C++ with the same mechanisms and lose interest. Rust has an unsafe subset that's nearly identical to C too, but yet we don't talk about it as having those problems.

[steveklabnik]

I, too, dislike "C/C++": you're right that they're very, very different. That's why I'd been saying C++. I'm not opposed to making the example in C as opposed to C++.

[bill-myers]

Well, the first thing one often wants to see when learning about a new language is a simple working program ("how does the language look?"), and ideally one they can copy&paste to start writing their own program ("how do I start using it?").

I think a simple version of the Unix "sort" utility (shows how to read and write files, and how to store stuff in a vector and sort it), and a HTTP server returning the current time in response to GET /time (shows how to write a web service, how to get the time, how to format strings) could be suitable for it.

Then, one can start with the "why should I use it?" (which the user may already know, since that might be why he started looking at the language in the first place).

[brson]

I've reformatted the markdown for editing, so now you can see the real diff.

[brson]

I don't want to get too much in the weeds on the issue of the C++ example. It's not an unreasonable way to introduce Rust, though if we can find a better way to begin then great.

[liigo]

I like this.

2014-04-10 8:33 GMT+08:00 bill-myers notifications@github.com:

Well, the first thing one often wants to see when learning about a new
language is a simple working program ("how does the language look?"), and
ideally one they can copy&paste to start writing their own program ("how do
I start using it?").

I think a simple version of the Unix "sort" utility (shows how to read and
write files, and how to store stuff in a vector and sort it), and a HTTP
server returning the current time in response to GET /time (shows how to
write a web service, how to get the time, how to format strings) could be
suitable for it.

Then, one can start with the "why should I use it?" (which the user may
already know, since that might be why he started looking at the language in
the first palec).

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/13416#issuecomment-40032137
.

by Liigo, http://blog.csdn.net/liigo/
Google+ https://plus.google.com/105597640837742873343/

[huonw]

I don't want to get too much in the weeds on the issue of the C++ example. It's not an unreasonable way to introduce Rust, though if we can find a better way to begin then great.

Another problem with C++ is it's hard to get an example with a problem that can be easily explained to non-C++ users, but is also convincing to C++ users.

Anything too simplistic is basically a strawman, and will cause ridicule/questioning from experienced C++-ers (and did; a while ago someone sent an email to the mailing list).

Anything too complicated is probably pointless, it's just wasted space for people who don't know C++ (or it would require inflating the document with a detailed explanation about the problem(s) in the C++, wasting the "30 minute" time budget on things that are not Rust).

On C++ specifically, there's the Rust for C++ programmers guide, which could be "upgraded" to include a little on how Rust addresses some common memory-safety problems in C++ (and moved in tree: #12100. I would do this myself, but I don't think I know enough C++ to update it effectively).

[steveklabnik]

I will also say that this is (from my own metrics) far and away the most popular thing about Rust I've ever written.

[brson]

I should have sold this better in the OP.

This is an excellent piece of introductory writing about Rust that is simple and intriguing, with a goal of giving the new user an idea of whether Rust is appropriate to them. It hints that there's a lot of cool stuff to learn if they just keep diving deeper. I'm particularly happy with the sequence of concurrency examples.

There may be improvements to be made yet, and we can do that later, but this is a great start.

Here's what I'm planning to do with Rust's introductory documentation:

• Add this intro doc. Update website to link to it.
• Write a new tutorial that explains the core concepts of Rust. This is what @plaindocs, @nikomatsakis and myself are working on.
• Find new locations for the material in the current tutorial, in the manual or other guides.
• Consider whether we are still missing a 'practical' tutorial on how to write real software in Rust.

[steveklabnik]

👍 😍

[huonw]

I'm in favour of landing this as is, although maybe a disclaimer about the C++ examples wouldn't go amiss (even just "these examples are a work-in-progress & are known to not be idiomatic C++" or something, to try to avoid people getting upset about them... although maybe this will just attract attention and have the opposite effect).

[adrientetar]

read this first is probably unnecessary since a/ it's the first thing in the list b/ it is named "intro".

[brson]

Addressed @adrientetar and @huonw's comments in followup.

[steveklabnik]

😍