---
tags: "2022-04-18"
title: "Jon Gjengset"
type: slidehttps://rust-lang.zulipchat.com/#narrow/stream/286036-ctcft
---

# Teaching Intermediate Rust

Jon Gjengset ([@jonhoo](https://twitter.com/jonhoo))

----

## Who am I?

- I wrote [_Rust for Rustaceans_](https://rust-for-rustaceans.com/),
a book intended to follow the Rust book.
- I do live Rust programming [on YouTube](https://www.youtube.com/c/JonGjengset).
- I maintain the Rust build tooling at AWS.

----

## Why am I giving this talk?

I've tried to teach intermediate Rust for years

and

I field a lot of questions from Rust developers.

---

# Let's go!

---

## Where do I look things up/ask?

----

There's doc.rust-lang.org, docs.rs, [rustc dev guide](https://rustc-dev-guide.rust-lang.org/), [nomicon](https://doc.rust-lang.org/nomicon/), [cargo book](https://doc.rust-lang.org/cargo/), [macro book](https://veykril.github.io/tlborm/), [embedded book(s)](https://docs.rust-embedded.org/), [cheats.rs](https://cheats.rs/), [rust by example](https://doc.rust-lang.org/stable/rust-by-example/), [rust cookbook](https://rust-lang-nursery.github.io/rust-cookbook/), [rust patterns](https://rust-unofficial.github.io/patterns/), [rust api guidelines](https://rust-lang.github.io/api-guidelines/), [the book](https://doc.rust-lang.org/book/), StackOverflow, users.r-l.o, internals.r-l.o, Reddit, Discord(s), Twitter.

(and email/DM Jon..)

----

Great to have many avenues.

Very hard to navigate and discover!

----

There are some resources that try to organize this info, like [the book of rust books](https://lborb.github.io/book/), [rust learning](https://github.com/ctjhoa/rust-learning), [awesome rust](https://github.com/rust-unofficial/awesome-rust), and [awesome rust mentors](https://rustbeginners.github.io/awesome-rust-mentors/).

But those are themselves hard to find.
And all suffer from the "giant list" problem.

Can we do better?

---

## Papercuts inhibit learning

----

"Known shortcomings" aren't too bad if you know.

But they're _extremely_ confusing otherwise.

Suggests your mental model is wrong _when it isn't_.

**Makes people give up.**

----

### Some examples
- Closure argument types: [#41078](https://github.com/rust-lang/rust/issues/41078)
- Borrow and early return: [#54663](https://github.com/rust-lang/rust/issues/54663)
- FnDef vs fn: [#86654](https://github.com/rust-lang/rust/issues/86654)
- Arguably also:
- [Trait aliases](https://github.com/rust-lang/rust/issues/41517)
- [GAT](https://github.com/rust-lang/rust/issues/44265)
- [TAIT](https://github.com/rust-lang/rust/issues/63063)

---

## Choices are hard

----

Arguably fundamental, but a major stumbling block

- `Rc` vs `Arc`
- `Mutex` vs `RefCell` vs `Cell`
- `usize` vs `isize` vs `NonZeroI32` vs ..
- tokio vs async-std vs smol vs glommio vs ..
- anyhow vs thiserror vs eyre vs miette vs ..
- clap vs pico-args vs argh vs gumdrop vs ..
- chrono vs time
- regex vs ???
- rand vs ???

----

Can, to some extent, be fixed with docs that explicitly show differences (tables are nice).

Can we encourage that somehow?

----

How do we teach "how to choose"?

---

## Cargo is a growing concern

----

As Rust gets better, Cargo pains become more visible.

Sometimes known limitations or poor diagnostics.

Often simply lack of knowledge!

----

No one reads the Cargo book.

Few even know it exists.

----

### Some examples

- Feature merging (no mutual exclusion)
- Build scripts esp. with native dependencies
- `cc`? `pkg_config`?
- `git submodule`? Vendor?
- Intra-workspace dependencies
- `default-features = false`
- How rustflags are (and aren't) propagated

----

Diagnostics could help with many of these.

Clippy for Cargo!

---

## unsafe remains unclear

----

Everyone is either too scared,
or not scared enough.

----

Constantly changing ground
(e.g., strict provenance).

The rules are under- or undocumented.

[Unsafe Code Guidelines WG](https://rust-lang.github.io/unsafe-code-guidelines/) progress is slow.

----

Established conventions might help.

Always `/// # Safety` and `// safety:`.
Can we formalize as part of the language?

----

Miri is great, but
1. analysis is limited without `-Z` flags
2. only checks the tests you wrote
3. nightly-only is a problem

----

Should work hard to stabilize unsafe-removing fns.

(e.g., `[T; N]::each_mut`)

---

## Quick-fire round

----

### Survey should ask what's hard

We need _data_.

Ask what users do not understand
or _later realized they misunderstood_.

----

### What is a breaking change?

Not centrally documented, just lots of RFC.

(esp. [private dependencies](https://github.com/rust-lang/rust/issues/44663))

----

### Docs should explain _why_

Developers don't "believe" necessity claims.

Must _show_ why `Send`/`Sync`/`'static`/etc. matter.
Give _concrete counter-examples_.

Does anyone read `--explain`?
Can they be repeated in docs?

----

### Procedural macro docs are lacking

Need end-to-end examples.

----

### Ecosystem-wide search

(e.g., https://www.rdocumentation.org/)

----

### Understanding slow builds

`--timings` is great, but incomplete
(e.g., which proc macros, time spent linking)

----

### Unstable feature status

Tracking issues should say what's blocking.

---

## Conclusion

Resources need organizing.

Papercuts need fixing.

Choices need comparisons.

Cargo needs love.

unsafe needs rules.

---

## See also

https://www.reddit.com/r/rust/comments/rjjwpd/uncovered_intermediate_topics/