rust/comprehensive-rust
1
0
Fork 0
mirror of https://github.com/google/comprehensive-rust.git synced 2025-03-24 23:31:56 +02:00
Code Issues Releases Activity
comprehensive-rust/src/index.md

72 lines
3.3 KiB
Markdown
Raw Normal View History

Publish Comprehensive Rust 🦀
2022-12-21 16:36:30 +01:00
# Welcome to Comprehensive Rust 🦀
Link badges to the `main` branch (#636) This is the only branch for which there is any expectation of stability, so it makes sense to send people here.
2023-05-16 00:12:10 +02:00
[![Build workflow](https://img.shields.io/github/actions/workflow/status/google/comprehensive-rust/build.yml?style=flat-square)](https://github.com/google/comprehensive-rust/actions/workflows/build.yml?query=branch%3Amain)
Add badges to README and welcome page (#481)
2023-03-07 13:45:00 +01:00
[![GitHub contributors](https://img.shields.io/github/contributors/google/comprehensive-rust?style=flat-square)](https://github.com/google/comprehensive-rust/graphs/contributors)
[![GitHub stars](https://img.shields.io/github/stars/google/comprehensive-rust?style=flat-square)](https://github.com/google/comprehensive-rust/stargazers)
Format all Markdown files with `dprint` (#1157) This is the result of running `dprint fmt` after removing `src/` from the list of excluded directories. This also reformats the Rust code: we might want to tweak this a bit in the future since some of the changes removes the hand-formatting. Of course, this formatting can be seen as a mis-feature, so maybe this is good overall. Thanks to mdbook-i18n-helpers 0.2, the POT file is nearly unchanged after this, meaning that all existing translations remain valid! A few messages were changed because of stray whitespace characters: msgid "" "Slices always borrow from another object. In this example, `a` has to remain " -"'alive' (in scope) for at least as long as our slice. " +"'alive' (in scope) for at least as long as our slice." msgstr "" The formatting is enforced in CI and we will have to see how annoying this is in practice for the many contributors. If it becomes annoying, we should look into fixing dprint/check#11 so that `dprint` can annotate the lines that need fixing directly, then I think we can consider more strict formatting checks. I added more customization to `rustfmt.toml`. This is to better emulate the dense style used in the course: - `max_width = 85` allows lines to take up the full width available in our code blocks (when taking margins and the line numbers into account). - `wrap_comments = true` ensures that we don't show very long comments in the code examples. I edited some comments to shorten them and avoid unnecessary line breaks — please trim other unnecessarily long comments when you see them! Remember we're writing code for slides :smile: - `use_small_heuristics = "Max"` allows for things like struct literals and if-statements to take up the full line width configured above. The formatting settings apply to all our Rust code right now — I think we could improve this with https://github.com/dprint/dprint/issues/711 which lets us add per-directory `dprint` configuration files. However, the `inherit: true` setting is not yet implemented (as far as I can tell), so a nested configuration file will have to copy most or all of the top-level file.
2023-12-31 00:15:07 +01:00
This is a free Rust course developed by the Android team at Google. The course
covers the full spectrum of Rust, from basic syntax to advanced topics like
generics and error handling.
Publish Comprehensive Rust 🦀
2022-12-21 16:36:30 +01:00
Add a link back to the canonical home (#1141) This is a follow-up to #1140 to further ensure that people can find the canonical home for the course.
2023-08-31 09:46:22 +02:00
> The latest version of the course can be found at
Format all Markdown files with `dprint` (#1157) This is the result of running `dprint fmt` after removing `src/` from the list of excluded directories. This also reformats the Rust code: we might want to tweak this a bit in the future since some of the changes removes the hand-formatting. Of course, this formatting can be seen as a mis-feature, so maybe this is good overall. Thanks to mdbook-i18n-helpers 0.2, the POT file is nearly unchanged after this, meaning that all existing translations remain valid! A few messages were changed because of stray whitespace characters: msgid "" "Slices always borrow from another object. In this example, `a` has to remain " -"'alive' (in scope) for at least as long as our slice. " +"'alive' (in scope) for at least as long as our slice." msgstr "" The formatting is enforced in CI and we will have to see how annoying this is in practice for the many contributors. If it becomes annoying, we should look into fixing dprint/check#11 so that `dprint` can annotate the lines that need fixing directly, then I think we can consider more strict formatting checks. I added more customization to `rustfmt.toml`. This is to better emulate the dense style used in the course: - `max_width = 85` allows lines to take up the full width available in our code blocks (when taking margins and the line numbers into account). - `wrap_comments = true` ensures that we don't show very long comments in the code examples. I edited some comments to shorten them and avoid unnecessary line breaks — please trim other unnecessarily long comments when you see them! Remember we're writing code for slides :smile: - `use_small_heuristics = "Max"` allows for things like struct literals and if-statements to take up the full line width configured above. The formatting settings apply to all our Rust code right now — I think we could improve this with https://github.com/dprint/dprint/issues/711 which lets us add per-directory `dprint` configuration files. However, the `inherit: true` setting is not yet implemented (as far as I can tell), so a nested configuration file will have to copy most or all of the top-level file.
2023-12-31 00:15:07 +01:00
> <https://google.github.io/comprehensive-rust/>. If you are reading somewhere
> else, please check there for updates.
Link to PDF version of course from first page (#1836) Re https://github.com/google/comprehensive-rust/pull/1805#pullrequestreview-1888804528 --------- Co-authored-by: Martin Geisler <martin@geisler.net>
2024-02-26 07:24:28 -05:00
>
Update index.md with language selection instructions and translations link (#2131)
2024-06-25 06:45:04 -07:00
> The course is available in other languages. Select your preferred language in
> the top right corner of the page or check the
> [Translations](running-the-course/translations.md) page for a list of all
> available translations.
>
Link to PDF version of course from first page (#1836) Re https://github.com/google/comprehensive-rust/pull/1805#pullrequestreview-1888804528 --------- Co-authored-by: Martin Geisler <martin@geisler.net>
2024-02-26 07:24:28 -05:00
> The course is also available [as a PDF](comprehensive-rust.pdf).
Add a link back to the canonical home (#1141) This is a follow-up to #1140 to further ensure that people can find the canonical home for the course.
2023-08-31 09:46:22 +02:00
Corrected 1 or 2 typos missing verb : "The goal of the course to teach you Rust." -> "The goal of the course is to teach you Rust." missing of ? : "to cover all it" -> "to cover all of it" for this one, I'm not a native english speaker but it seems more correct to me. I'll let you check :)
2022-12-22 18:33:02 +01:00
The goal of the course is to teach you Rust. We assume you don't know anything
Adding colon punctuation to lists Minor addition to make punctuation consistent on Welcome page
2022-12-21 09:20:30 -08:00
about Rust and hope to:
Publish Comprehensive Rust 🦀
2022-12-21 16:36:30 +01:00
Format all Markdown files with `dprint` (#1157) This is the result of running `dprint fmt` after removing `src/` from the list of excluded directories. This also reformats the Rust code: we might want to tweak this a bit in the future since some of the changes removes the hand-formatting. Of course, this formatting can be seen as a mis-feature, so maybe this is good overall. Thanks to mdbook-i18n-helpers 0.2, the POT file is nearly unchanged after this, meaning that all existing translations remain valid! A few messages were changed because of stray whitespace characters: msgid "" "Slices always borrow from another object. In this example, `a` has to remain " -"'alive' (in scope) for at least as long as our slice. " +"'alive' (in scope) for at least as long as our slice." msgstr "" The formatting is enforced in CI and we will have to see how annoying this is in practice for the many contributors. If it becomes annoying, we should look into fixing dprint/check#11 so that `dprint` can annotate the lines that need fixing directly, then I think we can consider more strict formatting checks. I added more customization to `rustfmt.toml`. This is to better emulate the dense style used in the course: - `max_width = 85` allows lines to take up the full width available in our code blocks (when taking margins and the line numbers into account). - `wrap_comments = true` ensures that we don't show very long comments in the code examples. I edited some comments to shorten them and avoid unnecessary line breaks — please trim other unnecessarily long comments when you see them! Remember we're writing code for slides :smile: - `use_small_heuristics = "Max"` allows for things like struct literals and if-statements to take up the full line width configured above. The formatting settings apply to all our Rust code right now — I think we could improve this with https://github.com/dprint/dprint/issues/711 which lets us add per-directory `dprint` configuration files. However, the `inherit: true` setting is not yet implemented (as far as I can tell), so a nested configuration file will have to copy most or all of the top-level file.
2023-12-31 00:15:07 +01:00
- Give you a comprehensive understanding of the Rust syntax and language.
- Enable you to modify existing programs and write new programs in Rust.
- Show you common Rust idioms.
Publish Comprehensive Rust 🦀
2022-12-21 16:36:30 +01:00
Comprehensive Rust v2 (#1073) 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>
2023-11-29 10:39:24 -05:00
We call the first four course days Rust Fundamentals.
Introduce Rust Fundamentals on welcome page (#1029) The split between Day 1 to 3 and the deep dives was never explicitly explained.
2023-07-25 15:04:32 +02:00
Building on this, you're invited to dive into one or more specialized topics:
Publish Comprehensive Rust 🦀
2022-12-21 16:36:30 +01:00
Format all Markdown files with `dprint` (#1157) This is the result of running `dprint fmt` after removing `src/` from the list of excluded directories. This also reformats the Rust code: we might want to tweak this a bit in the future since some of the changes removes the hand-formatting. Of course, this formatting can be seen as a mis-feature, so maybe this is good overall. Thanks to mdbook-i18n-helpers 0.2, the POT file is nearly unchanged after this, meaning that all existing translations remain valid! A few messages were changed because of stray whitespace characters: msgid "" "Slices always borrow from another object. In this example, `a` has to remain " -"'alive' (in scope) for at least as long as our slice. " +"'alive' (in scope) for at least as long as our slice." msgstr "" The formatting is enforced in CI and we will have to see how annoying this is in practice for the many contributors. If it becomes annoying, we should look into fixing dprint/check#11 so that `dprint` can annotate the lines that need fixing directly, then I think we can consider more strict formatting checks. I added more customization to `rustfmt.toml`. This is to better emulate the dense style used in the course: - `max_width = 85` allows lines to take up the full width available in our code blocks (when taking margins and the line numbers into account). - `wrap_comments = true` ensures that we don't show very long comments in the code examples. I edited some comments to shorten them and avoid unnecessary line breaks — please trim other unnecessarily long comments when you see them! Remember we're writing code for slides :smile: - `use_small_heuristics = "Max"` allows for things like struct literals and if-statements to take up the full line width configured above. The formatting settings apply to all our Rust code right now — I think we could improve this with https://github.com/dprint/dprint/issues/711 which lets us add per-directory `dprint` configuration files. However, the `inherit: true` setting is not yet implemented (as far as I can tell), so a nested configuration file will have to copy most or all of the top-level file.
2023-12-31 00:15:07 +01:00
- [Android](android.md): a half-day course on using Rust for Android platform
Fixing some typos (#667) fix some typos
2023-05-24 11:15:08 +03:00
development (AOSP). This includes interoperability with C, C++, and Java.
Format all Markdown files with `dprint` (#1157) This is the result of running `dprint fmt` after removing `src/` from the list of excluded directories. This also reformats the Rust code: we might want to tweak this a bit in the future since some of the changes removes the hand-formatting. Of course, this formatting can be seen as a mis-feature, so maybe this is good overall. Thanks to mdbook-i18n-helpers 0.2, the POT file is nearly unchanged after this, meaning that all existing translations remain valid! A few messages were changed because of stray whitespace characters: msgid "" "Slices always borrow from another object. In this example, `a` has to remain " -"'alive' (in scope) for at least as long as our slice. " +"'alive' (in scope) for at least as long as our slice." msgstr "" The formatting is enforced in CI and we will have to see how annoying this is in practice for the many contributors. If it becomes annoying, we should look into fixing dprint/check#11 so that `dprint` can annotate the lines that need fixing directly, then I think we can consider more strict formatting checks. I added more customization to `rustfmt.toml`. This is to better emulate the dense style used in the course: - `max_width = 85` allows lines to take up the full width available in our code blocks (when taking margins and the line numbers into account). - `wrap_comments = true` ensures that we don't show very long comments in the code examples. I edited some comments to shorten them and avoid unnecessary line breaks — please trim other unnecessarily long comments when you see them! Remember we're writing code for slides :smile: - `use_small_heuristics = "Max"` allows for things like struct literals and if-statements to take up the full line width configured above. The formatting settings apply to all our Rust code right now — I think we could improve this with https://github.com/dprint/dprint/issues/711 which lets us add per-directory `dprint` configuration files. However, the `inherit: true` setting is not yet implemented (as far as I can tell), so a nested configuration file will have to copy most or all of the top-level file.
2023-12-31 00:15:07 +01:00
- [Chromium](chromium.md): a half-day course on using Rust within Chromium based
browsers. This includes interoperability with C++ and how to include
Add Chromium section (#1479) 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>
2023-11-27 18:21:19 +00:00
third-party crates in Chromium.
Format all Markdown files with `dprint` (#1157) This is the result of running `dprint fmt` after removing `src/` from the list of excluded directories. This also reformats the Rust code: we might want to tweak this a bit in the future since some of the changes removes the hand-formatting. Of course, this formatting can be seen as a mis-feature, so maybe this is good overall. Thanks to mdbook-i18n-helpers 0.2, the POT file is nearly unchanged after this, meaning that all existing translations remain valid! A few messages were changed because of stray whitespace characters: msgid "" "Slices always borrow from another object. In this example, `a` has to remain " -"'alive' (in scope) for at least as long as our slice. " +"'alive' (in scope) for at least as long as our slice." msgstr "" The formatting is enforced in CI and we will have to see how annoying this is in practice for the many contributors. If it becomes annoying, we should look into fixing dprint/check#11 so that `dprint` can annotate the lines that need fixing directly, then I think we can consider more strict formatting checks. I added more customization to `rustfmt.toml`. This is to better emulate the dense style used in the course: - `max_width = 85` allows lines to take up the full width available in our code blocks (when taking margins and the line numbers into account). - `wrap_comments = true` ensures that we don't show very long comments in the code examples. I edited some comments to shorten them and avoid unnecessary line breaks — please trim other unnecessarily long comments when you see them! Remember we're writing code for slides :smile: - `use_small_heuristics = "Max"` allows for things like struct literals and if-statements to take up the full line width configured above. The formatting settings apply to all our Rust code right now — I think we could improve this with https://github.com/dprint/dprint/issues/711 which lets us add per-directory `dprint` configuration files. However, the `inherit: true` setting is not yet implemented (as far as I can tell), so a nested configuration file will have to copy most or all of the top-level file.
2023-12-31 00:15:07 +01:00
- [Bare-metal](bare-metal.md): a whole-day class on using Rust for bare-metal
Cleanup references to "Day 4" (#603) * 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
2023-05-02 08:02:28 +02:00
(embedded) development. Both microcontrollers and application processors are
covered.
Fix a broken link and check internal links (#2195) In #2153 I aimed to fix a link but broke it. In this PR, I fix it and add [`mdbook-linkcheck`](https://github.com/Michael-F-Bryan/mdbook-linkcheck) to avoid future cases. Some past fixes that could have been prevented, in addition to mine in this PR: * #811 * #2064 * #2146 Note: `mdbook-linkcheck` may also check external links with a configuration change. It can be beneficial to check also external links from time to time. I ran it here and found 3 broken links. Maintainers - sorry for the lack of a preceding issue. We can discuss it here. Some remaining work is to fix the outdated internal links in the translations, not done here. Let me know what you think about the proposed contribution. This PR completes #1502.
2024-07-22 14:37:19 +03:00
- [Concurrency](concurrency/welcome.md): a whole-day class on concurrency in
Rust. We cover both classical concurrency (preemptively scheduling using
threads and mutexes) and async/await concurrency (cooperative multitasking
using futures).
Precise what the Android parts are about (fixes #56)
2022-12-25 17:12:42 +01:00
Publish Comprehensive Rust 🦀
2022-12-21 16:36:30 +01:00
## Non-Goals
Corrected 1 or 2 typos missing verb : "The goal of the course to teach you Rust." -> "The goal of the course is to teach you Rust." missing of ? : "to cover all it" -> "to cover all of it" for this one, I'm not a native english speaker but it seems more correct to me. I'll let you check :)
2022-12-22 18:33:02 +01:00
Rust is a large language and we won't be able to cover all of it in a few days.
Publish Comprehensive Rust 🦀
2022-12-21 16:36:30 +01:00
Some non-goals of this course are:
Format all Markdown files with `dprint` (#1157) This is the result of running `dprint fmt` after removing `src/` from the list of excluded directories. This also reformats the Rust code: we might want to tweak this a bit in the future since some of the changes removes the hand-formatting. Of course, this formatting can be seen as a mis-feature, so maybe this is good overall. Thanks to mdbook-i18n-helpers 0.2, the POT file is nearly unchanged after this, meaning that all existing translations remain valid! A few messages were changed because of stray whitespace characters: msgid "" "Slices always borrow from another object. In this example, `a` has to remain " -"'alive' (in scope) for at least as long as our slice. " +"'alive' (in scope) for at least as long as our slice." msgstr "" The formatting is enforced in CI and we will have to see how annoying this is in practice for the many contributors. If it becomes annoying, we should look into fixing dprint/check#11 so that `dprint` can annotate the lines that need fixing directly, then I think we can consider more strict formatting checks. I added more customization to `rustfmt.toml`. This is to better emulate the dense style used in the course: - `max_width = 85` allows lines to take up the full width available in our code blocks (when taking margins and the line numbers into account). - `wrap_comments = true` ensures that we don't show very long comments in the code examples. I edited some comments to shorten them and avoid unnecessary line breaks — please trim other unnecessarily long comments when you see them! Remember we're writing code for slides :smile: - `use_small_heuristics = "Max"` allows for things like struct literals and if-statements to take up the full line width configured above. The formatting settings apply to all our Rust code right now — I think we could improve this with https://github.com/dprint/dprint/issues/711 which lets us add per-directory `dprint` configuration files. However, the `inherit: true` setting is not yet implemented (as far as I can tell), so a nested configuration file will have to copy most or all of the top-level file.
2023-12-31 00:15:07 +01:00
- Learning how to develop macros: please see
[Chapter 19.5 in the Rust Book](https://doc.rust-lang.org/book/ch19-06-macros.html)
and [Rust by Example](https://doc.rust-lang.org/rust-by-example/macros.html)
instead.
Publish Comprehensive Rust 🦀
2022-12-21 16:36:30 +01:00
## Assumptions
Format all Markdown files with `dprint` (#1157) This is the result of running `dprint fmt` after removing `src/` from the list of excluded directories. This also reformats the Rust code: we might want to tweak this a bit in the future since some of the changes removes the hand-formatting. Of course, this formatting can be seen as a mis-feature, so maybe this is good overall. Thanks to mdbook-i18n-helpers 0.2, the POT file is nearly unchanged after this, meaning that all existing translations remain valid! A few messages were changed because of stray whitespace characters: msgid "" "Slices always borrow from another object. In this example, `a` has to remain " -"'alive' (in scope) for at least as long as our slice. " +"'alive' (in scope) for at least as long as our slice." msgstr "" The formatting is enforced in CI and we will have to see how annoying this is in practice for the many contributors. If it becomes annoying, we should look into fixing dprint/check#11 so that `dprint` can annotate the lines that need fixing directly, then I think we can consider more strict formatting checks. I added more customization to `rustfmt.toml`. This is to better emulate the dense style used in the course: - `max_width = 85` allows lines to take up the full width available in our code blocks (when taking margins and the line numbers into account). - `wrap_comments = true` ensures that we don't show very long comments in the code examples. I edited some comments to shorten them and avoid unnecessary line breaks — please trim other unnecessarily long comments when you see them! Remember we're writing code for slides :smile: - `use_small_heuristics = "Max"` allows for things like struct literals and if-statements to take up the full line width configured above. The formatting settings apply to all our Rust code right now — I think we could improve this with https://github.com/dprint/dprint/issues/711 which lets us add per-directory `dprint` configuration files. However, the `inherit: true` setting is not yet implemented (as far as I can tell), so a nested configuration file will have to copy most or all of the top-level file.
2023-12-31 00:15:07 +01:00
The course assumes that you already know how to program. Rust is a
statically-typed language and we will sometimes make comparisons with C and C++
to better explain or contrast the Rust approach.
Publish Comprehensive Rust 🦀
2022-12-21 16:36:30 +01:00
Fix some typos and wording in welcome.md (#639)
2023-07-06 09:38:43 +00:00
If you know how to program in a dynamically-typed language such as Python or
Publish Comprehensive Rust 🦀
2022-12-21 16:36:30 +01:00
JavaScript, then you will be able to follow along just fine too.
Introduce speaker notes on welcome page
2023-01-07 16:44:53 +01:00
<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>
Reference in New Issue Copy Permalink