Skip to content

Commit 9bb174e

Browse files
committed
Add a guide for third-party exercises
1 parent 4c5573b commit 9bb174e

File tree

2 files changed

+59
-2
lines changed

2 files changed

+59
-2
lines changed

README.md

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -117,11 +117,15 @@ See the footer of the list for all possible keys.
117117

118118
## Continuing On
119119

120-
<!-- TODO: Mention third-party exercises -->
121-
122120
Once you've completed Rustlings, put your new knowledge to good use!
123121
Continue practicing your Rust skills by building your own projects, contributing to Rustlings, or finding other open-source projects to contribute to.
124122

123+
## Third-Party Exercises
124+
125+
Do you want to create your own set of Rustlings exercises to focus on some specific topic?
126+
Or did you want to translate the original Rustlings exercises?
127+
Then follow the link to the guide about [third-party exercises](THIRD_PARTY_EXERCISES.md)!
128+
125129
## Uninstalling Rustlings
126130

127131
If you want to remove Rustlings from your system, run the following command:

THIRD_PARTY_EXERCISES.md

Lines changed: 53 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,53 @@
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

Comments
 (0)