diff options
Diffstat (limited to 'website/content')
| -rw-r--r-- | website/content/_index.md | 21 | ||||
| -rw-r--r-- | website/content/community-exercises/index.md | 73 | ||||
| -rw-r--r-- | website/content/setup/index.md | 78 | ||||
| -rw-r--r-- | website/content/usage/index.md | 55 |
4 files changed, 227 insertions, 0 deletions
diff --git a/website/content/_index.md b/website/content/_index.md new file mode 100644 index 0000000..4bb4483 --- /dev/null +++ b/website/content/_index.md @@ -0,0 +1,21 @@ ++++ ++++ + +Small exercises to get you used to reading and writing [Rust](https://www.rust-lang.org) code - _Recommended in parallel to reading [the official Rust book](https://doc.rust-lang.org/book) ποΈ_ + +<script src="https://asciinema.org/a/719805.js" id="asciicast-719805" async="true"></script> + +## Quick start + +```bash +# Installation +cargo install rustlings +# Initialization +rustlings init +# Moving into new directory +cd rustlings +# Starting Rustlings +rustlings +``` + +Visit the [**setup**](@/setup/index.md) page for more details π§° diff --git a/website/content/community-exercises/index.md b/website/content/community-exercises/index.md new file mode 100644 index 0000000..0f713d7 --- /dev/null +++ b/website/content/community-exercises/index.md @@ -0,0 +1,73 @@ ++++ +title = "Community Exercises" ++++ + +## List of Community Exercises + +- π―π΅ [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. + +> You can use the same `rustlings` program that you installed with `cargo install rustlings` to run community exercises. + +## Creating Community Exercises + +Rustling's support for community exercises allows you to create your own exercises to focus on some specific topic. +You could also offer a translation of the original Rustlings exercises as community exercises. + +### Getting Started + +To create community exercises, install Rustlings and run `rustlings dev new PROJECT_NAME`. +This command will, similar to `cargo new PROJECT_NAME`, create the template directory `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. + +### Creating an Exercise + +Here is an example of the metadata of one exercise: + +```toml +[[exercises]] +name = "intro1" +hint = """ +To finish this exercise, you need to β¦ +These links 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 π + +### Cargo.toml + +Except of the `bin` list, you can modify the `Cargo.toml` file as you want. + +> The `bin` list is automatically updated by running `rustlings dev update` + +- You can add dependencies in the `[dependencies]` table. +- You might want to [configure some lints](https://doc.rust-lang.org/cargo/reference/manifest.html#the-lints-section) for all exercises. You can do so in the `[lints.rust]` and `[lints.clippy]` tables. + +### Publishing + +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 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 your users to not open the solution too early π + +### Sharing + +After publishing your community exercises, open an issue or a pull request in the [official Rustlings repository](https://github.com/rust-lang/rustlings) to add your project to the [list of community exercises](#list-of-community-exercises) π diff --git a/website/content/setup/index.md b/website/content/setup/index.md new file mode 100644 index 0000000..54551ad --- /dev/null +++ b/website/content/setup/index.md @@ -0,0 +1,78 @@ ++++ +title = "Setup" ++++ + +<!-- toc --> + +## Installing Rust + +Before installing Rustlings, you must have the **latest version of Rust** installed. +Visit [www.rust-lang.org/tools/install](https://www.rust-lang.org/tools/install) for further instructions. +This will also install _Cargo_, Rust's package/project manager. + +> π§ If you are on **Linux**, make sure you have `gcc` installed (_for a linker_). +> +> Debian: `sudo apt install gcc`\ +> Fedora: `sudo dnf install gcc` + +> π If you are on **MacOS**, make sure you have _Xcode and its developer tools_ installed: `xcode-select --install` + +## Installing Rustlings + +The following command will download and compile Rustlings: + +```bash +cargo install rustlings +``` + +{% details(summary="If the installation failsβ¦") %} + +- 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) + +{% end %} + +## Initialization + +After installing Rustlings, run the following command to initialize the `rustlings/` directory: + +```bash +rustlings init +``` + +{% details(summary="If the command <code>rustlings</code> can't be foundβ¦") %} + +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. + +- Either add `~/.cargo/bin` manually to `PATH` +- Or uninstall Rust from the package manager and [install it using the official way with `rustup`](https://www.rust-lang.org/tools/install) + +{% end %} + +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). + +## Usage + +After being done with the setup, visit the [**usage**](@/usage/index.md) page for some info about using Rustlings π diff --git a/website/content/usage/index.md b/website/content/usage/index.md new file mode 100644 index 0000000..88dabf4 --- /dev/null +++ b/website/content/usage/index.md @@ -0,0 +1,55 @@ ++++ +title = "Usage" ++++ + +<!-- toc --> + +## 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](@/setup/index.md#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="If detecting file changes in the <code>exercises/</code> directory failsβ¦") %} + +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 a virtual machine (e.g. WSL). + +{% end %} + +## 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_ discussions](https://github.com/rust-lang/rustlings/discussions/categories/q-a?discussions_q=) if your question isn't answered there π‘ + +## 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. + +> If you want to create your own Rustlings exercises, visit the [**community exercises**](@/community-exercises/index.md) page ποΈ |