Guide: Hello, world!

Let's write our first Rust program!

Author: steveklabnik

src/doc/guide.md

@@ -106,4 +106,184 @@ call ourselves), and we can help you out. Other great resources include our
 
 ## Hello, world!
 
+Now that you have Rust installed, let's write your first Rust program. It's
+traditional to make your first program in any new language one that prints the
+text "Hello, world!" to the screen. The nice thing about starting with such a
+simple program is that you can verify that your compiler isn't just installed,
+but also working properly. And printing information to the screen is a pretty
+common thing to do.
+
+The first thing that we need to do is make a file to put our code in. I like
+to make a projects directory in my home directory, and keep all my projects
+there. Rust does not care where your code lives.
+
+This actually leads to one other concern we should address: this tutorial will
+assume that you have basic familiarity with the command-line. Rust does not
+require that you know a whole ton about the command line, but until the
+language is in a more finished state, IDE support is spotty. Rust makes no
+specific demands on your editing tooling, or where your code lives.
+
+With that said, let's make a directory in our projects directory. Note that you
+don't need to type in the `$`s, they just indicate the start of each command:
+
+```{bash}
+$ mkdir ~/projects
+$ cd ~/projects
+$ mkdir hello_world
+$ cd hello_world
+```
+
+If you're on Windows and not using PowerShell, the `~` may not work. Consult
+the documentation for your shell for more details.
+
+Let's make a new source file next. I'm going to use the syntax `editor
+filename` to represent editing a file in these examples, but you should use
+whatever method you want. We'll call our file `hello_world.rs`:
+
+```{bash}
+$ editor hello_world.rs
+```
+
+Rust files always end in a `.rs` extension. If you're using more than one word
+in your file name, use an underscore. `hello_world.rs` versus `goodbye.rs`.
+
+Now that you've got your file open, type this in:
+
+```
+fn main() {
+    println!("Hello, world");
+}
+```
+
+Save the file, and then type this into your terminal window:
+
+```{bash}
+$ rustc hello_world.rs
+$ ./hello_world  # on Windows, this is ./hello_world.exe
+Hello, world
+```
+
+Success! Let's go over what just happened in detail.
+
+```
+fn main() {
+   
+}
+```
+
+These two lines define a **function** in Rust. The `main` function is special:
+it's the beginning of every Rust program. The first line says "I'm declaring a
+function named `main`, which takes no arguments and returns nothing." If there
+were arguments, they would go inside the parentheses (`(` and `)`), and because
+we aren't returning anything from this function, we've dropped that notation
+entirely.  We'll get to it later.
+
+You'll also note that the function is wrapped in curly braces (`{` and `}`).
+Rust requires these around all function bodies. It is also considered good
+style to put the curly brace on the same line as the function declaration, with
+one space in between.
+
+Next up is this line:
+
+```
+    println!("Hello, world");
+```
+
+This line does all of the work in our little program. There are a number of
+details that are important here. The first is that it's indented with four
+spaces, not tabs. Please configure your editor of choice to insert four spaces
+with the tab key. We provide some sample configurations for various editors
+[here](https://github.com/rust-lang/rust/tree/master/src/etc).
+
+The second point is the `println!()` part. This is calling a Rust **macro**,
+which is how metaprogramming is done in Rust. If it were a function instead, it
+would look like this: `println()`. For our purposes, we don't need to worry
+about this difference. Just know that sometimes, you'll see a `!`, and that
+means that you're calling a macro instead of a normal function.
+
+Next, `"Hello, world"` is a **string**. Strings are a surprisingly
+complicated topic in a systems programming language, and this is a **staticly
+allocated** string. We will talk more about different kinds of allocation
+later. We pass this string as an argument to `println!`, which prints the
+string to the screen. Easy enough!
+
+Finally, the line ends with a semicolon (`;`). Rust is an **expression
+oriented** language, which means that most things are expressions. The `;` is
+used to indicate that this expression is over, and the next one is ready to
+begin. Most lines of Rust code end with a `;`. We will cover this in-depth
+later in the tutorial.
+
+Finally, actually **compiling** and **running** our program. We can compile
+with our compiler, `rustc`, by passing it the name of our source file:
+
+```{bash}
+$ rustc hello_world.rs
+```
+
+This is similar to `gcc` or `clang`, if you come from a C or C++ background. Rust
+will output a binary executable. You can see it with `ls`:
+
+```{bash}
+$ ls
+hello_world  hello_world.rs
+```
+
+Or on Windows:
+
+```{bash}
+$ dir
+hello_world.exe  hello_world.rs
+```
+
+There are now two files: our source code, with the `.rs`, and the executable.
+We ran the executable like this:
+
+```{bash}
+$ ./hello_world  # or ./hello_world.exe on Windows
+```
+
+This prints out our `Hello, world!` text to our terminal.
+
+If you come from a dynamically typed language like Ruby, Python, or JavaScript,
+you may not be used to these two steps being separate. Rust is an
+**ahead-of-time compiled language**, which means that you can compile a
+program, give it to someone else, and they don't need to have Rust installed.
+If you give someone a `.rb` or `.py` or `.js` file, they need to have
+Ruby/Python/JavaScript installed, but you just need one command to both compile
+and run your program. Everything is a tradeoff in language design, and Rust has
+made its choice.
+
+Congratulations! You have officially written a Rust program. That makes you a
+Rust programmer! Welcome.
+
+Next, I'd like to introduce you to another tool, Cargo, which is used to write
+real-world Rust programs. Just using `rustc` is nice for simple things, but as
+your project grows, you'll want something to help you manage all of the options
+that it has, and to make it easy to share your code with other people and
+projects.
+
 ## Hello, Cargo!
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+