Skip to content

Commit 63d8e5a

Browse files
Enes1313Enes1313
committed
Merge branch 'main' into tr-translation-of-day-1-afternoon
2 parents 874c94c + 8419b30 commit 63d8e5a

File tree

6 files changed

+70
-39
lines changed

6 files changed

+70
-39
lines changed

‎.cargo/config.toml

Lines changed: 7 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,12 @@
11
[alias]
2-
# We use this alias for task automation in the project.
3-
# See README in xtask directory.
2+
# WARNING: Using the `xtask` alias is deprecated and will be unsupported in a
3+
# future version of Cargo. See https://github.com/rust-lang/cargo/issues/10049.
44
xtask = "run --package xtask --"
5+
install-tools = "run --package xtask -- install-tools"
6+
web-tests = "run --package xtask -- web-tests"
7+
rust-tests = "run --package xtask -- rust-tests"
8+
serve = "run --package xtask -- serve"
9+
build-book = "run --package xtask -- build"
510

611
[env]
712
# To provide an anchor to the root of the workspace when working with paths.

‎README.md

Lines changed: 21 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -75,17 +75,31 @@ cargo xtask install-tools
7575

7676
Here is a summary of the various commands you can run in the project.
7777

78-
| Command | Description |
79-
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
80-
| `cargo xtask install-tools` | Install all the tools the project depends on. |
81-
| `cargo xtask serve` | Start a web server with the course. You'll find the content on http://localhost:3000. |
82-
| `cargo xtask rust-tests` | Test the included Rust snippets. |
83-
| `cargo xtask web-tests` | Run the web driver tests in the tests directory. |
84-
| `cargo xtask build` | Create a static version of the course in the `book/` directory. Note that you have to separately build and zip exercises and add them to book/html. To build any of the translated versions of the course, run MDBOOK_BOOK__LANGUAGE=xx mdbook build -d book/xx where xx is the ISO 639 language code (e.g. da for the Danish translation). [TRANSLATIONS.md](TRANSLATIONS.md) contains further instructions. |
78+
| Command | Description |
79+
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
80+
| `cargo install-tools` | Install all the tools the project depends on. |
81+
| `cargo serve` | Start a web server with the course. You'll find the content on http://localhost:3000. |
82+
| `cargo rust-tests` | Test the included Rust snippets. |
83+
| `cargo web-tests` | Run the web driver tests in the tests directory. |
84+
| `cargo build-book` | Create a static version of the course in the `book/` directory. Note that you have to separately build and zip exercises and add them to book/html. To build any of the translated versions of the course, run MDBOOK_BOOK__LANGUAGE=xx mdbook build -d book/xx where xx is the ISO 639 language code (e.g. da for the Danish translation). [TRANSLATIONS.md](TRANSLATIONS.md) contains further instructions. |
8585

8686
> **Note** On Windows, you need to enable symlinks
8787
> (`git config --global core.symlinks true`) and Developer Mode.
8888
89+
> **Note** Previous versions this README recommended that you use
90+
> `cargo xtool <tool>`, i.e. `cargo xtool install-tools`. This causes issues
91+
> with pre-existing installations of `cargo-xtool` and is now deprecated.
92+
>
93+
> The new syntax is almost a 1:1 mapping, although `cargo xtool build` has
94+
> become `cargo build-book` to avoid conflicting with the built-in Cargo
95+
> subcommand.
96+
>
97+
> - `cargo xtool build` -> `cargo build-book`
98+
> - `cargo xtool install-tools` -> `cargo install-tools`
99+
> - `cargo xtool serve` -> `cargo serve`
100+
> - `cargo xtool run-tests` -> `cargo run-tests`
101+
> - `cargo xtool web-tests` -> `cargo web-tests`
102+
89103
## Contributing
90104

91105
We would like to receive your contributions. Please see

‎src/unsafe-rust/dereferencing.md

Lines changed: 26 additions & 18 deletions
Original file line numberDiff line numberDiff line change
@@ -8,27 +8,32 @@ Creating pointers is safe, but dereferencing them requires `unsafe`:
88

