From bfed596d2821238239a07bf2a6e0e5dd85624db7 Mon Sep 17 00:00:00 2001 From: "Dustin J. Mitchell" Date: Fri, 10 Mar 2023 09:07:36 -0500 Subject: [PATCH] Generalize the day-4 afternoon (#487) * Generalize the day-4 afternoon This is in preparation for adding more options for this portion of the course, and reflects an existing practice of substituting other materials for this last half-day. * address review comments --- book.toml | 1 + src/SUMMARY.md | 5 ++- src/android.md | 4 ++ .../day-4/{afternoon.md => android.md} | 0 src/running-the-course.md | 45 ++++++++----------- src/running-the-course/course-structure.md | 6 +-- src/running-the-course/day-4.md | 27 +++++++++++ src/welcome-day-4.md | 14 +++--- 8 files changed, 61 insertions(+), 41 deletions(-) rename src/exercises/day-4/{afternoon.md => android.md} (100%) create mode 100644 src/running-the-course/day-4.md diff --git a/book.toml b/book.toml index b3e81ac6..c7d251d1 100644 --- a/book.toml +++ b/book.toml @@ -43,4 +43,5 @@ editable = true [output.html.redirect] "structure.html" = "running-the-course/course-structure.html" +"exercises/day-4/afternoon.html" = "exercises/day-4/android.html" "unsafe/unsafe-functions.html" = "calling-unsafe-functions.html" diff --git a/src/SUMMARY.md b/src/SUMMARY.md index e508f673..bf5800a8 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -3,6 +3,7 @@ [Welcome to Comprehensive Rust 🦀](welcome.md) - [Running the Course](running-the-course.md) - [Course Structure](running-the-course/course-structure.md) + - [Day 4](running-the-course/day-4.md) - [Keyboard Shortcuts](running-the-course/keyboard-shortcuts.md) - [Translations](running-the-course/translations.md) - [Using Cargo](cargo.md) @@ -199,7 +200,7 @@ - [Dining Philosophers](exercises/day-4/dining-philosophers.md) - [Multi-threaded Link Checker](exercises/day-4/link-checker.md) -# Day 4: Afternoon +# Day 4: Afternoon (Android) ---- @@ -222,7 +223,7 @@ - [Calling Rust from C](android/interoperability/with-c/rust.md) - [With C++](android/interoperability/cpp.md)) - [With Java](android/interoperability/java.md) -- [Exercises](exercises/day-4/afternoon.md) +- [Exercises](exercises/day-4/android.md) # Final Words diff --git a/src/android.md b/src/android.md index c0424d5c..d3066218 100644 --- a/src/android.md +++ b/src/android.md @@ -4,3 +4,7 @@ Rust is supported for native platform development on Android. This means that you can write new operating system services in Rust, as well as extending existing services. +> We will attempt to call Rust from one of your own projects today. So try to +> find a little corner of your code base where we can move some lines of code to +> Rust. The fewer dependencies and "exotic" types the better. Something that +> parses some raw bytes would be ideal. diff --git a/src/exercises/day-4/afternoon.md b/src/exercises/day-4/android.md similarity index 100% rename from src/exercises/day-4/afternoon.md rename to src/exercises/day-4/android.md diff --git a/src/running-the-course.md b/src/running-the-course.md index a2a8306f..2d0a7401 100644 --- a/src/running-the-course.md +++ b/src/running-the-course.md @@ -5,20 +5,23 @@ Here is a bit of background information about how we've been running the course internally at Google. -To run the course, you need to: +Before you run the course, you will want to: 1. Make yourself familiar with the course material. We've included speaker notes - to help highlight the key points (please help us by - contributing more speaker notes!). You should make sure to open the speaker - notes in a popup (click the link with a little arrow next to "Speaker - Notes"). This way you have a clean screen to present to the class. + to help highlight the key points (please help us by contributing more speaker + notes!). When presenting, you should make sure to open the speaker notes in a + popup (click the link with a little arrow next to "Speaker Notes"). This way + you have a clean screen to present to the class. -2. Decide on the dates. Since the course is large, we recommend that you +1. Select your topic for the afternoon of the fourth day. This may be based on + the audience you expect, or on your own expertise. + +1. Decide on the dates. Since the course is large, we recommend that you schedule the four days over two weeks. Course participants have said that they find it helpful to have a gap in the course since it helps them process all the information we give them. -3. Find a room large enough for your in-person participants. We recommend a +1. Find a room large enough for your in-person participants. We recommend a class size of 15-20 people. That's small enough that people are comfortable asking questions --- it's also small enough that one instructor will have time to answer the questions. Make sure the room has _desks_ for yourself and for the @@ -26,37 +29,27 @@ To run the course, you need to: In particular, you will be doing a lot of live-coding as an instructor, so a lectern won't be very helpful for you. -4. On the day of your course, show up to the room a little early to set things +1. On the day of your course, show up to the room a little early to set things up. We recommend presenting directly using `mdbook serve` running on your - laptop (see the [installation instructions][5]). This ensures optimal performance with no lag as you change pages. + laptop (see the [installation instructions][3]). This ensures optimal performance with no lag as you change pages. Using your laptop will also allow you to fix typos as you or the course participants spot them. -5. Let people solve the exercises by themselves or in small groups. Make sure to +1. Let people solve the exercises by themselves or in small groups. Make sure to ask people if they're stuck or if there is anything you can help with. When you see that several people have the same problem, call it out to the class and offer a solution, e.g., by showing people where to find the relevant information in the standard library. -6. If you don't skip the Android specific parts on Day 4, you will need an [AOSP - checkout][1]. Make a checkout of the [course repository][2] on the same - machine and move the `src/android/` directory into the root of your AOSP - checkout. This will ensure that the Android build system sees the - `Android.bp` files in `src/android/`. - - Ensure that `adb sync` works with your emulator or real device and pre-build - all Android examples using `src/android/build_all.sh`. Read the script to see - the commands it runs and make sure they work when you run them by hand. +1. Prepare anything you need to have available for the afternoon of day 4. That is all, good luck running the course! We hope it will be as much fun for you as it has been for us! -Please [provide feedback][3] afterwards so that we can keep improving the +Please [provide feedback][1] afterwards so that we can keep improving the course. We would love to hear what worked well for you and what can be made -better. Your students are also very welcome to [send us feedback][4]! +better. Your students are also very welcome to [send us feedback][2]! -[1]: https://source.android.com/docs/setup/download/downloading -[2]: https://github.com/google/comprehensive-rust -[3]: https://github.com/google/comprehensive-rust/discussions/86 -[4]: https://github.com/google/comprehensive-rust/discussions/100 -[5]: https://github.com/google/comprehensive-rust#building +[1]: https://github.com/google/comprehensive-rust/discussions/86 +[2]: https://github.com/google/comprehensive-rust/discussions/100 +[3]: https://github.com/google/comprehensive-rust#building diff --git a/src/running-the-course/course-structure.md b/src/running-the-course/course-structure.md index f87f1d49..4c2180f9 100644 --- a/src/running-the-course/course-structure.md +++ b/src/running-the-course/course-structure.md @@ -7,11 +7,7 @@ The course is fast paced and covers a lot of ground: * Day 1: Basic Rust, ownership and the borrow checker. * Day 2: Compound data types, pattern matching, the standard library. * Day 3: Traits and generics, error handling, testing, unsafe Rust. -* Day 4: Concurrency in Rust and interoperability with other languages - -> **Exercise for Day 4:** Do you interface with some C/C++ code in your project -> which we could attempt to move to Rust? The fewer dependencies the better. -> Parsing code would be ideal. +* Day 4: Concurrency in Rust and seeing Rust in action. ## Format diff --git a/src/running-the-course/day-4.md b/src/running-the-course/day-4.md new file mode 100644 index 00000000..0eb98dc5 --- /dev/null +++ b/src/running-the-course/day-4.md @@ -0,0 +1,27 @@ +# Day 4 + +> This page is for the course instructor. + +The afternoon of the fourth day should cover a topic of your choice. Include +the topic in the announcement of the course, so that participants know what to +expect. + +This phase of the course is a chance for participants to see Rust in action on a +codebase they might be familiar with. You can choose from the topics already +defined here, or plan your own. + +Some topics need additional preparation: + +## Android + +If you chose Android for Day 4 afternoon, you will need an [AOSP checkout][1]. +Make a checkout of the [course repository][2] on the same machine and move the +`src/android/` directory into the root of your AOSP checkout. This will ensure +that the Android build system sees the `Android.bp` files in `src/android/`. + +Ensure that `adb sync` works with your emulator or real device and pre-build +all Android examples using `src/android/build_all.sh`. Read the script to see +the commands it runs and make sure they work when you run them by hand. + +[1]: https://source.android.com/docs/setup/download/downloading +[2]: https://github.com/google/comprehensive-rust diff --git a/src/welcome-day-4.md b/src/welcome-day-4.md index a087cc81..65e00267 100644 --- a/src/welcome-day-4.md +++ b/src/welcome-day-4.md @@ -1,13 +1,11 @@ # Welcome to Day 4 -Today we will look at two main topics: +This morning, we will focus on Concurrency: threads, channels, shared state, `Send` and `Sync`. +In the afternoon, we will have a chance to see Rust in action. -* Concurrency: threads, channels, shared state, `Send` and `Sync`. +
-* Android: building binaries and libraries, using AIDL, logging, and - interoperability with C, C++, and Java. +This is a good time to give an outline of what you will cover in the afternoon +section, as announced in the course offering. -> We will attempt to call Rust from one of your own projects today. So try to -> find a little corner of your code base where we can move some lines of code to -> Rust. The fewer dependencies and "exotic" types the better. Something that -> parses some raw bytes would be ideal. +