|
| 1 | +# Third-Party Exercises |
| 2 | + |
| 3 | +The support of Rustlings for third-party exercises allows you to create your own set of Rustlings exercises to focus on some specific topic. |
| 4 | +You could also offer a translatation of the original Rustlings exercises as a third-party exercises. |
| 5 | + |
| 6 | +## Getting started |
| 7 | + |
| 8 | +To create third-party exercises, install Rustlings and run `rustlings dev new PROJECT_NAME`. |
| 9 | +This command will, similar to `cargo new PROJECT_NAME`, create a template directory called `PROJECT_NAME` with all what you need to get started. |
| 10 | + |
| 11 | +Read the comments in the generated `info.toml` file to understand the format of this file. |
| 12 | +It allows you to set a custom welcome and final message and specify the metadata of every exercise. |
| 13 | + |
| 14 | +## Create an exercise |
| 15 | + |
| 16 | +Here is an example of the metadata of one file: |
| 17 | + |
| 18 | +```toml |
| 19 | +[[exercises]] |
| 20 | +name = "intro1" |
| 21 | +hint = """ |
| 22 | +To finish this exercise, you need to … |
| 23 | +This link might help you …""" |
| 24 | +``` |
| 25 | + |
| 26 | +After entering this in `info.toml`, create the file `intro1.rs` in the `exercises/` directory. |
| 27 | +The exercise needs to contain a `main` function, but it can be empty. |
| 28 | +Adding tests is recommended. |
| 29 | +Look at the official Rustlings exercises for inspiration. |
| 30 | + |
| 31 | +You can optionally add a solution file `intro1.rs` to the `solutions/` directory. |
| 32 | + |
| 33 | +Now, run `rustlings dev check`. |
| 34 | +It will tell you about any issues with your exercises. |
| 35 | +For example, it will tell you to run `rustlings dev update` to update the `Cargo.toml` file to include the new exercise `intro1`. |
| 36 | + |
| 37 | +`rustlings dev check` will also run your solutions (if you have any) to make sure that they run successfully. |
| 38 | + |
| 39 | +That's it! |
| 40 | +You finished your first exercise 🎉 |
| 41 | + |
| 42 | +## Publish |
| 43 | + |
| 44 | +Now, add more exercises and publish them as a Git repository. |
| 45 | + |
| 46 | +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. |
| 47 | + |
| 48 | +One difference to the official exercises is that the solution files will not be hidden until the user finishes an exercise. |
| 49 | +But you can trust the user to not look at the solution too early ;) |
| 50 | + |
| 51 | +## Share |
| 52 | + |
| 53 | +After publishing your set of exercises, open a pull request in the official Rustlings repository to link to your project in the README 😃 |
0 commit comments