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