# 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/
{"metaMigratedAt":"2023-06-16T22:27:30.723Z","metaMigratedFrom":"YAML","title":"Jon Gjengset","breaks":true,"contributors":"[{\"id\":\"5dd2ddf2-aabf-43b5-a5a8-9b038ad58c15\",\"add\":10406,\"del\":5023},{\"id\":\"db349910-53c1-45a5-aa34-1ac5434980b0\",\"add\":94,\"del\":0}]"}