src/doc/trpl/hello-world.md

   1 % Hello, world!
   2
   3 Now that you have Rust installed, let's write your first Rust program. It's
   4 traditional to make your first program in any new language one that prints the
   5 text "Hello, world!" to the screen. The nice thing about starting with such a
   6 simple program is that you can verify that your compiler isn't just installed,
   7 but also working properly. And printing information to the screen is a pretty
   8 common thing to do.
   9
  10 The first thing that we need to do is make a file to put our code in. I like
  11 to make a `projects` directory in my home directory, and keep all my projects
  12 there. Rust does not care where your code lives.
  13
  14 This actually leads to one other concern we should address: this guide will
  15 assume that you have basic familiarity with the command line. Rust does not
  16 require that you know a whole ton about the command line, but until the
  17 language is in a more finished state, IDE support is spotty. Rust makes no
  18 specific demands on your editing tooling, or where your code lives.
  19
  20 With that said, let's make a directory in our projects directory.
  21
  22 ```{bash}
  23 $ mkdir ~/projects
  24 $ cd ~/projects
  25 $ mkdir hello_world
  26 $ cd hello_world
  27 ```
  28
  29 If you're on Windows and not using PowerShell, the `~` may not work. Consult
  30 the documentation for your shell for more details.
  31
  32 Let's make a new source file next. I'm going to use the syntax `editor
  33 filename` to represent editing a file in these examples, but you should use
  34 whatever method you want. We'll call our file `main.rs`:
  35
  36 ```{bash}
  37 $ editor main.rs
  38 ```
  39
  40 Rust files always end in a `.rs` extension. If you're using more than one word
  41 in your filename, use an underscore. `hello_world.rs` rather than
  42 `helloworld.rs`.
  43
  44 Now that you've got your file open, type this in:
  45
  46 ```{rust}
  47 fn main() {
  48     println!("Hello, world!");
  49 }
  50 ```
  51
  52 Save the file, and then type this into your terminal window:
  53
  54 ```{bash}
  55 $ rustc main.rs
  56 $ ./main # or main.exe on Windows
  57 Hello, world!
  58 ```
  59
  60 You can also run these examples on [play.rust-lang.org](http://play.rust-lang.org/) by clicking on the arrow that appears in the upper right of the example when you mouse over the code.
  61
  62 Success! Let's go over what just happened in detail.
  63
  64 ```{rust}
  65 fn main() {
  66
  67 }
  68 ```
  69
  70 These lines define a *function* in Rust. The `main` function is special:
  71 it's the beginning of every Rust program. The first line says "I'm declaring a
  72 function named `main`, which takes no arguments and returns nothing." If there
  73 were arguments, they would go inside the parentheses (`(` and `)`), and because
  74 we aren't returning anything from this function, we can omit the return type
  75 entirely. We'll get to it later.
  76
  77 You'll also note that the function is wrapped in curly braces (`{` and `}`).
  78 Rust requires these around all function bodies. It is also considered good
  79 style to put the opening curly brace on the same line as the function
  80 declaration, with one space in between.
  81
  82 Next up is this line:
  83
  84 ```{rust}
  85     println!("Hello, world!");
  86 ```
  87
  88 This line does all of the work in our little program. There are a number of
  89 details that are important here. The first is that it's indented with four
  90 spaces, not tabs. Please configure your editor of choice to insert four spaces
  91 with the tab key. We provide some [sample configurations for various
  92 editors](https://github.com/rust-lang/rust/tree/master/src/etc).
  93
  94 The second point is the `println!()` part. This is calling a Rust *macro*,
  95 which is how metaprogramming is done in Rust. If it were a function instead, it
  96 would look like this: `println()`. For our purposes, we don't need to worry
  97 about this difference. Just know that sometimes, you'll see a `!`, and that
  98 means that you're calling a macro instead of a normal function. Rust implements
  99 `println!` as a macro rather than a function for good reasons, but that's a
 100 very advanced topic. You'll learn more when we talk about macros later. One
 101 last thing to mention: Rust's macros are significantly different from C macros,
 102 if you've used those. Don't be scared of using macros. We'll get to the details
 103 eventually, you'll just have to trust us for now.
 104
 105 Next, `"Hello, world!"` is a *string*. Strings are a surprisingly complicated
 106 topic in a systems programming language, and this is a *statically allocated*
 107 string. We will talk more about different kinds of allocation later. We pass
 108 this string as an argument to `println!`, which prints the string to the
 109 screen. Easy enough!
 110
 111 Finally, the line ends with a semicolon (`;`). Rust is an *expression
 112 oriented* language, which means that most things are expressions. The `;` is
 113 used to indicate that this expression is over, and the next one is ready to
 114 begin. Most lines of Rust code end with a `;`. We will cover this in-depth
 115 later in the guide.
 116
 117 Finally, actually *compiling* and *running* our program. We can compile
 118 with our compiler, `rustc`, by passing it the name of our source file:
 119
 120 ```{bash}
 121 $ rustc main.rs
 122 ```
 123
 124 This is similar to `gcc` or `clang`, if you come from a C or C++ background. Rust
 125 will output a binary executable. You can see it with `ls`:
 126
 127 ```{bash}
 128 $ ls
 129 main  main.rs
 130 ```
 131
 132 Or on Windows:
 133
 134 ```{bash}
 135 $ dir
 136 main.exe  main.rs
 137 ```
 138
 139 There are now two files: our source code, with the `.rs` extension, and the
 140 executable (`main.exe` on Windows, `main` everywhere else)
 141
 142 ```{bash}
 143 $ ./main  # or main.exe on Windows
 144 ```
 145
 146 This prints out our `Hello, world!` text to our terminal.
 147
 148 If you come from a dynamically typed language like Ruby, Python, or JavaScript,
 149 you may not be used to these two steps being separate. Rust is an
 150 *ahead-of-time compiled language*, which means that you can compile a
 151 program, give it to someone else, and they don't need to have Rust installed.
 152 If you give someone a `.rb` or `.py` or `.js` file, they need to have
 153 Ruby/Python/JavaScript installed, but you just need one command to both compile
 154 and run your program. Everything is a tradeoff in language design, and Rust has
 155 made its choice.
 156
 157 Congratulations! You have officially written a Rust program. That makes you a
 158 Rust programmer! Welcome.
 159
 160 Next, I'd like to introduce you to another tool, Cargo, which is used to write
 161 real-world Rust programs. Just using `rustc` is nice for simple things, but as
 162 your project grows, you'll want something to help you manage all of the options
 163 that it has, and to make it easy to share your code with other people and
 164 projects.