rust/comprehensive-rust
1
0
Fork 0
mirror of https://github.com/google/comprehensive-rust.git synced 2025-12-23 23:12:52 +02:00
Code Issues Releases Activity

Format all Markdown files with dprint (#1157)

Browse Source 
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 😄
- `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.
This commit is contained in:
Martin Geisler
2023-12-31 00:15:07 +01:00
committed by GitHub
parent f43e72e0ad
commit c9f66fd425
302 changed files with 3067 additions and 2622 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
src/cargo/code-samples.md
View File

@@ -21,15 +21,14 @@ text box.
<details>
Most code samples are editable like shown above. A few code samples
are not editable for various reasons:
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 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.
- 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>

65
src/cargo/running-locally.md
View File

@@ -1,9 +1,10 @@
# Running Code Locally with Cargo
If you want to experiment with the code on your own system, then you will need
to first install Rust. Do this by following the [instructions in the Rust
Book][1]. This should give you a working `rustc` and `cargo`. At the time of
writing, the latest stable Rust release has these version numbers:
to first install Rust. Do this by following the
[instructions in the Rust Book][1]. This should give you a working `rustc` and
`cargo`. At the time of writing, the latest stable Rust release has these
version numbers:
```shell
% rustc --version
@@ -14,47 +15,47 @@ cargo 1.69.0 (6e9a83356 2023-04-12)
You can use any later version too since Rust maintains backwards compatibility.
With this in place, follow these steps to build a Rust binary from one
of the examples in this training:
With this in place, follow these steps to build a Rust binary from one of the
examples in this training:
1. Click the "Copy to clipboard" button on the example you want to copy.
2. Use `cargo new exercise` to create a new `exercise/` directory for your code:
```shell
$ cargo new exercise
Created binary (application) `exercise` package
```
```shell
$ cargo new exercise
Created binary (application) `exercise` package
```
3. Navigate into `exercise/` and use `cargo run` to build and run your binary:
```shell
$ cd exercise
$ cargo run
Compiling exercise v0.1.0 (/home/mgeisler/tmp/exercise)
Finished dev [unoptimized + debuginfo] target(s) in 0.75s
Running `target/debug/exercise`
Hello, world!
```
```shell
$ cd exercise
$ cargo run
Compiling exercise v0.1.0 (/home/mgeisler/tmp/exercise)
Finished dev [unoptimized + debuginfo] target(s) in 0.75s
Running `target/debug/exercise`
Hello, world!
```
4. Replace the boiler-plate code in `src/main.rs` with your own code. For
example, using the example on the previous page, make `src/main.rs` look like
```rust
fn main() {
println!("Edit me!");
}
```
```rust
fn main() {
println!("Edit me!");
}
```
5. Use `cargo run` to build and run your updated binary:
```shell
$ cargo run
Compiling exercise v0.1.0 (/home/mgeisler/tmp/exercise)
Finished dev [unoptimized + debuginfo] target(s) in 0.24s
Running `target/debug/exercise`
Edit me!
```
```shell
$ cargo run
Compiling exercise v0.1.0 (/home/mgeisler/tmp/exercise)
Finished dev [unoptimized + debuginfo] target(s) in 0.24s
Running `target/debug/exercise`
Edit me!
```
6. Use `cargo check` to quickly check your project for errors, use `cargo build`
to compile it without running it. You will find the output in `target/debug/`
@@ -69,8 +70,8 @@ of the examples in this training:
<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.
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>

71
src/cargo/rust-ecosystem.md
View File

@@ -2,15 +2,15 @@
The Rust ecosystem consists of a number of tools, of which the main ones are:
* `rustc`: the Rust compiler which turns `.rs` files into binaries and other
- `rustc`: the Rust compiler which turns `.rs` files into binaries and other
intermediate formats.
* `cargo`: the Rust dependency manager and build tool. Cargo knows how to
download dependencies, usually hosted on <https://crates.io>, and it will pass them to
`rustc` when building your project. Cargo also comes with a built-in test
runner which is used to execute unit tests.
- `cargo`: the Rust dependency manager and build tool. Cargo knows how to
download dependencies, usually hosted on <https://crates.io>, and it will pass
them to `rustc` when building your project. Cargo also comes with a built-in
test runner which is used to execute unit tests.
* `rustup`: the Rust toolchain installer and updater. This tool is used to
- `rustup`: the Rust toolchain installer and updater. This tool is used to
install and update `rustc` and `cargo` when new versions of Rust are released.
In addition, `rustup` can also download documentation for the standard
library. You can have multiple versions of Rust installed at once and `rustup`
@@ -20,52 +20,51 @@ The Rust ecosystem consists of a number of tools, of which the main ones are:
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.
- 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".
- There are three release channels: "stable", "beta", and "nightly".
* New features are being tested on "nightly", "beta" is what becomes
"stable" every six weeks.
- New features are being tested on "nightly", "beta" is what becomes "stable"
every six weeks.
* Dependencies can also be resolved from alternative [registries], git, folders, and more.
- Dependencies can also be resolved from alternative [registries], git, folders,
and more.
* Rust also has [editions]: the current edition is Rust 2021. Previous
editions were Rust 2015 and Rust 2018.
- 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.
- 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 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.
- To avoid splitting the ecosystem, Rust compilers can mix code written for
different editions.
* Mention that it is quite rare to ever use the compiler directly not through `cargo` (most users never do).
- Mention that it is quite rare to ever use the compiler directly not through
`cargo` (most users never do).
* It might be worth alluding that Cargo itself is an extremely powerful and comprehensive tool. It is capable of many advanced features including but not limited to:
* Project/package structure
* [workspaces]
* Dev Dependencies and Runtime Dependency management/caching
* [build scripting]
* [global installation]
* It is also extensible with sub command plugins as well (such as [cargo clippy]).
* Read more from the [official Cargo Book]
- It might be worth alluding that Cargo itself is an extremely powerful and
comprehensive tool. It is capable of many advanced features including but
not limited to:
- Project/package structure
- [workspaces]
- Dev Dependencies and Runtime Dependency management/caching
- [build scripting]
- [global installation]
- It is also extensible with sub command plugins as well (such as
[cargo clippy]).
- Read more from the [official Cargo Book]
[editions]: https://doc.rust-lang.org/edition-guide/
[workspaces]: https://doc.rust-lang.org/cargo/reference/workspaces.html
[build scripting]: https://doc.rust-lang.org/cargo/reference/build-scripts.html
[global installation]: https://doc.rust-lang.org/cargo/commands/cargo-install.html
[cargo clippy]: https://github.com/rust-lang/rust-clippy
[official Cargo Book]: https://doc.rust-lang.org/cargo/
[registries]: https://doc.rust-lang.org/cargo/reference/registries.html
</details>