|
1 | 1 | # Rustlings 🦀❤️ |
2 | 2 |
|
3 | | -Greetings and welcome to Rustlings. |
4 | | -This project contains small exercises to get you used to reading and writing Rust code. |
5 | | -This includes reading and responding to compiler messages! |
6 | | - |
7 | | -It is recommended to do the Rustlings exercises in parallel to reading [the official Rust book](https://doc.rust-lang.org/book/), the most comprehensive resource for learning Rust 📚️ |
8 | | - |
9 | | -[Rust By Example](https://doc.rust-lang.org/rust-by-example/) is another recommended resource that you might find helpful. |
10 | | -It contains code examples and exercises similar to Rustlings, but online. |
11 | | - |
12 | | -## Getting Started |
13 | | - |
14 | | -### Installing Rust |
15 | | - |
16 | | -Before installing Rustlings, you need to have the **latest version of Rust** installed. |
17 | | -Visit [www.rust-lang.org/tools/install](https://www.rust-lang.org/tools/install) for further instructions on installing Rust. |
18 | | -This will also install _Cargo_, Rust's package/project manager. |
19 | | - |
20 | | -> 🐧 If you are on Linux, make sure you have installed `gcc` (for a linker). |
21 | | -> |
22 | | -> Deb: `sudo apt install gcc` |
23 | | -> |
24 | | -> Dnf: `sudo dnf install gcc` |
25 | | -
|
26 | | -> 🍎 If you are on MacOS, make sure you have installed Xcode and its developer tools by running `xcode-select --install`. |
27 | | -
|
28 | | -### Installing Rustlings |
29 | | - |
30 | | -The following command will download and compile Rustlings: |
31 | | - |
32 | | -```bash |
33 | | -cargo install rustlings |
34 | | -``` |
35 | | - |
36 | | -<details> |
37 | | -<summary><strong>If the installation fails…</strong> (<em>click to expand</em>)</summary> |
38 | | - |
39 | | -- Make sure you have the latest Rust version by running `rustup update` |
40 | | -- Try adding the `--locked` flag: `cargo install rustlings --locked` |
41 | | -- Otherwise, please [report the issue](https://github.com/rust-lang/rustlings/issues/new) |
42 | | - |
43 | | -</details> |
44 | | - |
45 | | -### Initialization |
46 | | - |
47 | | -After installing Rustlings, run the following command to initialize the `rustlings/` directory: |
48 | | - |
49 | | -```bash |
50 | | -rustlings init |
51 | | -``` |
52 | | - |
53 | | -<details> |
54 | | -<summary><strong>If the command <code>rustlings</code> can't be found…</strong> (<em>click to expand</em>)</summary> |
55 | | - |
56 | | -You are probably using Linux and installed Rust using your package manager. |
57 | | - |
58 | | -Cargo installs binaries to the directory `~/.cargo/bin`. |
59 | | -Sadly, package managers often don't add `~/.cargo/bin` to your `PATH` environment variable. |
60 | | - |
61 | | -The solution is to … |
62 | | - |
63 | | -- either add `~/.cargo/bin` manually to `PATH` |
64 | | -- or to uninstall Rust from the package manager and install it using the official way with `rustup`: https://www.rust-lang.org/tools/install |
65 | | - |
66 | | -</details> |
67 | | - |
68 | | -Now, go into the newly initialized directory and launch Rustlings for further instructions on getting started with the exercises: |
69 | | - |
70 | | -```bash |
71 | | -cd rustlings/ |
72 | | -rustlings |
73 | | -``` |
74 | | - |
75 | | -## Working environment |
76 | | - |
77 | | -### Editor |
78 | | - |
79 | | -Our general recommendation is [VS Code](https://code.visualstudio.com/) with the [rust-analyzer plugin](https://marketplace.visualstudio.com/items?itemName=rust-lang.rust-analyzer). |
80 | | -But any editor that supports [rust-analyzer](https://rust-analyzer.github.io/) should be enough for working on the exercises. |
81 | | - |
82 | | -### Terminal |
83 | | - |
84 | | -While working with Rustlings, please use a modern terminal for the best user experience. |
85 | | -The default terminal on Linux and Mac should be sufficient. |
86 | | -On Windows, we recommend the [Windows Terminal](https://aka.ms/terminal). |
87 | | - |
88 | | -## Doing exercises |
89 | | - |
90 | | -The exercises are sorted by topic and can be found in the subdirectory `exercises/<topic>`. |
91 | | -For every topic, there is an additional `README.md` file with some resources to get you started on the topic. |
92 | | -We highly recommend that you have a look at them before you start 📚️ |
93 | | - |
94 | | -Most exercises contain an error that keeps them from compiling, and it's up to you to fix it! |
95 | | -Some exercises contain tests that need to pass for the exercise to be done ✅ |
96 | | - |
97 | | -Search for `TODO` and `todo!()` to find out what you need to change. |
98 | | -Ask for hints by entering `h` in the _watch mode_ 💡 |
99 | | - |
100 | | -### Watch Mode |
101 | | - |
102 | | -After the [initialization](#initialization), Rustlings can be launched by simply running the command `rustlings`. |
103 | | - |
104 | | -This will start the _watch mode_ which walks you through the exercises in a predefined order (what we think is best for newcomers). |
105 | | -It will rerun the current exercise automatically every time you change the exercise's file in the `exercises/` directory. |
106 | | - |
107 | | -<details> |
108 | | -<summary><strong>If detecting file changes in the <code>exercises/</code> directory fails…</strong> (<em>click to expand</em>)</summary> |
109 | | - |
110 | | -> You can add the **`--manual-run`** flag (`rustlings --manual-run`) to manually rerun the current exercise by entering `r` in the watch mode. |
111 | | -> |
112 | | -> Please [report the issue](https://github.com/rust-lang/rustlings/issues/new) with some information about your operating system and whether you run Rustlings in a container or virtual machine (e.g. WSL). |
113 | | -
|
114 | | -</details> |
115 | | - |
116 | | -### Exercise List |
117 | | - |
118 | | -In the [watch mode](#watch-mode) (after launching `rustlings`), you can enter `l` to open the interactive exercise list. |
119 | | - |
120 | | -The list allows you to… |
121 | | - |
122 | | -- See the status of all exercises (done or pending) |
123 | | -- `c`: Continue at another exercise (temporarily skip some exercises or go back to a previous one) |
124 | | -- `r`: Reset status and file of the selected exercise (you need to _reload/reopen_ its file in your editor afterwards) |
125 | | - |
126 | | -See the footer of the list for all possible keys. |
127 | | - |
128 | | -## Questions? |
129 | | - |
130 | | -If you need any help while doing the exercises and the builtin-hints aren't helpful, feel free to ask in the [_Q&A_ category of the discussions](https://github.com/rust-lang/rustlings/discussions/categories/q-a?discussions_q=) if your question wasn't asked yet 💡 |
131 | | - |
132 | | -## Third-Party Exercises |
133 | | - |
134 | | -Third-party exercises are a set of exercises maintained by the community. |
135 | | -You can use the same `rustlings` program that you installed with `cargo install rustlings` to run them: |
136 | | - |
137 | | -- 🇯🇵 [Japanese Rustlings](https://github.com/sotanengel/rustlings-jp)：A Japanese translation of the Rustlings exercises. |
138 | | -- 🇨🇳 [Simplified Chinese Rustlings](https://github.com/SandmeyerX/rustlings-zh-cn): A simplified Chinese translation of the Rustlings exercises. |
139 | | - |
140 | | -Do you want to create your own set of Rustlings exercises to focus on some specific topic? |
141 | | -Or do you want to translate the original Rustlings exercises? |
142 | | -Then follow the the guide about [third-party exercises](https://github.com/rust-lang/rustlings/blob/main/THIRD_PARTY_EXERCISES.md)! |
143 | | - |
144 | | -## Continuing On |
145 | | - |
146 | | -Once you've completed Rustlings, put your new knowledge to good use! |
147 | | -Continue practicing your Rust skills by building your own projects, contributing to Rustlings, or finding other open-source projects to contribute to. |
148 | | - |
149 | | -## Uninstalling Rustlings |
150 | | - |
151 | | -If you want to remove Rustlings from your system, run the following command: |
152 | | - |
153 | | -```bash |
154 | | -cargo uninstall rustlings |
155 | | -``` |
156 | | - |
157 | | -## Contributing |
158 | | - |
159 | | -See [CONTRIBUTING.md](https://github.com/rust-lang/rustlings/blob/main/CONTRIBUTING.md) 🔗 |
160 | | - |
161 | | -Thanks to [all the wonderful contributors](https://github.com/rust-lang/rustlings/graphs/contributors) ✨ |
| 3 | +➡️ [**rustlings.rust-lang.org**](https://rustlings.rust-lang.org) ⬅️ |
0 commit comments