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, use
  47 an underscore to separate them. For example, use *hello_world.rs* rather than
  48 *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. On Linux or macOS, enter
  63 the following commands to compile and run the file:
  64
  65 ```console
  66 $ rustc main.rs
  67 $ ./main
  68 Hello, world!
  69 ```
  70
  71 On Windows, enter the command `.\main.exe` instead of `./main`:
  72
  73 ```powershell
  74 > rustc main.rs
  75 > .\main.exe
  76 Hello, world!
  77 ```
  78
  79 Regardless of your operating system, the string `Hello, world!` should print to
  80 the terminal. If you don’t see this output, refer back to the
  81 [“Troubleshooting”][troubleshooting]<!-- ignore --> part of the Installation
  82 section for ways to get help.
  83
  84 If `Hello, world!` did print, congratulations! You’ve officially written a Rust
  85 program. That makes you a Rust programmer—welcome!
  86
  87 ### Anatomy of a Rust Program
  88
  89 Let’s review in detail what just happened in your “Hello, world!” program.
  90 Here’s the first piece of the puzzle:
  91
  92 ```rust
  93 fn main() {
  94
  95 }
  96 ```
  97
  98 These lines define a function in Rust. The `main` function is special: it is
  99 always the first code that runs in every executable Rust program. The first
 100 line declares a function named `main` that has no parameters and returns
 101 nothing. If there were parameters, they would go inside the parentheses, `()`.
 102
 103 Also, note that the function body is wrapped in curly brackets, `{}`. Rust
 104 requires these around all function bodies. It’s good style to place the opening
 105 curly bracket on the same line as the function declaration, adding one space in
 106 between.
 107
 108 If you want to stick to a standard style across Rust projects, you can use an
 109 automatic formatter tool called `rustfmt` to format your code in a particular
 110 style. The Rust team has included this tool with the standard Rust distribution,
 111 like `rustc`, so it should already be installed on your computer! Check the
 112 online documentation for more details.
 113
 114 Inside the `main` function is the following code:
 115
 116 ```rust
 117     println!("Hello, world!");
 118 ```
 119
 120 This line does all the work in this little program: it prints text to the
 121 screen. There are four important details to notice here.
 122
 123 First, Rust style is to indent with four spaces, not a tab.
 124
 125 Second, `println!` calls a Rust macro. If it called a function instead, it
 126 would be entered as `println` (without the `!`). We’ll discuss Rust macros in
 127 more detail in Chapter 19. For now, you just need to know that using a `!`
 128 means that you’re calling a macro instead of a normal function, and that macros
 129 don't always follow the same rules as functions.
 130
 131 Third, you see the `"Hello, world!"` string. We pass this string as an argument
 132 to `println!`, and the string is printed to the screen.
 133
 134 Fourth, we end the line with a semicolon (`;`), which indicates that this
 135 expression is over and the next one is ready to begin. Most lines of Rust code
 136 end with a semicolon.
 137
 138 ### Compiling and Running Are Separate Steps
 139
 140 You’ve just run a newly created program, so let’s examine each step in the
 141 process.
 142
 143 Before running a Rust program, you must compile it using the Rust compiler by
 144 entering the `rustc` command and passing it the name of your source file, like
 145 this:
 146
 147 ```console
 148 $ rustc main.rs
 149 ```
 150
 151 If you have a C or C++ background, you’ll notice that this is similar to `gcc`
 152 or `clang`. After compiling successfully, Rust outputs a binary executable.
 153
 154 On Linux, macOS, and PowerShell on Windows, you can see the executable by
 155 entering the `ls` command in your shell. On Linux and macOS, you’ll see two
 156 files. With PowerShell on Windows, you’ll see the same three files that you
 157 would see using CMD.
 158
 159 ```console
 160 $ ls
 161 main  main.rs
 162 ```
 163
 164 With CMD on Windows, you would enter the following:
 165
 166 ```cmd
 167 > dir /B %= the /B option says to only show the file names =%
 168 main.exe
 169 main.pdb
 170 main.rs
 171 ```
 172
 173 This shows the source code file with the *.rs* extension, the executable file
 174 (*main.exe* on Windows, but *main* on all other platforms), and, when using
 175 Windows, a file containing debugging information with the *.pdb* extension.
 176 From here, you run the *main* or *main.exe* file, like this:
 177
 178 ```console
 179 $ ./main # or .\main.exe on Windows
 180 ```
 181
 182 If *main.rs* was your “Hello, world!” program, this line would print `Hello,
 183 world!` to your terminal.
 184
 185 If you’re more familiar with a dynamic language, such as Ruby, Python, or
 186 JavaScript, you might not be used to compiling and running a program as
 187 separate steps. Rust is an *ahead-of-time compiled* language, meaning you can
 188 compile a program and give the executable to someone else, and they can run it
 189 even without having Rust installed. If you give someone a *.rb*, *.py*, or
 190 *.js* file, they need to have a Ruby, Python, or JavaScript implementation
 191 installed (respectively). But in those languages, you only need one command to
 192 compile and run your program. Everything is a trade-off in language design.
 193
 194 Just compiling with `rustc` is fine for simple programs, but as your project
 195 grows, you’ll want to manage all the options and make it easy to share your
 196 code. Next, we’ll introduce you to the Cargo tool, which will help you write
 197 real-world Rust programs.
 198
 199 [troubleshooting]: ch01-01-installation.html#troubleshooting