tweedegolf / 101-rs

A modular, reusable university course for Rust

Teach-rs

Teach-rs is a university course for computer science students, introducing the Rust Programming Language, and is available for anyone who wants to teach Rust.

Why? Have a look at our blog post introducing the course.

This repo will contain everything that's needed to organize the course: slides, exercises, tools, setup instructions and more.

While all the available material is user-ready, this repo is not yet as exhaustive as we'd like, so feedback and contributions are welcome! So is sponsorship; read more below or on our Sponsorship page.

Usage

The teacher's guide can be found here. Have a look at the ModMod Readme for instructions on how to render the content of a track.

Structure

The actual content can be found in the content directory. The content is structured in a tree of Tracks, Modules, Units, and Topics. Tracks define a single course, which consists of one or more Modules, which again combines one or more Units, which again is a set of Topics. Units roughly correspond to one lecture+tutorial (or at least that is the idea, but TODO), and consist of several Topics. Related Units are combined in a Module. Topics are packages that cover a single topic, and include a small number of slides, some exercises, and an exercise descripion. Topics can define their learning objectives, further reading material, and how they should be summarized in a Unit introduction.

Tracks, Modules, Units, and Topics and the files they refer to are described in the several TOML files in the content directory. ModMod combines the content into a structure that can be directly published to your students in a Git repo, for instance.

Pre-defined tracks

• Rust Language Introduction aims to introduce the basics to the Rust programming language, and to enable students to engineer their own applications and crates.
• Rust for the Web covers content that is needed to use Rust in web applications.
• Rust for Systems Programming contains more low-level topics, to teach systems programming using Rust.
• Scientific Rust is about using Rust in scientific programming.
• Full contains all available teach-rs content.

Note: although the outline of the tracks is mostly complete, the tracks may still contain TODOs. You're invited to contribute your own content to fix these!

High-level goals

Teach-rs aims to provide an open-source course, lectures, tutorials and exercises, that can be used by any higher education institution. Use one of the pre-defined tracks, or compose your own with the content we provide and your own.

1. Provide a modular, resuable basis for live-taught Rust courses
2. Provide students with practical, hands-on experience
3. Provide students with background information of Rust features
4. Provide students with ability to judge whether Rust fits a project
5. Provide several specialized learning tracks that focus on different applications (e.g. systems, embedded, web)
6. Enable teachers to contribute their material for others to use

About the project

The project is executed by Henk Oordt and others at Tweede golf. It is a not-for-profit project, where the only requirement is that the cost of our work is covered.

We're very happy with support in developing the course material from:

• Bernard van Gastel, Radboud University
• Florian Gilcher, Ferrous Systems
• Jonathan Donszelmann, TU Delft

Contributing

If you'd like to improve teach-rs, either by doing touchups, restructuring a module, or even adding a module, please refer to the contributing guidelines before you get started.

Our sponsors

Founding sponsors

The initial sponsor of the project is the Faculty of Informatics and Information Technologies (FIIT) of the Slovak University of Technology (STU) in Bratislava, Slovakia. FIIT's contribution has enabled us to layout the groundwork for the course. Tweede golf and Rust Edu have also contributed substantially to the creation of teach-rs.

In addition, lead developer Henk has received a grant from the Rust Foundation.

Silver sponsors

And a big thank you to our Silver sponsors:

• Gofore
• RustJobs.dev

Support teach-rs

We are in search of further funding for this project. Contact us if you´re interested, or sponsor our work. At the moment, any one-time or montly donation would support the maintenance of the project. Larger donations would enable us to create new modules and improve existing course material.

101-rs's Issues

Add content on `Fn*` traits to closure topic

Content about

• Fn, FnMut, FnOnce, fn
• Closures as function parameters
• Closures in structs

Best would be to contribute it directly to the restructure branch while it's still unmerged. There's a file on that branch where the content could be added: https://github.com/tweedegolf/101-rs/blob/restructure/slides/A-foundations/closures.md

101-rs/slides /A3-traits-generics.md : ` impl std::ops::Add ` (2) : typo ?

compilation of the example on the slide fails... line 6 : replacing "rhs : Self" with "rhs : u32" makes it work.

Add content on NodeJS interoperability

Add content on NodeJS interoperability

• Call Rust from NodeJS with wasm
• Call Rust from NodeJS with NAPI-rs

Best would be to contribute it directly to the restructure branch while it's still unmerged. There's a file on that branch where the content could be added: https://github.com/tweedegolf/101-rs/blob/restructure/slides/D-rust-for-web/nodejs-interop.md

Add content on `sqlx`

Add content on the sqlx crate with Postgres

• How to set up
• Migrations
• Best practices