99
```rust,editable
1010
fn main() {
11-
let mut s = String::from("careful!");
11+
let mut x = 10;
1212
13-
let r1 = &raw mut s;
14-
let r2 = r1 as *const String;
13+
let p1: *mut i32 = &raw mut x;
14+
let p2 = p1 as *const i32;
1515
16-
// SAFETY: r1 and r2 were obtained from references and so are guaranteed to
17-
// be non-null and properly aligned, the objects underlying the references
18-
// from which they were obtained are live throughout the whole unsafe
19-
// block, and they are not accessed either through the references or
20-
// concurrently through any other pointers.
16+
// SAFETY: p1 and p2 were created by taking raw pointers to a local, so they
17+
// are guaranteed to be non-null, aligned, and point into a single (stack-)
18+
// allocated object.
19+
//
20+
// The object underlying the raw pointers lives for the entire function, so
21+
// it is not deallocated while the raw pointers still exist. It is not
22+
// accessed through references while the raw pointers exist, nor is it
23+
// accessed from other threads concurrently.
2124
unsafe {
22-
println!("r1 is: {}", *r1);
23-
*r1 = String::from("uhoh");
24-
println!("r2 is: {}", *r2);
25+
dbg!(*p1);
26+
*p1 = 6;
27+
// Mutation may soundly be observed through a raw pointer, like in C.
28+
dbg!(*p2);
2529
}
2630
27-
// NOT SAFE. DO NOT DO THIS.
31+
// UNSOUND. DO NOT DO THIS.
2832
/*
29-
let r3: &String = unsafe { &*r1 };
30-
drop(s);
31-
println!("r3 is: {}", *r3);
33+
let r: &i32 = unsafe { &*p1 };
34+
dbg!(r);
35+
x = 50;
36+
dbg!(r); // Object underlying the reference has been mutated. This is UB.
3237
*/
3338
}
3439
```
@@ -52,8 +57,11 @@ In the case of pointer dereferences, this means that the pointers must be
5257

5358
In most cases the pointer must also be properly aligned.
5459

55-
The "NOT SAFE" section gives an example of a common kind of UB bug: `*r1` has
56-
the `'static` lifetime, so `r3` has type `&'static String`, and thus outlives
57-
`s`. Creating a reference from a pointer requires _great care_.
60+
The "UNSOUND" section gives an example of a common kind of UB bug: naïvely
61+
taking a reference to the dereference of a raw pointer sidesteps the compiler's
62+
knowledge of what object the reference is actually pointing to. As such, the
63+
borrow checker does not freeze `x` and so we are able to modify it despite the
64+
existence of a reference to it. Creating a reference from a pointer requires
65+
_great care_.
5866

5967
</details>

‎src/unsafe-rust/mutable-static.md

Lines changed: 9 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -14,15 +14,18 @@ fn main() {
1414
}
1515
```
1616

17-
However, since data races can occur, it is unsafe to read and write mutable
18-
static variables:
17+
However, mutable static variables are unsafe to read and write because multiple
18+
threads could do so concurrently without synchronization, constituting a data
19+
race.
20+
21+
Using mutable statics soundly requires reasoning about concurrency without the
22+
compiler's help:
1923

2024
```rust,editable
2125
static mut COUNTER: u32 = 0;
2226
2327
fn add_to_counter(inc: u32) {
2428
// SAFETY: There are no other threads which could be accessing `COUNTER`.
25-
#[allow(static_mut_refs)]
2629
unsafe {
2730
COUNTER += inc;
2831
}
@@ -32,7 +35,6 @@ fn main() {
3235
add_to_counter(42);
3336
3437
// SAFETY: There are no other threads which could be accessing `COUNTER`.
35-
#[allow(static_mut_refs)]
3638
unsafe {
3739
dbg!(COUNTER);
3840
}
@@ -41,13 +43,12 @@ fn main() {
4143

4244
<details>
4345

44-
- The program here is safe because it is single-threaded. However, the Rust
46+
- The program here is sound because it is single-threaded. However, the Rust
4547
compiler reasons about functions individually so can't assume that. Try
4648
removing the `unsafe` and see how the compiler explains that it is undefined
4749
behavior to access a mutable static from multiple threads.
48-
- Rust 2024 edition goes further and makes accessing a mutable static by
49-
reference an error by default. We work around this in the example with
50-
`#[allow(static_mut_refs)]`. Don't do this.
50+
- The 2024 Rust edition goes further and makes accessing a mutable static by
51+
reference an error by default.
5152
- Using a mutable static is almost always a bad idea, you should use interior
5253
mutability instead.
5354
- There are some cases where it might be necessary in low-level `no_std` code,

‎src/unsafe-rust/unsafe-functions.md

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,10 +7,10 @@ minutes: 15
77
A function or method can be marked `unsafe` if it has extra preconditions you
88
must uphold to avoid undefined behaviour.
99

10-
There are two main categories:
10+
Unsafe functions may come from two places:
1111

12-
- Rust functions declared unsafe with `unsafe fn`.
13-
- Foreign functions in `extern "C"` blocks.
12+
- Rust functions declared unsafe.
13+
- Unsafe foreign functions in `extern "C"` blocks.
1414

1515
<details>
1616

‎src/unsafe-rust/unsafe-functions/extern-c.md

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
# Unsafe External Functions
22

3-
Functions in a foreign language may also be unsafe:
3+
You can declare foreign functions for access from Rust with `unsafe extern`.
4+
This is unsafe because the compiler has to way to reason about their behavior.
5+
Functions declared in an `extern` block must be marked as `safe` or `unsafe`,
6+
depending on whether they have preconditions for safe use:
47

58
```rust,editable
69
use std::ffi::c_char;

0 commit comments

Comments
 (0)