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 itself makes
  16 no specific demands on your editing tooling, or where your code lives. If you
  17 prefer an IDE to the command line, you may want to check out
  18 [SolidOak][solidoak], or wherever plugins are for your favorite IDE. There are
  19 a number of extensions of varying quality in development by the community. The
  20 Rust team also ships [plugins for various editors][plugins]. Configuring your
  21 editor or IDE is out of the scope of this tutorial, so check the documentation
  22 for your 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 you’re on Windows and not using PowerShell, the `~` may not work. Consult
  37 the documentation for your 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 you’re using more than one word in your
  41 filename, use an underscore: `hello_world.rs` rather than `helloworld.rs`.
  42
  43 Now that you’ve got your 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 your 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
  76 style to put the opening curly brace on the same line as the function
  77 declaration, 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 [sample configurations for various
  89 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 [macro][macro],
  94 which is how metaprogramming is done in Rust. If it were a function instead, it
  95 would look like this: `println()`. For our purposes, we don’t need to worry
  96 about this difference. Just know that sometimes, you’ll see a `!`, and that
  97 means that you’re calling a macro instead of a normal function. Rust implements
  98 `println!` as a macro rather than a function for good reasons, but that's an
  99 advanced topic. One last thing to mention: Rust’s macros are significantly
 100 different from C macros, if you’ve used those. Don’t be scared of using macros.
 101 We’ll get to the details eventually, you’ll just have to trust us for now.
 102
 103 [macro]: macros.html
 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. If you want to read further about allocation, check out
 108 [the stack and the heap][allocation], but you don’t need to right now if you
 109 don’t want to. We pass this string as an argument to `println!`, which prints the
 110 string to the screen. Easy enough!
 111
 112 [allocation]: the-stack-and-the-heap.html
 113
 114 Finally, the line ends with a semicolon (`;`). Rust is an [‘expression oriented’
 115 language][expression-oriented language], which means that most things are
 116 expressions, rather than statements. The `;` is used to indicate that this
 117 expression is over, and the next one is ready to begin. Most lines of Rust code
 118 end with a `;`.
 119
 120 [expression-oriented language]: glossary.html#expression-oriented-language
 121
 122 Finally, actually compiling and running our program. We can compile with our
 123 compiler, `rustc`, by passing it the name of our source file:
 124
 125 ```bash
 126 $ rustc main.rs
 127 ```
 128
 129 This is similar to `gcc` or `clang`, if you come from a C or C++ background. Rust
 130 will output a binary executable. You can see it with `ls`:
 131
 132 ```bash
 133 $ ls
 134 main  main.rs
 135 ```
 136
 137 Or on Windows:
 138
 139 ```bash
 140 $ dir
 141 main.exe  main.rs
 142 ```
 143
 144 There are now two files: our source code, with the `.rs` extension, and the
 145 executable (`main.exe` on Windows, `main` everywhere else)
 146
 147 ```bash
 148 $ ./main  # or main.exe on Windows
 149 ```
 150
 151 This prints out our `Hello, world!` text to our terminal.
 152
 153 If you come from a dynamic language like Ruby, Python, or JavaScript,
 154 you may not be used to these two steps being separate. Rust is an
 155 ‘ahead-of-time compiled language’, which means that you can compile a program,
 156 give it to someone else, and they don't need to have Rust installed. If you
 157 give someone a `.rb` or `.py` or `.js` file, they need to have a
 158 Ruby/Python/JavaScript implementation installed, but you just need one command
 159 to both compile and run your program. Everything is a tradeoff in language
 160 design, and Rust has made its choice.
 161
 162 Congratulations! You have officially written a Rust program. That makes you a
 163 Rust programmer! Welcome. 🎊🎉👍
 164
 165 Next, I'd like to introduce you to another tool, Cargo, which is used to write
 166 real-world Rust programs. Just using `rustc` is nice for simple things, but as
 167 your project grows, you'll want something to help you manage all of the options
 168 that it has, and to make it easy to share your code with other people and
 169 projects.