Best would be to contribute it directly to the restructure branch while it's still unmerged. There's a file on that branch where the content could be added: https://github.com/tweedegolf/101-rs/blob/restructure/slides/D-rust-for-web/sqlx.md

101-rs/slides / D-trait-objects-patterns.md : Typestate: example : typo ?

impl CoffeeMachine {
fn insert_money(self) -> CoffeeMachine {
println!("Money inserted!");
self.insert_money()
}
}

=> self.into_state() instead of self.insert_money() to prevent recursion

Add references to further reading material

For each module, add references to further reading material

Add a teacher's companion

To allow teachers to more easily get started with Rust 101, add a teacher's companion to the course. The teacher's companion should describe which modules can be used for different situations and target audiences, and describes per module how it should be taught, how much time we estimate the module takes, and where to find background information on the module subjects.

Add content on smart pointers

Add content on the following topics:

• Box, Vec and String being smart pointers
• Rc
• Drop
• Deref & DerefMut
• Deref coercion

Best would be to contribute it directly to the restructure branch while it's still unmerged. There's a file on that branch where the content could be added: https://github.com/tweedegolf/101-rs/blob/restructure/slides/A-foundations/smart-pointers.md

Invite students for test lecture

Define different learning tracks

Rust 101 is meant to be multi purpose. Therefore, we define a set of different learning tracks consisting of several modules of which we define modules and subjects their content is dependent on.

As a start, we can define the following tracks:

• Systems programming
• Embedded development
• Web development

We also explore the possiblity of setting up a track that uses Rust as a first programming language. See #25

Add content on macros

Content about:

• Declarative macros
• Macro hygiene
• Macros operating on AST
• Procedural macros
• When to use and when to avoid

Best would be to contribute it directly to the restructure branch while it's still unmerged. There's a file on that branch where the content could be added: https://github.com/tweedegolf/101-rs/blob/restructure/slides/B-crate-engineering/macros.md

Add content on quality tools

Content about some tools that can be used to monitor the code quality

• cargo audit
• cargo vet
• cargo fuzz
• cargo udeps

Best would be to contribute it directly to the restructure branch while it's still unmerged. There's a file on that branch where the content could be added: https://github.com/tweedegolf/101-rs/blob/restructure/slides/B-crate-engineering/tools.md

Notes on Course Material

Hey, I decided to look through the Course Material and have some questions and comments which hopefully can help the course forward. Overal I agree with most of the structure.

Target Audience

What is the actual target audience of the course? Is it targeting first year's students or students later in their university life? My current impression is that is trying to target both, which is fine but is probably quite a lot more difficult.

To deal with these differences in the audience experience, it may be interesting to provide a block with most programming syntax and semantics sections with 4-5 tabs. This should try to explain it which the readers specific context and give the professors good resources depending on the context at the university.

One tab should explain the concept as if the reader has no programming experience, others should explain it as if the reader is coming from a specific programming language. As far as I know the most common languages to learn first at university are C, Python, Java and JavaScript. We can compare basic concepts to how they are in those languages.

A1

The A1 module mostly seems fine to me. One of the parts I maybe agree a bit less with is the Move Semantics. Personally, I would take this chance to explain the rationale for the Borrow Checker and also explain the Drop semantics (not the Drop trait). I feel like most people would agree this is one of the major mechanisms that sets rust apart from other programming languages and having people familiar with it seems like something you want to do as soon as possible. Later you could link back onto this and explain things in a little more detail. Meanwhile students may connect some dots and detect some patterns themselves.

Some others small things:

• rustc --explain is really useful
• Some exercises with theoretical questions about the borrow checker

A2

This is probably the module I have the most comments about.

• Personnally, I would explain lib vs bin and the module system in this section as I feel like they are both extremely vital to looking at any form of rust code.
• I would move opt-levels and LTO to module B. These things are extremely domain specific and just distract from the important basics. Same for cross-compilation.
• SemVer is extremely widely used in Rust. It should at least be mentioned here, I reckon.
• Mention the rustonomicon in module F and not here.
• Just provide a list of commonly used crates (serde, rand, libc, nix, syn, quote, proc_macro(2)) and explain why not everything is in the std

A3

• Maybe do mention into & from with the casting but don't explain them detailed as of yet. Just plant the seed that there might be a method that is used in most situations.
• Maybe add a part about const contexts.
• Small part on macro_rules! since these are widely used
• Leave out union here and explain that in F with the unsafe and FFI parts

B

• Part on normal headers in documentation. Already partly included in Rust API guidelines

C

• Mention Rayon
• Maybe reference the book by Mara Bos on the topic

D

• Explain the different memory models that can be used while programming rust. This is mostly from the Jon Gjengset video on unsafe rust. I do think this is quite important but may take a long time to explain properly. Maybe there are some external resources that do this already and we can link to those.

