From 3e8b12604ac11a815afb0f55c2c4761bcc59ce4a Mon Sep 17 00:00:00 2001 From: "Carol (Nichols || Goulding)" Date: Tue, 12 Jan 2021 21:35:44 -0500 Subject: [PATCH 1/2] Rewrap to 80 chars like the rest of this repo --- ADMIN_TASKS.md | 123 +++++++++++++++++++++++------------------- tools/update-rustc.sh | 17 +++--- 2 files changed, 79 insertions(+), 61 deletions(-) diff --git a/ADMIN_TASKS.md b/ADMIN_TASKS.md index 701375574b..036b0d8068 100644 --- a/ADMIN_TASKS.md +++ b/ADMIN_TASKS.md @@ -1,88 +1,103 @@ # Administrative Tasks -This documentation is for Carol and Steve and anyone else managing the repo to remember how to do -occasional maintenance tasks. +This documentation is for Carol and Steve and anyone else managing the repo to +remember how to do occasional maintenance tasks. ## Update the `rustc` version - Change the version number in `.github/workflows/main.yml` -- Change the version number in `rust-toolchain`, which should change the version you're using - locally with `rustup` +- Change the version number in `rust-toolchain`, which should change the + version you're using locally with `rustup` - Change the version number in `src/title-page.md` -- Run `./tools/update-rustc.sh` (see its commented code for details on what it does) -- Inspect the changes (by looking at the files changed according to git) and their effects (by - looking at the files in `tmp/book-before` and `tmp/book-after`) and commit them if they look good -- Grep for `manual-regeneration` and follow the instructions in those places to update output that - cannot be generated by a script +- Run `./tools/update-rustc.sh` (see its commented code for details on what it + does) +- Inspect the changes (by looking at the files changed according to git) and + their effects (by looking at the files in `tmp/book-before` and + `tmp/book-after`) and commit them if they look good +- Grep for `manual-regeneration` and follow the instructions in those places to + update output that cannot be generated by a script ## Release a new version of the listings -We now make `.tar` files of complete projects containing every listing available [as GitHub -Releases](https://github.com/rust-lang/book/releases). To create a new release artifact, for -example if there have been code changes due to edits or due to updating Rust and `rustfmt`, do the -following: - -- Create a git tag for the release and push it to GitHub, or create a new tag by going to the - GitHub UI, [drafting a new release](https://github.com/rust-lang/book/releases/new), and entering - a new tag instead of selecting an existing tag -- Run `cargo run --bin release_listings`, which will generate `tmp/listings.tar.gz` +We now make `.tar` files of complete projects containing every listing +available [as GitHub Releases](https://github.com/rust-lang/book/releases). To +create a new release artifact, for example if there have been code changes due +to edits or due to updating Rust and `rustfmt`, do the following: + +- Create a git tag for the release and push it to GitHub, or create a new tag + by going to the GitHub UI, [drafting a new + release](https://github.com/rust-lang/book/releases/new), and entering a new + tag instead of selecting an existing tag +- Run `cargo run --bin release_listings`, which will generate + `tmp/listings.tar.gz` - Upload `tmp/listings.tar.gz` in the GitHub UI for the draft release - Publish the release ## Add a new listing -To facilitate the scripts that run `rustfmt` on all the listings, update the output when the -compiler is updated, and produce release artifacts containing full projects for the listings, any -listing beyond the most trivial should be extracted into a file. To do that: +To facilitate the scripts that run `rustfmt` on all the listings, update the +output when the compiler is updated, and produce release artifacts containing +full projects for the listings, any listing beyond the most trivial should be +extracted into a file. To do that: - Find where the new listing should go in the `listings` directory. - There is one subdirectory for each chapter - - Numbered listings should use `listing-[chapter num]-[listing num]` for their directory names. - - Listings without a number should start with `no-listing-` followed by a number that indicates - its position in the chapter relative to the other listings without numbers in the chapter, then - a short description that someone could read to find the code they're looking for. - - Listings used only for displaying the output of the code (for example, when we say "if we had - written x instead of y, we would get this compiler error:" but we don't actually show code x) - should be named with `output-only-` followed by a number that indicates its position in the - chapter relative to the other listings used only for output, then a short description that - authors or contributors could read to find the code they're looking for. + - Numbered listings should use `listing-[chapter num]-[listing num]` for + their directory names. + - Listings without a number should start with `no-listing-` followed by a + number that indicates its position in the chapter relative to the other + listings without numbers in the chapter, then a short description that + someone could read to find the code they're looking for. + - Listings used only for displaying the output of the code (for example, when + we say "if we had written x instead of y, we would get this compiler + error:" but we don't actually show code x) should be named with + `output-only-` followed by a number that indicates its position in the + chapter relative to the other listings used only for output, then a short + description that authors or contributors could read to find the code + they're looking for. - **Remember to adjust surrounding listing numbers as appropriate!** -- Create a full Cargo project in that directory, either by using `cargo new` or copying another - listing as a starting point. +- Create a full Cargo project in that directory, either by using `cargo new` or + copying another listing as a starting point. - Add the code and any surrounding code needed to create a full working example. -- If you only want to show part of the code in the file, use anchor comments (`// ANCHOR: some_tag` - and `// ANCHOR_END: some_tag`) to mark the parts of the file you want to show. -- For Rust code, use the `{{#rustdoc_include [fileame:some_tag]}}` directive within the code blocks - in the text. The `rustdoc_include` directive gives the code that doesn't get displayed to - `rustdoc` for `mdbook test` purposes. +- If you only want to show part of the code in the file, use anchor comments + (`// ANCHOR: some_tag` and `// ANCHOR_END: some_tag`) to mark the parts of + the file you want to show. +- For Rust code, use the `{{#rustdoc_include [fileame:some_tag]}}` directive + within the code blocks in the text. The `rustdoc_include` directive gives the + code that doesn't get displayed to `rustdoc` for `mdbook test` purposes. - For anything else, use the `{{#include [filename:some_tag]}}` directive. -- If you want to display the output of a command in the text as well, create an `output.txt` file - in the listing's directory as follows: - - Run the command, like `cargo run` or `cargo test`, and copy all of the output. - - Create a new `output.txt` file with the first line `$ [the command you ran]`. +- If you want to display the output of a command in the text as well, create an + `output.txt` file in the listing's directory as follows: + - Run the command, like `cargo run` or `cargo test`, and copy all of the + output. + - Create a new `output.txt` file with the first line `$ [the command you + ran]`. - Paste the output you just copied. - - Run `./tools/update-rustc.sh`, which should perform some normalization on the compiler output. + - Run `./tools/update-rustc.sh`, which should perform some normalization on + the compiler output. - Include the output in the text with the `{{#include [filename]}}` directive. - Add and commit output.txt. -- If you want to display output but for some reason it can't be generated by a script (say, because - of user input or external events like making a web request), keep the output inline but make a - comment that contains `manual-regeneration` and instructions for manually updating the inline - output. -- If you don't want this example to even be attempted to be formatted by `rustfmt` (for example - because the example doesn't parse on purpose), add a `rustfmt-ignore` file in the listing's - directory and the reason it's not being formatted as the contents of that file (in case it's a - rustfmt bug that might get fixed someday). +- If you want to display output but for some reason it can't be generated by a + script (say, because of user input or external events like making a web + request), keep the output inline but make a comment that contains + `manual-regeneration` and instructions for manually updating the inline + output. +- If you don't want this example to even be attempted to be formatted by + `rustfmt` (for example because the example doesn't parse on purpose), add a + `rustfmt-ignore` file in the listing's directory and the reason it's not + being formatted as the contents of that file (in case it's a rustfmt bug that + might get fixed someday). ## See the effect of some change on the rendered book To check, say, updating `mdbook` or changing the way files get included: -- Generate a built book before the change you want to test by running `mdbook build -d - tmp/book-before` +- Generate a built book before the change you want to test by running `mdbook + build -d tmp/book-before` - Apply the changes you want to test and run `mdbook build -d tmp/book-after` - Run `./tools/megadiff.sh` -- Files remaining in `tmp/book-before` and `tmp/book-after` have differences you can manually - inspect with your favorite diff viewing mechanism +- Files remaining in `tmp/book-before` and `tmp/book-after` have differences + you can manually inspect with your favorite diff viewing mechanism ## Produce new markdown files for No Starch diff --git a/tools/update-rustc.sh b/tools/update-rustc.sh index 27ee942041..c6150fc770 100755 --- a/tools/update-rustc.sh +++ b/tools/update-rustc.sh @@ -11,8 +11,8 @@ echo 'Formatting all listings...' find -s listings -name Cargo.toml -print0 | while IFS= read -r -d '' f; do dir_to_fmt=$(dirname $f) - # There are a handful of listings we don't want to rustfmt and skipping doesn't work; - # those will have a file in their directory that explains why. + # There are a handful of listings we don't want to rustfmt and skipping + # doesn't work; those will have a file in their directory that explains why. if [ ! -f "${dir_to_fmt}/rustfmt-ignore" ]; then cd $dir_to_fmt cargo fmt --all && true @@ -20,7 +20,8 @@ find -s listings -name Cargo.toml -print0 | while IFS= read -r -d '' f; do fi done -# Get listings without anchor comments in tmp by compiling a release listings artifact +# Get listings without anchor comments in tmp by compiling a release listings +# artifact echo 'Generate listings without anchor comments...' cargo run --bin release_listings @@ -36,10 +37,12 @@ find -s listings -name output.txt -print0 | while IFS= read -r -d '' f; do cd $tmp_build_directory - # Save the previous compile time; we're going to keep it to minimize diff churn + # Save the previous compile time; we're going to keep it to minimize diff + # churn compile_time=$(sed -E -ne 's/.*Finished (dev|test) \[unoptimized \+ debuginfo] target\(s\) in ([0-9.]*).*/\2/p' ${full_output_path}) - # Save the hash from the first test binary; we're going to keep it to minimize diff churn + # Save the hash from the first test binary; we're going to keep it to + # minimize diff churn test_binary_hash=$(sed -E -ne 's@.*Running target/debug/deps/[^-]*-([^\s]*)@\1@p' ${full_output_path} | head -n 1) # Act like this is the first time this listing has been built @@ -56,8 +59,8 @@ find -s listings -name output.txt -print0 | while IFS= read -r -d '' f; do # ordering of tests in the output when the command is `cargo test`. RUSTFLAGS="-A unused_variables -A dead_code" RUST_TEST_THREADS=1 $cargo_command >> ${full_output_path} 2>&1 || true - # Set the project file path to the projects directory plus the crate name instead of a path - # to the computer of whoever is running this + # Set the project file path to the projects directory plus the crate name + # instead of a path to the computer of whoever is running this sed -i '' -E -e 's@(Compiling|Checking) ([^\)]*) v0.1.0 (.*)@\1 \2 v0.1.0 (file:///projects/\2)@' ${full_output_path} # Restore the previous compile time, if there is one From 2485f9023b67cd4175a03c8724802eb51e34048d Mon Sep 17 00:00:00 2001 From: "Carol (Nichols || Goulding)" Date: Tue, 12 Jan 2021 21:50:40 -0500 Subject: [PATCH 2/2] Update to 1.49 --- .github/workflows/main.yml | 4 ++-- .../ch17-oop/no-listing-01-trait-object-of-clone/output.txt | 3 ++- rust-toolchain | 2 +- src/title-page.md | 2 +- 4 files changed, 6 insertions(+), 5 deletions(-) diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml index af813166db..976890d727 100644 --- a/.github/workflows/main.yml +++ b/.github/workflows/main.yml @@ -12,8 +12,8 @@ jobs: - name: Install Rust run: | rustup set profile minimal - rustup toolchain install 1.48 -c rust-docs - rustup default 1.48 + rustup toolchain install 1.49 -c rust-docs + rustup default 1.49 - name: Install mdbook run: | mkdir bin diff --git a/listings/ch17-oop/no-listing-01-trait-object-of-clone/output.txt b/listings/ch17-oop/no-listing-01-trait-object-of-clone/output.txt index 8c67a059d9..40d6c7f9fa 100644 --- a/listings/ch17-oop/no-listing-01-trait-object-of-clone/output.txt +++ b/listings/ch17-oop/no-listing-01-trait-object-of-clone/output.txt @@ -4,9 +4,10 @@ error[E0038]: the trait `Clone` cannot be made into an object --> src/lib.rs:2:21 | 2 | pub components: Vec>, - | ^^^^^^^^^^^^^^^^^^^ the trait `Clone` cannot be made into an object + | ^^^^^^^^^^^^^^^^^^^ `Clone` cannot be made into an object | = note: the trait cannot be made into an object because it requires `Self: Sized` + = note: for a trait to be "object safe" it needs to allow building a vtable to allow the call to be resolvable dynamically; for more information visit error: aborting due to previous error diff --git a/rust-toolchain b/rust-toolchain index c05d9129f1..d4d0f85c9e 100644 --- a/rust-toolchain +++ b/rust-toolchain @@ -1 +1 @@ -1.48 +1.49 diff --git a/src/title-page.md b/src/title-page.md index 2dfe5a102f..96e16ad4d0 100644 --- a/src/title-page.md +++ b/src/title-page.md @@ -2,7 +2,7 @@ *by Steve Klabnik and Carol Nichols, with contributions from the Rust Community* -This version of the text assumes you’re using Rust 1.48 or later with +This version of the text assumes you’re using Rust 1.49 or later with `edition="2018"` in *Cargo.toml* of all projects to use Rust 2018 Edition idioms. See the [“Installation” section of Chapter 1][install] to install or update Rust, and see the new [Appendix E][editions]