src/doc/trpl/hello-world.md

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