diff options
Diffstat (limited to 'website/content')
| -rw-r--r-- | website/content/_index.md | 143 | ||||
| -rw-r--r-- | website/content/custom-exercises/index.md | 66 |
2 files changed, 209 insertions, 0 deletions
diff --git a/website/content/_index.md b/website/content/_index.md new file mode 100644 index 0000000..2ad12eb --- /dev/null +++ b/website/content/_index.md @@ -0,0 +1,143 @@ ++++ ++++ + +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! + +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 📚️ + +<!-- toc --> + +## Getting Started + +### Installing Rust + +Before installing Rustlings, you need to have the **latest version of Rust** installed. +Visit [www.rust-lang.org/tools/install](https://www.rust-lang.org/tools/install) for further instructions on installing Rust. +This will also install _Cargo_, Rust's package/project manager. + +> 🐧 If you are on Linux, make sure you have installed `gcc` (for a linker). +> +> Deb: `sudo apt install gcc` +> +> Dnf: `sudo dnf install gcc` + +> 🍎 If you are on MacOS, make sure you have installed Xcode and its developer tools by running `xcode-select --install`. + +### Installing Rustlings + +The following command will download and compile Rustlings: + +```bash +cargo install rustlings +``` + +<details> +<summary><strong>If the installation fails…</strong> (<em>click to expand</em>)</summary> + +- Make sure you have the latest Rust version by running `rustup update` +- Try adding the `--locked` flag: `cargo install rustlings --locked` +- Otherwise, please [report the issue](https://github.com/rust-lang/rustlings/issues/new) + +</details> + +### Initialization + +After installing Rustlings, run the following command to initialize the `rustlings/` directory: + +```bash +rustlings init +``` + +<details> +<summary><strong>If the command <code>rustlings</code> can't be found…</strong> (<em>click to expand</em>)</summary> + +You are probably using Linux and installed Rust using your package manager. + +Cargo installs binaries to the directory `~/.cargo/bin`. +Sadly, package managers often don't add `~/.cargo/bin` to your `PATH` environment variable. + +The solution is to … + +- either add `~/.cargo/bin` manually to `PATH` +- or to uninstall Rust from the package manager and install it using the official way with `rustup`: https://www.rust-lang.org/tools/install + +</details> + +Now, go into the newly initialized directory and launch Rustlings for further instructions on getting started with the exercises: + +```bash +cd rustlings/ +rustlings +``` + +## 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). + +## Doing exercises + +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 📚️ + +Most exercises contain an error that keeps them from compiling, and it's up to you to fix it! +Some exercises contain tests that need to pass for the exercise to be done ✅ + +Search for `TODO` and `todo!()` to find out what you need to change. +Ask for hints by entering `h` in the _watch mode_ 💡 + +### Watch Mode + +After the [initialization](#initialization), Rustlings can be launched by simply running the command `rustlings`. + +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. + +<details> +<summary><strong>If detecting file changes in the <code>exercises/</code> directory fails…</strong> (<em>click to expand</em>)</summary> + +> You can add the **`--manual-run`** flag (`rustlings --manual-run`) to manually rerun the current exercise by entering `r` in the watch mode. +> +> 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). + +</details> + +### Exercise List + +In the [watch mode](#watch-mode) (after launching `rustlings`), you can enter `l` to open the interactive exercise list. + +The list allows you to… + +- See the status of all exercises (done or pending) +- `c`: Continue at another exercise (temporarily skip some exercises or go back to a previous one) +- `r`: Reset status and file of the selected exercise (you need to _reload/reopen_ its file in your editor afterwards) + +See the footer of the list for all possible keys. + +## Questions? + +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 💡 + +## Continuing On + +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 + +If you want to remove Rustlings from your system, run the following command: + +```bash +cargo uninstall rustlings +``` diff --git a/website/content/custom-exercises/index.md b/website/content/custom-exercises/index.md new file mode 100644 index 0000000..e8bef76 --- /dev/null +++ b/website/content/custom-exercises/index.md @@ -0,0 +1,66 @@ ++++ +title = "Custom Exercises" ++++ + +Custom exercises are a set of exercises maintained by the community. +You can use the same `rustlings` program that you installed with `cargo install rustlings` to run them: + +- 🇯🇵 [Japanese Rustlings](https://github.com/sotanengel/rustlings-jp)：A Japanese translation of the Rustlings exercises. +- 🇨🇳 [Simplified Chinese Rustlings](https://github.com/SandmeyerX/rustlings-zh-cn): A simplified Chinese translation of the Rustlings exercises. + +Do you want to create your own set of Rustlings exercises to focus on some specific topic? +Or do you want to translate the original Rustlings exercises? + +<!-- toc --> + +The support of Rustlings for custom exercises allows you to create your own set of Rustlings exercises to focus on some specific topic. +You could also offer a translation of the original Rustlings exercises as custom exercises. + +## Getting started + +To create custom exercises, install Rustlings and run `rustlings dev new PROJECT_NAME`. +This command will, similar to `cargo new PROJECT_NAME`, create a template directory called `PROJECT_NAME` with all what you need to get started. + +Read the comments in the generated `info.toml` file to understand its format. +It allows you to set a custom welcome and final message and specify the metadata of every exercise. + +## Create an exercise + +Here is an example of the metadata of one file: + +```toml +[[exercises]] +name = "intro1" +hint = """ +To finish this exercise, you need to … +This link might help you …""" +``` + +After entering this in `info.toml`, create the file `intro1.rs` in the `exercises/` directory. +The exercise needs to contain a `main` function, but it can be empty. +Adding tests is recommended. +Look at the official Rustlings exercises for inspiration. + +You can optionally add a solution file `intro1.rs` to the `solutions/` directory. + +Now, run `rustlings dev check`. +It will tell you about any issues with your exercises. +For example, it will tell you to run `rustlings dev update` to update the `Cargo.toml` file to include the new exercise `intro1`. + +`rustlings dev check` will also run your solutions (if you have any) to make sure that they run successfully. + +That's it! +You finished your first exercise 🎉 + +## Publish + +Now, add more exercises and publish them as a Git repository. + +Users just have to clone that repository and run `rustlings` in it to start working on your set of exercises just like the official ones. + +One difference to the official exercises is that the solution files will not be hidden until the user finishes an exercise. +But you can trust the users to not look at the solution too early 😉 + +## Share + +After publishing your set of exercises, open an issue or a pull request in the official Rustlings repository to link to your project in the README 😃 |