src/doc/book/src/ch01-01-installation.md

   1 ## Installation
   2
   3 The first step is to install Rust. We’ll download Rust through `rustup`, a
   4 command line tool for managing Rust versions and associated tools. You’ll need
   5 an internet connection for the download.
   6
   7 > Note: If you prefer not to use `rustup` for some reason, please see [the Rust
   8 > installation page](https://www.rust-lang.org/tools/install) for other options.
   9
  10 The following steps install the latest stable version of the Rust compiler.
  11 Rust’s stability guarantees ensure that all the examples in the book that
  12 compile will continue to compile with newer Rust versions. The output might
  13 differ slightly between versions, because Rust often improves error messages
  14 and warnings. In other words, any newer, stable version of Rust you install
  15 using these steps should work as expected with the content of this book.
  16
  17 > ### Command Line Notation
  18 >
  19 > In this chapter and throughout the book, we’ll show some commands used in the
  20 > terminal. Lines that you should enter in a terminal all start with `$`. You
  21 > don’t need to type in the `$` character; it indicates the start of each
  22 > command. Lines that don’t start with `$` typically show the output of the
  23 > previous command. Additionally, PowerShell-specific examples will use `>`
  24 > rather than `$`.
  25
  26 ### Installing `rustup` on Linux or macOS
  27
  28 If you’re using Linux or macOS, open a terminal and enter the following command:
  29
  30 ```console
  31 $ curl --proto '=https' --tlsv1.2 https://sh.rustup.rs -sSf | sh
  32 ```
  33
  34 The command downloads a script and starts the installation of the `rustup`
  35 tool, which installs the latest stable version of Rust. You might be prompted
  36 for your password. If the install is successful, the following line will appear:
  37
  38 ```text
  39 Rust is installed now. Great!
  40 ```
  41
  42 Additionally, you’ll need a linker of some kind. It’s likely one is already
  43 installed, but when you try to compile a Rust program and get errors indicating
  44 that a linker could not execute, that means a linker isn’t installed on your
  45 system and you’ll need to install one manually. C compilers usually come with
  46 the correct linker. Check your platform’s documentation for how to install a C
  47 compiler. Also, some common Rust packages depend on C code and will need a C
  48 compiler. Therefore, it might be worth installing one now.
  49
  50 ### Installing `rustup` on Windows
  51
  52 On Windows, go to [https://www.rust-lang.org/tools/install][install] and follow
  53 the instructions for installing Rust. At some point in the installation, you’ll
  54 receive a message explaining that you’ll also need the C++ build tools for
  55 Visual Studio 2013 or later. The easiest way to acquire the build tools is to
  56 install [Build Tools for Visual Studio 2019][visualstudio]. When asked which
  57 workloads to install make sure "C++ build tools" is selected and that the
  58 Windows 10 SDK and the English language pack components are included.
  59
  60 [install]: https://www.rust-lang.org/tools/install
  61 [visualstudio]: https://visualstudio.microsoft.com/visual-cpp-build-tools/
  62
  63 The rest of this book uses commands that work in both *cmd.exe* and PowerShell.
  64 If there are specific differences, we’ll explain which to use.
  65
  66 ### Updating and Uninstalling
  67
  68 After you’ve installed Rust via `rustup`, updating to the latest version is
  69 easy. From your shell, run the following update script:
  70
  71 ```console
  72 $ rustup update
  73 ```
  74
  75 To uninstall Rust and `rustup`, run the following uninstall script from your
  76 shell:
  77
  78 ```console
  79 $ rustup self uninstall
  80 ```
  81
  82 ### Troubleshooting
  83
  84 To check whether you have Rust installed correctly, open a shell and enter this
  85 line:
  86
  87 ```console
  88 $ rustc --version
  89 ```
  90
  91 You should see the version number, commit hash, and commit date for the latest
  92 stable version that has been released in the following format:
  93
  94 ```text
  95 rustc x.y.z (abcabcabc yyyy-mm-dd)
  96 ```
  97
  98 If you see this information, you have installed Rust successfully! If you don’t
  99 see this information and you’re on Windows, check that Rust is in your `%PATH%`
 100 system variable. If that’s all correct and Rust still isn’t working, there are
 101 a number of places you can get help. The easiest is the #beginners channel on
 102 [the official Rust Discord][discord]. There, you can chat with other Rustaceans
 103 (a silly nickname we call ourselves) who can help you out. Other great
 104 resources include [the Users forum][users] and [Stack Overflow][stackoverflow].
 105
 106 [discord]: https://discord.gg/rust-lang
 107 [users]: https://users.rust-lang.org/
 108 [stackoverflow]: https://stackoverflow.com/questions/tagged/rust
 109
 110 ### Local Documentation
 111
 112 The installation of Rust also includes a copy of the documentation locally, so
 113 you can read it offline. Run `rustup doc` to open the local documentation in
 114 your browser.
 115
 116 Any time a type or function is provided by the standard library and you’re not
 117 sure what it does or how to use it, use the application programming interface
 118 (API) documentation to find out!