]> git.proxmox.com Git - rustc.git/blob - src/doc/book/src/ch01-02-hello-world.md
New upstream version 1.63.0+dfsg1
[rustc.git] / src / doc / book / src / ch01-02-hello-world.md
1 ## Hello, World!
2
3 Now that you’ve installed Rust, let’s write your first Rust program. It’s
4 traditional when learning a new language to write a little program that prints
5 the text `Hello, world!` to the screen, so we’ll do the same here!
6
7 > Note: This book assumes basic familiarity with the command line. Rust makes
8 > no specific demands about your editing or tooling or where your code lives, so
9 > if you prefer to use an integrated development environment (IDE) instead of
10 > the command line, feel free to use your favorite IDE. Many IDEs now have some
11 > degree of Rust support; check the IDE’s documentation for details. Recently,
12 > the Rust team has been focusing on enabling great IDE support, and progress
13 > has been made rapidly on that front!
14
15 ### Creating a Project Directory
16
17 You’ll start by making a directory to store your Rust code. It doesn’t matter
18 to Rust where your code lives, but for the exercises and projects in this book,
19 we suggest making a *projects* directory in your home directory and keeping all
20 your projects there.
21
22 Open a terminal and enter the following commands to make a *projects* directory
23 and a directory for the “Hello, world!” project within the *projects* directory.
24
25 For Linux, macOS, and PowerShell on Windows, enter this:
26
27 ```console
28 $ mkdir ~/projects
29 $ cd ~/projects
30 $ mkdir hello_world
31 $ cd hello_world
32 ```
33
34 For Windows CMD, enter this:
35
36 ```cmd
37 > mkdir "%USERPROFILE%\projects"
38 > cd /d "%USERPROFILE%\projects"
39 > mkdir hello_world
40 > cd hello_world
41 ```
42
43 ### Writing and Running a Rust Program
44
45 Next, make a new source file and call it *main.rs*. Rust files always end with
46 the *.rs* extension. If you’re using more than one word in your filename, the
47 convention is to use an underscore to separate them. For example, use
48 *hello_world.rs* rather than *helloworld.rs*.
49
50 Now open the *main.rs* file you just created and enter the code in Listing 1-1.
51
52 <span class="filename">Filename: main.rs</span>
53
54 ```rust
55 fn main() {
56 println!("Hello, world!");
57 }
58 ```
59
60 <span class="caption">Listing 1-1: A program that prints `Hello, world!`</span>
61
62 Save the file and go back to your terminal window in the
63 *~/projects/hello_world* directory. On Linux or macOS, enter the following
64 commands to compile and run the file:
65
66 ```console
67 $ rustc main.rs
68 $ ./main
69 Hello, world!
70 ```
71
72 On Windows, enter the command `.\main.exe` instead of `./main`:
73
74 ```powershell
75 > rustc main.rs
76 > .\main.exe
77 Hello, world!
78 ```
79
80 Regardless of your operating system, the string `Hello, world!` should print to
81 the terminal. If you don’t see this output, refer back to the
82 [“Troubleshooting”][troubleshooting]<!-- ignore --> part of the Installation
83 section for ways to get help.
84
85 If `Hello, world!` did print, congratulations! You’ve officially written a Rust
86 program. That makes you a Rust programmer—welcome!
87
88 ### Anatomy of a Rust Program
89
90 Let’s review this “Hello, world!” program in detail. Here’s the first piece of
91 the puzzle:
92
93 ```rust
94 fn main() {
95
96 }
97 ```
98
99 These lines define a function named `main`. The `main` function is special: it
100 is always the first code that runs in every executable Rust program. Here, the
101 first line declares a function named `main` that has no parameters and returns
102 nothing. If there were parameters, they would go inside the parentheses `()`.
103
104 The function body is wrapped in `{}`. Rust requires curly brackets around all
105 function bodies. It’s good style to place the opening curly bracket on the same
106 line as the function declaration, adding one space in between.
107
108 > Note: If you want to stick to a standard style across Rust projects, you can
109 > use an automatic formatter tool called `rustfmt` to format your code in a
110 > particular style (more on `rustfmt` in
111 > [Appendix D][devtools]<!-- ignore -->). The Rust team has included this tool
112 > with the standard Rust distribution, like `rustc`, so it should already be
113 > installed on your computer!
114
115 The body of the the `main` function holds the following code:
116
117 ```rust
118 println!("Hello, world!");
119 ```
120
121 This line does all the work in this little program: it prints text to the
122 screen. There are four important details to notice here.
123
124 First, Rust style is to indent with four spaces, not a tab.
125
126 Second, `println!` calls a Rust macro. If it had called a function instead, it
127 would be entered as `println` (without the `!`). We’ll discuss Rust macros in
128 more detail in Chapter 19. For now, you just need to know that using a `!`
129 means that you’re calling a macro instead of a normal function, and that macros
130 don’t always follow the same rules as functions.
131
132 Third, you see the `"Hello, world!"` string. We pass this string as an argument
133 to `println!`, and the string is printed to the screen.
134
135 Fourth, we end the line with a semicolon (`;`), which indicates that this
136 expression is over and the next one is ready to begin. Most lines of Rust code
137 end with a semicolon.
138
139 ### Compiling and Running Are Separate Steps
140
141 You’ve just run a newly created program, so let’s examine each step in the
142 process.
143
144 Before running a Rust program, you must compile it using the Rust compiler by
145 entering the `rustc` command and passing it the name of your source file, like
146 this:
147
148 ```console
149 $ rustc main.rs
150 ```
151
152 If you have a C or C++ background, you’ll notice that this is similar to `gcc`
153 or `clang`. After compiling successfully, Rust outputs a binary executable.
154
155 On Linux, macOS, and PowerShell on Windows, you can see the executable by
156 entering the `ls` command in your shell. On Linux and macOS, you’ll see two
157 files. With PowerShell on Windows, you’ll see the same three files that you
158 would see using CMD.
159
160 ```console
161 $ ls
162 main main.rs
163 ```
164
165 With CMD on Windows, you would enter the following:
166
167 ```cmd
168 > dir /B %= the /B option says to only show the file names =%
169 main.exe
170 main.pdb
171 main.rs
172 ```
173
174 This shows the source code file with the *.rs* extension, the executable file
175 (*main.exe* on Windows, but *main* on all other platforms), and, when using
176 Windows, a file containing debugging information with the *.pdb* extension.
177 From here, you run the *main* or *main.exe* file, like this:
178
179 ```console
180 $ ./main # or .\main.exe on Windows
181 ```
182
183 If your *main.rs* is your “Hello, world!” program, this line prints `Hello,
184 world!` to your terminal.
185
186 If you’re more familiar with a dynamic language, such as Ruby, Python, or
187 JavaScript, you might not be used to compiling and running a program as
188 separate steps. Rust is an *ahead-of-time compiled* language, meaning you can
189 compile a program and give the executable to someone else, and they can run it
190 even without having Rust installed. If you give someone a *.rb*, *.py*, or
191 *.js* file, they need to have a Ruby, Python, or JavaScript implementation
192 installed (respectively). But in those languages, you only need one command to
193 compile and run your program. Everything is a trade-off in language design.
194
195 Just compiling with `rustc` is fine for simple programs, but as your project
196 grows, you’ll want to manage all the options and make it easy to share your
197 code. Next, we’ll introduce you to the Cargo tool, which will help you write
198 real-world Rust programs.
199
200 [troubleshooting]: ch01-01-installation.html#troubleshooting
201 [devtools]: appendix-04-useful-development-tools.md