E

• Part on WebAssembly

A0

Maybe, it is an idea to have an A0 module that is specifically for universities trying to use Rust as their intro to programming class. This may be out of the scope of this project, let me know.

This module can explain some of the more general and basic programming concepts. This could cover motivations for items and introduce working code without to much explanation as to what they are. Providing a lot of space for the student to infer their own patterns. I need to do more research into how other courses do this, but right now some of the items I think it should introduce are:

• Variables
  • Numbers (unsigned, signed, floating point)
  • Chars and strings
  • Groups of structures
• Control Flow
• Loops
• Functions
• Input / Output
• Compartimentilization
• Examples of common domains
  • Web
  • Systems
  • Embedded
• Common problems
  • max / min
  • serialisation
  • parsing
  • sorting

Thoughts

I think it will be very difficult to balance time and what to explain where.

I would love to help writing parts of this course. I would love to hear your opinions on these items and if you agree with some, I can send a PR with those changes. Also, if you would like me to look into some specifics let me know. If you would like to have me start writing on some topic, also let me know. Again, would love to help.

Decide on quiz platform

• Nearpod (gratis basisversie, veel mogelijkheden, o.a. gamified en integratie met je slides)
• Kahoot (gratis basisversie, gamified, kinderlijk?)
• Socrative ($179.99 USD/year, even navragen of ze dat bij Bratislava al gebruiken, mss kun je een account krijgen)
• Forms (zal bij het pakket van de uni van Bratislava zitten, als ze ook Teams gebruiken. Voordeel is dat studenten dan automatisch ingelogd zijn en je het makkelijk in een voor hun bekende omgeving kunt integreren. Nadeel is dat antwoorden van open vragen visueel slecht weergegeven worden)

Add contributing guidelines

Add guidelines on how to contribute to this project.

Write blog post based on 101-rs presentation

Swap out slidev for some rust-based tool

Currently, modmod builds a NodeJS package that uses Slidev to create slideshows out of markdown files. Being a Rust course, it would be nice to depend only on Rust-based tooling, and therefore swap out Slidev for something Rust based.

What we need in a tool:

• Convert Markdown slides to slideshow
• Include Markdown files in other Mardown files
• Support custom themes
• Be open source (MIT Licensed)
• Support presenter mode
• Render to HTML

Add topic 'Why Rust'

We currently have no apt introduction to the (design) goals of Rust. Add a slides that covering the following topic:

Why Rust

• Problems Rust aims to solve
  • Memory safety
  • Concurrency bugs
• Brief history
• Design goals
  • Memory safety
  • Explicitness
  • Zero-cost abstractions
• The space Rust is in
• What you can use Rust for

Best would be to contribute it directly to the restructure branch while it's still unmerged. There's a file on that branch where the content could be added: https://github.com/tweedegolf/101-rs/blob/restructure/slides/A-foundations/why-rust.md

Add content on WASM

Add content on Web Assembly

• Running in the browser
• As an extension
• Various runtimes
• Sandboxing
• Current state of the art concerning Wasm Interface Types

Best would be to contribute it directly to the restructure branch while it's still unmerged. There's a file on that branch where the content could be added: https://github.com/tweedegolf/101-rs/blob/restructure/slides/D-rust-for-web/wasm.md

Add content on crate `futures`

Content about:

• futures::lock
• futures::channel
• Stream & Sync
• AsyncRead & AsyncWrite
• macros

Best would be to contribute it directly to the restructure branch while it's still unmerged. There's a file on that branch where the content could be added: https://github.com/tweedegolf/101-rs/blob/restructure/slides/C-multitasking/ordering.md

Update README

Revise current content and add sections on future ideas and roadmap

Minor fixes and improvements

A1

