diff --git a/src/doc/guide.md b/src/doc/guide.md index 59fb050556c36..280204fbc9624 100644 --- a/src/doc/guide.md +++ b/src/doc/guide.md @@ -7,4 +7,103 @@ displayed here in line with Rust's open development policy. Please open any issues you find as usual. -Coming soon. :) +## Welcome! + +Hey there! Welcome to the Rust guide. This is the place to be if you'd like to +learn how to program in Rust. Rust is a systems programming language with a +focus on "high-level, bare-metal programming": the lowest level control a +programming language can give you, but with zero-cost, higher level +abstractions, because people aren't computers. We really think Rust is +something special, and we hope you do too. + +To show you how to get going with Rust, we're going to write the traditional +"Hello, World!" program. Next, we'll introduce you to a tool that's useful for +writing real-world Rust programs and libraries: "Cargo." Then, we'll show off +Rust's features by writing a little program together. + +Sound good? Let's go! + +## Installing Rust + +The first step to using Rust is to install it! There are a number of ways to +install Rust, but the easiest is to use the the `rustup` script. If you're on +Linux or a Mac, All you need to do is this: + +```{ignore} +$ curl -s http://www.rust-lang.org/rustup.sh | sudo sh +``` + +(If you're concerned about `curl | sudo sh`, please keep reading. Disclaimer +below.) + +If you're on Windows, please [download this .exe and run +it](http://static.rust-lang.org/dist/rust-nightly-install.exe). + +If you decide you don't want Rust anymore, we'll be a bit sad, but that's okay. +Not every programming language is great for everyone. Just pass an argument to +the script: + +```{ignore} +$ curl -s http://www.rust-lang.org/rustup.sh | sudo sh -s -- --uninstall +``` + +If you used the Windows installer, just re-run the `.exe` and it will give you +an uninstall option. + +You can re-run this script any time you want to update Rust. Which, at this +point, is often. Rust is still pre-1.0, and so people assume that you're using +a very recent Rust. + +This brings me to one other point: some people, and somewhat rightfully so, get +very upset when we tell you to `curl | sudo sh`. And they should be! Basically, +when you do this, you are trusting that the good people who maintain Rust +aren't going to hack your computer and do bad things. That's a good instinct! +If you're one of those people, please check out the documentation on [building +Rust from Source](https://github.com/rust-lang/rust#building-from-source), or +[the official binary downloads](http://www.rust-lang.org/install.html). And we +promise that this method will not be the way to install Rust forever: it's just +the easiest way to keep people updated while Rust is in its alpha state. + +Oh, we should also mention the officially supported platforms: + +* Windows (7, 8, Server 2008 R2), x86 only +* Linux (2.6.18 or later, various distributions), x86 and x86-64 +* OSX 10.7 (Lion) or greater, x86 and x86-64 + +We extensively test Rust on these platforms, and a few others, too, like +Android. But these are the ones most likely to work, as they have the most +testing. + +Finally, a comment about Windows. Rust considers Windows to be a first-class +platform upon release, but if we're honest, the Windows experience isn't as +integrated as the Linux/OS X experience is. We're working on it! If anything +does not work, it is a bug. Please let us know if that happens. Each and every +commit is tested against Windows just like any other platform. + +If you've got Rust installed, you can open up a shell, and type this: + +```{ignore} +$ rustc --version +``` + +You should see some output that looks something like this: + +```{ignore} +rustc 0.11.0-pre (443a1cd 2014-06-08 14:56:52 -0700) +host: x86_64-unknown-linux-gnu +``` + +If you did, Rust has been installed successfully! Congrats! + +If not, there are a number of places where you can get help. The easiest is +IRC, which you can access +[here](http://chat.mibbit.com/?server=irc.mozilla.org&channel=%23rust). Click +that link, and you'll be chatting with other Rustaceans (a silly nickname we +call ourselves), and we can help you out. Other great resources include our +[mailing list](https://mail.mozilla.org/listinfo/rust-dev), +[subreddit](http://www.reddit.com/r/rust), and +[StackOverflow](http://stackoverflow.com/questions/tagged/rust). + +## Hello, world! + +## Hello, Cargo!