Merge pull request #128 from google/speaker-notes

Add speaker notes for the first few slides

Author: mgeisler

src/cargo/code-samples.md

@@ -18,3 +18,18 @@ fn main() {
 
 You can use <kbd>Ctrl-Enter</kbd> to execute the code when focus is in the text
 box.
+
+<details>
+
+Most code samples are editable like shown above. A few code samples
+are not editable for various reasons:
+
+* The embedded playgrounds cannot execute unit tests. Copy-paste the
+  code and open it in the real Playground to demonstrate unit tests.
+
+* The embedded playgrounds lose their state the moment you navigate
+  away from the page! This is the reason that the students should
+  solve the exercises using a local Rust installation or via the
+  Playground.
+
+</details>

src/cargo/running-locally.md

@@ -64,3 +64,11 @@ of the examples in this training:
    dependencies for you.
 
 [1]: https://doc.rust-lang.org/book/ch01-01-installation.html
+
+<details>
+
+Try to encourage the class participants to install Cargo and use a
+local editor. It will make their life easier since they will have a
+normal development environment.
+
+</details>

src/cargo/rust-ecosystem.md

@@ -15,3 +15,32 @@ The Rust ecosystem consists of a number of tools, of which the main ones are:
   In addition, `rustup` can also download documentation for the standard
   library. You can have multiple versions of Rust installed at once and `rustup`
   will let you switch between them as needed.
+
+<details>
+
+Key points:
+
+* Rust has a rapid release schedule with a new release coming out
+  every six weeks. New releases maintain backwards compatibility with
+  old releases --- plus they enable new functionality.
+
+* There are three release channels: "stable", "beta", and "nightly".
+
+* New features are being tested on "nightly", "beta" is what becomes
+  "stable" every six weeks.
+
+* Rust also has [editions]: the current edition is Rust 2021. Previous
+  editions were Rust 2015 and Rust 2018.
+
+  * The editions are allowed to make backwards incompatible changes to
+    the language.
+
+  * To prevent breaking code, editions are opt-in: you select the
+    edition for your crate via the `Cargo.toml` file.
+
+  * To avoid splitting the ecosystem, Rust compilers can mix code
+    written for different editions.
+
+[editions]: https://doc.rust-lang.org/edition-guide/
+
+</details>

src/welcome.md

@@ -42,3 +42,11 @@ explain or contrast the Rust approach.
 
 If you know how to program in a dynamically typed language such as Python or
 JavaScript, then you will be able to follow along just fine too.
+
+<details>
+
+This is an example of a _speaker note_. We will use these to add additional
+information to the slides. This could be key points which the instructor should
+cover as well as answers to typical questions which come up in class.
+
+</details>

src/why-rust.md

@@ -5,3 +5,20 @@ Some unique selling points of Rust:
 * Compile time memory safety.
 * Lack of undefined runtime behavior.
 * Modern language features.
+
+<details>
+
+Make sure to ask the class which languages they have experience with. Depending
+on the answer you can highlight different features of Rust:
+
+* Experience with C or C++: Rust eliminates a whole class of _runtime errors_
+  via the borrow checker. You get performance like in C and C++, but you don't
+  have the memory unsafety issues. In addition, you get a modern language with
+  constructs like pattern matching and built-in dependency management.
+
+* Experience with Java, Go, Python, JavaSript...: You get the same memory safety
+  as in those languages, plus a similar high-level language feeling. In addition
+  you get fast and predictable performance like C and C++ (no garbage collector)
+  as well as access to low-level hardware (should you need it)
+
+</details>

src/why-rust/compile-time.md

@@ -3,12 +3,31 @@
 Static memory management at compile time:
 
 * No uninitialized variables.
-* *Mostly* no memory leaks[^leaks].
+* No memory leaks (_mostly_, see notes).
 * No double-frees.
 * No use-after-free.
 * No `NULL` pointers.
 * No forgotten locked mutexes.
 * No data races between threads.
 * No iterator invalidation.
 
-[^leaks]: It is technically possible to produce a memory leak in (safe) Rust. The [`Box::leak`](https://doc.rust-lang.org/std/boxed/struct.Box.html#method.leak) method allows getting a raw reference out of a [`Box`](https://doc.rust-lang.org/std/boxed/struct.Box.html) and dropping the [`Box`](https://doc.rust-lang.org/std/boxed/struct.Box.html) afterwards, without running the destructor. A use of this could be to get runtime-initialized and runtime-sized static variables. Or simply, the [`std::mem::forget`](https://doc.rust-lang.org/std/mem/fn.forget.html) function, which makes the compiler "forget" about a value meaning the destructor is never run. There are many other ways to create leaks in safe Rust, but for the purpose of this course, "No memory leaks" should be understood as "Pretty much no *accidental* memory leaks".
+<details>
+
+It is possible to produce memory leaks in (safe) Rust. Some examples
+are:
+
+* You can for use [`Box::leak`] to leak a pointer. A use of this could
+  be to get runtime-initialized and runtime-sized static variables
+* You can use [`std::mem::forget`] to make the compiler "forget" about
+  a value (meaning the destructor is never run).
+* You can also accidentally create a [reference cycle] with `Rc` or
+  `Arc`.
+
+For the purpose of this course, "No memory leaks" should be understood
+as "Pretty much no *accidental* memory leaks".
+
+[`Box::leak`]: https://doc.rust-lang.org/std/boxed/struct.Box.html#method.leak
+[`std::mem::forget`]: https://doc.rust-lang.org/std/mem/fn.forget.html
+[reference cycle]: https://doc.rust-lang.org/book/ch15-06-reference-cycles.html
+
+</details>

src/why-rust/modern.md

@@ -13,3 +13,39 @@ Rust is built with all the experience gained in the last 40 years.
 * Great compiler errors.
 * Built-in dependency manager.
 * Built-in support for testing.
+
+<details>
+
+Key points:
+
+* Remind people to read the errors --- many developers have gotten used to
+  ignore lengthly compiler output. The Rust compiler is significantly more
+  talkative than other compilers. It will often provide you with _actionable_
+  feedback, ready to copy-paste into your code.
+
+* The Rust standard library is small compared to languages like Java, Python,
+  and Go. Rust does not come with several things you might consider standard and
+  essential:
+
+  * a random number generator, but see [rand].
+  * support for SSL or TLS, but see [rusttls].
+  * support for JSON, but see [serde_json].
+
+  The reasoning behind this is that functionality in the standard library cannot
+  go away, so it has to be very stable. For the examples above, the Rust
+  community is still working on finding the best solution --- and perhaps there
+  isn't a single "best solution" for some of these things.
+
+  Rust comes with a built-in package manager in the form of Cargo and this makes
+  it trivial to download and compile third-party crates. A consequence of this
+  is that the standard library can be smaller.
+
+  Discovering good third-party crates can be a problem. Sites like
+  <https://lib.rs/> help with this by letting you compare health metrics for
+  crates to find a good and trusted one.
+
+[rand]: https://docs.rs/rand/
+[rusttls]: https://docs.rs/rustls/
+[serde_json]: https://docs.rs/serde_json/
+
+</details>

src/why-rust/runtime.md

@@ -4,3 +4,19 @@ No undefined behavior at runtime:
 
 * Array access is bounds checked.
 * Integer overflow is defined.
+
+<details>
+
+Key points:
+
+* Integer overflow is defined via a compile-time flag. The options are
+  either a panic (a controlled crash of the program) or wrap-around
+  semantics. By default, you get panics in debug mode (`cargo build`)
+  and wrap-around in release mode (`cargo build --release`).
+
+* Bounds checking cannot be disabled with a compiler flag. It can also
+  not be disabled directly with the `unsafe` keyword. However,
+  `unsafe` allows you to call functions such as `slice::get_unchecked`
+  which does not do bounds checking.
+
+</details>