• Slide 7 has a strange list
• Slide 8: Maybe don't use the embedded link to display on the slide
• Slide 30: I find it a bit counterintuitive that the first bullet point after the heading “Statements” explains what an Expression is. Maybe move the first bullet point to the next slide, where expressions are explained anyway
• Slide 34: The light font on the image is hard to read (As I found out later, this is apparently only a problem in the dark mode. If you don't use that, you can probably ignore this)

https://101-rs.tweede.golf/

1.0 - Installation

• This link gives a 404: https://marketplace.visualstudio.com/items?itemName=MS-vsliveshare.vsliveshare-pack
• The following link is not clickable: https://www.youtube.com/playlist?list=PLg7s6cbtAD15G8lNyoaYDuKZSKyJrgwB-
• “To clone the repository, you'll need an account on GitHub” is not true. As long as only pull but not push, you don't need one (though I agree that it is helpful anyway)

2.1

• In the end, you say that exercises/A1/2-move-semantics/01.rs should compile as is, but this is not true, as there is one mut missing.
• You may want to delete exercises/A1/2-move-semantics/src/main.rs

A2

• Slide 21: In the subheading, you probably mean 'Structs' instead of 'Enums'?

• exercises/A2/4-boxed-data/src/main.rs:102 “If you have time let” should be “If you have time left”

• exercises/A2/4-boxed-data/src/main.rs uses a different syntax ('///') instead of ('//') to explain the exercise

3.B

• https://101-rs.tweede.golf/B-application-programming/mod.html previous to last line: 'allications' should be 'allocations'

Tracking Issue: A0 module for First Language-Learners / Refresh on Low-Level Concepts

This tracks the progress of the A0 module, which aims to help bridge the gap for two target groups to move onto A1. The groups that are targeted:

1. Students learning Rust as their first programming language
2. Students who know high-level programming languages but are unfamiliar with low-level concepts

This should really represent an optional course that can be included in specific situations. It could serve as a resource for students or provide exercises to study specific low-level concepts.

This was proposed and discussed in #18.

Module Content

This is a list of things this module should aim to teach. This is not necessarily ordered.

• Hello World in Rust
• Input / Output
• Variables
• Branching
• Loop Conditions
  • For (Each)
  • While
  • For Each
  • Break Loop
• Static Typing
  - Binary and Variables in Memory
  - Bit operations
  - Signed integer
  - Unsigned integer
  - String
  - Boolean
  - Arrays
  - Tuples
  • Structures
• Functions
  - Parameters & Return value
  - Recursion
• Stack and Heap
• Copy-by-Reference versus Copy-by-Value

Slides

The slides on a specific concept should focus the rough structure:

1. General overview of the concept. Gives an intuition for the student, but probably too abstract to apply.
2. Several examples. These should increase in level. Try to find some quite complicated examples that really test the understanding of the student.
3. Last quick summary of the concept.

Exercises

The module contains many small and rewarding exercises to teach. All of these exercise should be on the Rust Playground and try to really focus on a specific concept per time.

What this module does not contain

• Operating System concepts
  - System-Calls
  - Low-Level Memory Management
• An exploration of the standard library. Talk about Box and Vec but nothing else.
• Compilers
  - CLI interaction with cargo or rustc

Useful Reference Resources

• Rust Book
• Steve Donovan's Rust Basics
• Previous Rust-Lang.org FAQ
• RustConf 2017 - A Tale of Teaching Rust by Andrew Brinker

Add content on Memory Ordering

Content about:

• std::sync::atomic::Ordering
• Atomic ordering
• Compiler fences

Best would be to contribute it directly to the restructure branch while it's still unmerged. There's a file on that branch where the content could be added: https://github.com/tweedegolf/101-rs/blob/restructure/slides/C-multitasking/ordering.md

Add content introducing multithreading

Add content introducing multithreading as a concept

Best would be to contribute it directly to the restructure branch while it's still unmerged. There's a file on that branch where the content could be added: https://github.com/tweedegolf/101-rs/blob/restructure/slides/C-multitasking/intro.md

Cannot create a Vec literal (compile error in slices/slides.md example)

Hi, awesome work! When I recorded my video based on your slides this morning I noticed something that didn't look right.

In this example in slides/slides.md:

fn sum(data: &[i32]) -> i32 { /* ... */ }

fn get_v_arr() -> &'static [i32] {
    &[0, 1, 2, 3, 4, 5, 6]
}

fn get_v_vec() -> &'static [i32] {
    &vec![0, 1, 2, 3, 4, 5, 6]
}

fn main() {
  let all = sum(get_v_arr());
  let all_vec = sum(get_v_vec());
}

There is a compile error:

error[E0515]: cannot return reference to temporary value
  --> src/main.rs:10:5
   |
10 |     &vec![0, 1, 2, 3, 4, 5, 6]
   |     ^-------------------------
   |     ||
   |     |temporary value created here
   |     returns a reference to data owned by the current function

I don't think there is a way to do what we are trying to do here (create a Vec as a literal and expect it to have static lfetime) - I think this example should be edited to mention array literals only.

explanation of A1/2-move-semantics/04.rs is not understandable

I was talking with @dudo50 about solution for the exercise and we are not sure what should be a correct output

More detailed description of lecture/tutorial format

Once we've piloted a module, we should describe the lecture and tutorial formats in more detail, in order for other users of this course to get a better understanding of what we suggest is a good way to provide the content to the students.

Add content on interior mutability

Content about:

• Cell
• RefCell

Best would be to contribute it directly to the restructure branch while it's still unmerged. There's a file on that branch where the content could be added: https://github.com/tweedegolf/101-rs/blob/restructure/slides/A-foundations/interior-mutability.md