I don't like shortening words, so I prefer "Documentation" over "Docs".
I find this less jargony and thus easier to read (and potentially also
easier to translate).
With the latest version of mdbook-i18n-helpers, we now have support for
formatting in the `SUMMARY.md` file. This allows us to revert the
changes made in #130 when we first introduced the translation support.
This also aligns a few headings to match the heading in the outline.
While this isn’t strictly necessary, it removes a bit of work for the
translators.
As more and more Android teams start using Rust, the question of "How to do mocking?" has come up more frequently. Right now, we don't have a good answer to those teams, AOSP doesn't have any mocking framework available. That will change soon with the import of Mockall and this slide is part of the supporting documentation that we can point teams to.
I've taken some work by @fw-immunant and others on the new organization
of the course and condensed it into a form amenable to a text editor and
some computational analysis. You can see the inputs in `course.py` but
the interesting bits are the output: `outline.md` and `slides.md`.
The idea is to break the course into more, smaller segments with
exercises at the ends and breaks in between. So `outline.md` lists the
segments, their duration, and sums those durations up per-day. It shows
we're about an hour too long right now! There are more details of the
segments in `slides.md`, or you can see mostly the same stuff in
`course.py`.
This now contains all of the content from the v1 course, ensuring both
that we've covered everything and that we'll have somewhere to redirect
every page.
Fixes#1082.
Fixes#1465.
---------
Co-authored-by: Nicole LeGare <dlegare.1001@gmail.com>
Co-authored-by: Martin Geisler <mgeisler@google.com>
This is a contribution of a Chromium section for Comprehensive Rust.
---------
Co-authored-by: Nicole L <dlegare.1001@gmail.com>
Co-authored-by: Martin Geisler <martin@geisler.net>
Add a number of slides that cover most of CXX's functionality and
demonstrate how it can be used.
Fixes#823.
---------
Co-authored-by: Martin Geisler <mgeisler@google.com>
The goal of this is twofold: give translators a place to document how
certain terms are translated as well as giving people a place to quickly
find a definition of a term. The slides might not always give a quick
definition the same way a glossary can.
This example shows what kind of bugs easily slip into C code and are
made impossible via Rust.
I have created this example for the motivation slides of my master
thesis. Since then, the university institute has used it in their
introduction to Rust.
I hereby make this part available to the Comprehensive Rust course and
relicense it under the terms of the Apache 2.0 license.
Thank you @mgeisler for your invitation to contribute to this course!
---------
Co-authored-by: Martin Geisler <martin@geisler.net>
This is a follow-up to #998 and the discussion in #1049. The
comparison page is now gone: like @randomPoison said, it feels
redundant and I also mostly skip over it when teaching the class.
I also took out some duplication in the Rust memory management page. I
would be up for simplifying the whole chapter down to one or two
slides as @djmitche suggests: that would leave us with more time for
covering ownership.
- Morning of Day 1 still introduces the language and its high-level
goals/value proposition, and starts with the built-in data types Rust
provides, and how you define a function.
- Afternoon of Day 1 gets a front loading of the basic control flow
structures in Rust but not the more exotic ones.
- The exercises for day 1 afternoon will be the Luhn algorithm (where we
can match on digits and enums such as `Option`.
- Morning of day 2 still has discussion of memory management.
Fixes#510.
---------
Co-authored-by: Martin Geisler <mgeisler@google.com>
When building the book, mdBook will always generate an `index.html`
page for first page of the book. This meant that we had the same
content available under two different names:
- `welcome.html`: this is what the TOC would link to, and
- `index.html` or simply `/`: this is what search engines link to
Renaming the page and setting up a redirect should fix this confusion.
We still don’t have a good way of avoiding links to the `index.html`
page, but this should fix the first half of the problem.
I tested this for translations as well by building the output in a
subdirectory and serving the parent directory.
Part of #847.
rename 'designing a library' example
library design in Rust is its own topic that this course does not cover; to avoid confusion, let's stick to describing things in terms of books
* Add page about entry point before Rust code.
* Convert tabs to spaces.
mdbook doesn't seem to handle tabs in code properly.
* Add page about handling exceptions.
* More nuanced discussion of Rust Raspberry Pi OS tutorial.
* Add note about EL1 to entry point page too.
* Mention cancellation via select!
* Add a section on async cancellation
* Update cancellation slide, rework example
* Rework select! note about cancellation
* Collapse cancellation comparision to panic and ?
* Don't keep null bytes from incomplete reads
* Adds a description of the async chat exercise
* Simplifies the use of Error in chat-async
* Links the solution to the async chat exercise
* Removes the elevator exercise
* Adds dining philosophers as an async exercise
* Adds a solution for async dining philosophers
* Adds a solution page for the afternoon session on concurrency
The Arc/Mutex chapters mention Send/Sync in the speaker notes, and in
fact serve as good illustrations of the traits, so let's define the
traits before referencing them.
* Align outline with new spin-off course structure
With the new structure, the section on Android is a spin-off course
from the main 3-day course on Rust Fundamentals. The Bare-metal and
Concurrency days are spin-off courses in the same way.
* Explain new course structure
* Align Bare-Metal welcome page with other deep dives
* Merge Day 4 page into Course Structure page
* Remove Day 4 Welcome page
This aligns the Concurrency in Rust section with the Bare-Metal Rust
deep dive.
* Show subsections for Android deep dive
This aligns the Rust in Android section with the other deep dives.
* Clean up welcome page and README
We now cover async Rust and the course is no longer a four day course.
* Remove reference to the old Day 4
* Remove Day 4 references from exercises
* beginning of an Async section
* address review comments
* Add futures page (#497)
NOTE: `mdbook test` does not allow code samples to reference other crates, so
they must be marked as `compile_fail`; see #175.
* Add Runtimes & Tasks (#522)
These concepts are closely related, and there's not much else to know
about runtimes other than "they exist".
This removes the bit about futures being "inert" because it doesn't
really lead anywhere.
* Async chapter (#524)
* Add async channels chapter
* Async control flow
* Async pitfalls
* Separate in multiple chapters + add daemon section
* Merge reentering threads in blocking-executor
* async_trait
* Async fixes (#546)
* Async: some ideas for simplifying the content (#550)
* Simplify the async-await slide
* Shorten futures and move it up
* Add a page on Tokio
* Modifications to the async section (#556)
* Modifications to the async section
* Remove the "Daemon" slide, as it largely duplicates the "Tasks" slide.
The introduction to the "Control Flow" section mentions tasks as a
kind of control flow.
* Reorganize the structure in SUMMARY.md to correspond to the directory
structure.
* Simplify the "Pin" and "Blocking the Executor" slides with steps in
the speaker notes to demonstrate / fix the issues.
* Rename "join_all" to "Join".
* Simplify some code samples to shorten them, and to print output rather
than asserting.
* Clarify speaker notes and include more "Try.." suggestions.
* Be consistent about where `async` blocks are introduced (in the
"Tasks" slide).
* Explain `join` and `select` in prose.
* Fix formatting of section-header slides.
* Add a note on async trait (#558)
---------
Co-authored-by: sakex <alexandre@senges.ch>
Co-authored-by: rbehjati <razieh@google.com>
