rustlings/README.md

141 lines
5.1 KiB
Markdown
Raw Normal View History

2023-05-17 18:11:49 +03:00
<div class="oranda-hide">
2024-04-18 18:17:21 +03:00
# Rustlings 🦀❤️
2015-09-15 05:32:54 +03:00
2023-05-17 18:11:49 +03:00
</div>
2024-04-18 18:17:21 +03:00
Greetings and welcome to Rustlings.
This project contains small exercises to get you used to reading and writing Rust code.
This includes reading and responding to compiler messages!
2024-04-18 18:17:21 +03:00
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 📚️
2024-04-18 18:17:21 +03:00
[Rust By Example](https://doc.rust-lang.org/rust-by-example/) is another recommended resource that you might find helpful.
It contains code examples and exercises similar to Rustlings, but online.
2019-01-09 23:02:47 +03:00
## Getting Started
2024-04-18 18:17:21 +03:00
### Installing Rust
2019-03-06 22:25:27 +03:00
2024-04-18 18:17:21 +03:00
Before installing Rustlings, you need to have _Rust installed_.
Visit [www.rust-lang.org/tools/install](https://www.rust-lang.org/tools/install) for further instructions on installing Rust.
This'll also install _Cargo_, Rust's package/project manager.
2019-03-06 22:25:27 +03:00
2024-04-26 04:44:16 +03:00
> 🐧 If you're on Linux, make sure you've installed `gcc` (for a linker).
>
> Deb: `sudo apt install gcc`.
> Dnf: `sudo dnf install gcc`.
2024-04-26 04:44:16 +03:00
> 🍎 If you're on MacOS, make sure you've installed Xcode and its developer tools by running `xcode-select --install`.
2024-04-18 18:17:21 +03:00
### Installing Rustlings
2024-04-18 18:17:21 +03:00
The following command will download and compile Rustlings:
<!-- TODO: Remove @6.0.0-beta.x -->
2019-01-23 23:36:08 +03:00
```bash
2024-05-13 18:14:00 +03:00
cargo install rustlings@6.0.0-beta.9
2019-01-23 23:36:08 +03:00
```
2024-04-26 03:00:42 +03:00
<details>
2024-04-26 04:20:34 +03:00
<summary><strong>If the installation fails…</strong> (<em>click to expand</em>)</summary>
<!-- TODO: Remove @6.0.0-beta.x -->
2024-04-26 04:39:38 +03:00
- Make sure you have the latest Rust version by running `rustup update`
2024-05-13 18:14:00 +03:00
- Try adding the `--locked` flag: `cargo install rustlings@6.0.0-beta.9 --locked`
2024-04-26 04:39:38 +03:00
- Otherwise, please [report the issue](https://github.com/rust-lang/rustlings/issues/new)
2024-04-26 02:49:36 +03:00
2024-04-26 03:00:42 +03:00
</details>
2024-04-18 18:17:21 +03:00
### Initialization
2019-01-23 23:36:08 +03:00
2024-04-18 18:17:21 +03:00
After installing Rustlings, run the following command to initialize the `rustlings/` directory:
2019-01-23 23:36:08 +03:00
```bash
2024-04-18 18:17:21 +03:00
rustlings init
2019-01-23 23:36:08 +03:00
```
2024-04-26 04:25:31 +03:00
Now, go into the newly initialized directory and launch Rustlings for further instructions on getting started with the exercises:
```bash
2024-04-18 18:17:21 +03:00
cd rustlings/
rustlings
```
2024-04-29 01:26:53 +03:00
## Working environment
### Editor
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).
But any editor that supports [rust-analyzer](https://rust-analyzer.github.io/) should be enough for working on the exercises.
### Terminal
While working with Rustlings, please use a modern terminal for the best user experience.
The default terminal on Linux and Mac should be sufficient.
On Windows, we recommend the [Windows Terminal](https://aka.ms/terminal).
If you use VS Code, the builtin terminal should also be fine.
2024-04-18 18:17:21 +03:00
## Doing exercises
2024-04-26 04:17:35 +03:00
The exercises are sorted by topic and can be found in the subdirectory `exercises/<topic>`.
For every topic, there is an additional `README.md` file with some resources to get you started on the topic.
We highly recommend that you have a look at them before you start 📚️
2024-04-18 18:17:21 +03:00
Most exercises contain an error that keeps them from compiling, and it's up to you to fix it!
2024-04-26 04:44:16 +03:00
Some exercises contain tests that need to pass for the exercise to be done ✅
2024-04-26 04:17:35 +03:00
### Watch Mode
2024-04-26 04:25:31 +03:00
After [initialization](#initialization), Rustlings can be launched by simply running the command `rustlings`.
2024-04-26 04:17:35 +03:00
This will start the _watch mode_ which walks you through the exercises in a predefined order (what we think is best for newcomers).
It will rerun the current exercise automatically every time you change the exercise's file in the `exercises/` directory.
2024-04-18 18:17:21 +03:00
2024-04-26 04:17:35 +03:00
<details>
2024-04-26 04:20:34 +03:00
<summary><strong>If detecting file changes in the <code>exercises/</code> directory fails…</strong> (<em>click to expand</em>)</summary>
2022-03-29 16:04:52 +03:00
2024-05-13 03:37:32 +03:00
> You can add the **`--manual-run`** flag (`rustlings --manual-run`) to manually rerun the current exercise by entering `r` in the watch mode.
2024-04-26 04:29:05 +03:00
>
> 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).
2019-01-23 23:36:08 +03:00
2024-04-26 04:17:35 +03:00
</details>
2024-04-18 18:17:21 +03:00
2024-04-26 04:17:35 +03:00
### Exercise List
2024-04-18 18:17:21 +03:00
2024-05-13 03:37:32 +03:00
In the [watch mode](#watch-mode) (after launching `rustlings`), you can enter `l` to open the interactive exercise list.
2024-04-26 04:17:35 +03:00
The list allows you to…
- See the status of all exercises (done or pending)
2024-04-26 04:39:38 +03:00
- `c`: Continue at another exercise (temporarily skip some exercises or go back to a previous one)
- `r`: Reset status and file of an exercise (you need to _reload/reopen_ its file in your editor afterwards)
2024-04-26 04:17:35 +03:00
See the footer of the list for all possible keys.
2024-04-18 18:17:21 +03:00
## Continuing On
2024-04-18 18:17:21 +03:00
<!-- TODO: Mention third-party exercises -->
Once you've completed Rustlings, put your new knowledge to good use!
Continue practicing your Rust skills by building your own projects, contributing to Rustlings, or finding other open-source projects to contribute to.
## Uninstalling Rustlings
2024-04-26 04:17:35 +03:00
If you want to remove Rustlings from your system, run the following command:
2022-03-29 16:04:52 +03:00
```bash
cargo uninstall rustlings
```
2019-01-23 23:36:08 +03:00
## Contributing
2024-04-26 04:17:35 +03:00
See [CONTRIBUTING.md](https://github.com/rust-lang/rustlings/blob/main/CONTRIBUTING.md) 🔗
## Contributors ✨
2024-04-18 18:17:21 +03:00
Thanks to [all the wonderful contributors](https://github.com/rust-lang/rustlings/graphs/contributors) 🎉