Skip to content

Commit 389fae2

Browse files
committed
auto merge of #15181 : steveklabnik/rust/hello_world, r=brson
This is built on top of #15162 . steveklabnik@cccae83 is the only new commit, you may want to look at that rather than the whole diff. Writing our first Rust program together. This is the most crucial step, so I go to a fairly deep level of detail. Future sections will move more quickly.
2 parents 99519cc + cccae83 commit 389fae2

File tree

1 file changed

+180
-0
lines changed

1 file changed

+180
-0
lines changed

src/doc/guide.md

+180
Original file line numberDiff line numberDiff line change
@@ -106,4 +106,184 @@ call ourselves), and we can help you out. Other great resources include our
106106

107107
## Hello, world!
108108

109+
Now that you have Rust installed, let's write your first Rust program. It's
110+
traditional to make your first program in any new language one that prints the
111+
text "Hello, world!" to the screen. The nice thing about starting with such a
112+
simple program is that you can verify that your compiler isn't just installed,
113+
but also working properly. And printing information to the screen is a pretty
114+
common thing to do.
115+
116+
The first thing that we need to do is make a file to put our code in. I like
117+
to make a projects directory in my home directory, and keep all my projects
118+
there. Rust does not care where your code lives.
119+
120+
This actually leads to one other concern we should address: this tutorial will
121+
assume that you have basic familiarity with the command-line. Rust does not
122+
require that you know a whole ton about the command line, but until the
123+
language is in a more finished state, IDE support is spotty. Rust makes no
124+
specific demands on your editing tooling, or where your code lives.
125+
126+
With that said, let's make a directory in our projects directory. Note that you
127+
don't need to type in the `$`s, they just indicate the start of each command:
128+
129+
```{bash}
130+
$ mkdir ~/projects
131+
$ cd ~/projects
132+
$ mkdir hello_world
133+
$ cd hello_world
134+
```
135+
136+
If you're on Windows and not using PowerShell, the `~` may not work. Consult
137+
the documentation for your shell for more details.
138+
139+
Let's make a new source file next. I'm going to use the syntax `editor
140+
filename` to represent editing a file in these examples, but you should use
141+
whatever method you want. We'll call our file `hello_world.rs`:
142+
143+
```{bash}
144+
$ editor hello_world.rs
145+
```
146+
147+
Rust files always end in a `.rs` extension. If you're using more than one word
148+
in your file name, use an underscore. `hello_world.rs` versus `goodbye.rs`.
149+
150+
Now that you've got your file open, type this in:
151+
152+
```
153+
fn main() {
154+
println!("Hello, world");
155+
}
156+
```
157+
158+
Save the file, and then type this into your terminal window:
159+
160+
```{bash}
161+
$ rustc hello_world.rs
162+
$ ./hello_world # on Windows, this is ./hello_world.exe
163+
Hello, world
164+
```
165+
166+
Success! Let's go over what just happened in detail.
167+
168+
```
169+
fn main() {
170+
171+
}
172+
```
173+
174+
These two lines define a **function** in Rust. The `main` function is special:
175+
it's the beginning of every Rust program. The first line says "I'm declaring a
176+
function named `main`, which takes no arguments and returns nothing." If there
177+
were arguments, they would go inside the parentheses (`(` and `)`), and because
178+
we aren't returning anything from this function, we've dropped that notation
179+
entirely. We'll get to it later.
180+
181+
You'll also note that the function is wrapped in curly braces (`{` and `}`).
182+
Rust requires these around all function bodies. It is also considered good
183+
style to put the curly brace on the same line as the function declaration, with
184+
one space in between.
185+
186+
Next up is this line:
187+
188+
```
189+
println!("Hello, world");
190+
```
191+
192+
This line does all of the work in our little program. There are a number of
193+
details that are important here. The first is that it's indented with four
194+
spaces, not tabs. Please configure your editor of choice to insert four spaces
195+
with the tab key. We provide some sample configurations for various editors
196+
[here](https://github.com/rust-lang/rust/tree/master/src/etc).
197+
198+
The second point is the `println!()` part. This is calling a Rust **macro**,
199+
which is how metaprogramming is done in Rust. If it were a function instead, it
200+
would look like this: `println()`. For our purposes, we don't need to worry
201+
about this difference. Just know that sometimes, you'll see a `!`, and that
202+
means that you're calling a macro instead of a normal function.
203+
204+
Next, `"Hello, world"` is a **string**. Strings are a surprisingly
205+
complicated topic in a systems programming language, and this is a **staticly
206+
allocated** string. We will talk more about different kinds of allocation
207+
later. We pass this string as an argument to `println!`, which prints the
208+
string to the screen. Easy enough!
209+
210+
Finally, the line ends with a semicolon (`;`). Rust is an **expression
211+
oriented** language, which means that most things are expressions. The `;` is
212+
used to indicate that this expression is over, and the next one is ready to
213+
begin. Most lines of Rust code end with a `;`. We will cover this in-depth
214+
later in the tutorial.
215+
216+
Finally, actually **compiling** and **running** our program. We can compile
217+
with our compiler, `rustc`, by passing it the name of our source file:
218+
219+
```{bash}
220+
$ rustc hello_world.rs
221+
```
222+
223+
This is similar to `gcc` or `clang`, if you come from a C or C++ background. Rust
224+
will output a binary executable. You can see it with `ls`:
225+
226+
```{bash}
227+
$ ls
228+
hello_world hello_world.rs
229+
```
230+
231+
Or on Windows:
232+
233+
```{bash}
234+
$ dir
235+
hello_world.exe hello_world.rs
236+
```
237+
238+
There are now two files: our source code, with the `.rs`, and the executable.
239+
We ran the executable like this:
240+
241+
```{bash}
242+
$ ./hello_world # or ./hello_world.exe on Windows
243+
```
244+
245+
This prints out our `Hello, world!` text to our terminal.
246+
247+
If you come from a dynamically typed language like Ruby, Python, or JavaScript,
248+
you may not be used to these two steps being separate. Rust is an
249+
**ahead-of-time compiled language**, which means that you can compile a
250+
program, give it to someone else, and they don't need to have Rust installed.
251+
If you give someone a `.rb` or `.py` or `.js` file, they need to have
252+
Ruby/Python/JavaScript installed, but you just need one command to both compile
253+
and run your program. Everything is a tradeoff in language design, and Rust has
254+
made its choice.
255+
256+
Congratulations! You have officially written a Rust program. That makes you a
257+
Rust programmer! Welcome.
258+
259+
Next, I'd like to introduce you to another tool, Cargo, which is used to write
260+
real-world Rust programs. Just using `rustc` is nice for simple things, but as
261+
your project grows, you'll want something to help you manage all of the options
262+
that it has, and to make it easy to share your code with other people and
263+
projects.
264+
109265
## Hello, Cargo!
266+
267+
268+
269+
270+
271+
272+
273+
274+
275+
276+
277+
278+
279+
280+
281+
282+
283+
284+
285+
286+
287+
288+
289+

0 commit comments

Comments
 (0)