Merge main into only-new-sync

packages/trpl/CONTRIBUTING.md

@@ -0,0 +1,11 @@
+# Contributing
+
+## 🚧 Under construction! 🚧
+
+Thanks for your interesting in helping us with this! At the moment, we are not
+ready for contributions, though.
+
+Once we stabilize the contents of the book, including the APIs we are
+re-exporting here and the little bits of functionality implemented in that
+crate, we will gladly take all the help we can get for maintaining this. We will
+update this document once we are ready for contributions.

packages/trpl/Cargo.toml

@@ -0,0 +1,9 @@
+[package]
+name = "trpl"
+version = "0.1.0"
+edition = "2021"
+
+# See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
+
+[dependencies]
+tokio = { version = "1", features = ["full"] }

packages/trpl/README.md

@@ -0,0 +1,23 @@
+# The Rust Programming Language Book Crate
+
+![Build Status](https://github.com/chriskrycho/trpl-crate/workflows/CI/badge.svg)
+
+This repository is the home of the `trpl` crate used in _The Rust Programming
+Language_ book materials.
+
+This crate mostly just re-exports items from *other* crates. It exists for two
+main reasons:
+
+1. So that as you read along in _The Rust Programming Language_, you can add
+   just one dependency, rather than however many we end up with, and likewise
+   use only one set of imports.
+
+2. So that we can more easily guarantee it keeps building and working. Since we
+   control the contents of this crate and when it changes, readers will never be
+   broken by upstream changes, e.g. if Tokio does a breaking 2.0 release at some
+   point.
+
+## Requirements
+
+<!-- TODO: pick an appropriate starting version! -->
+This crate currently requires at least Rust 1.77.

packages/trpl/src/lib.rs

@@ -0,0 +1,15 @@
+//! A support crate for _The Rust Programming Language_.
+//!
+//! This crate mostly just re-exports items from *other* crates. It exists for
+//! two main reasons:
+//!
+//! 1. So that as you read along in _The Rust Programming Language_, you can
+//!    add just one dependency, rather than however many we end up with, and
+//!    likewise use only one set of imports.
+//!
+//! 2. So that we can more easily guarantee it keeps building and working. Since
+//!    we control the contents of this crate and when it changes, readers will
+//!    never be broken by upstream changes, e.g. if Tokio does a breaking 2.0
+//!    release at some point.
+
+pub use tokio::main as async_main;

packages/trpl/tests/integration/main.rs

@@ -0,0 +1,29 @@
+//! Integration tests for the crate.
+//!
+//! These all live in a *single* integration test crate, `tests/integration`,
+//! because each integration test is a dedicated binary crate which has to be
+//! compiled separately. While that is not really a problem for a crate this
+//! small, we have chosen to follow this “best practice” here as a good example.
+//!
+//! For more details on why you might prefer this pattern see [this post][post].
+//!
+//! [post]: https://matklad.github.io/2021/02/27/delete-cargo-integration-tests.html
+
+use trpl::async_main;
+
+/// This test makes sure the re-exported version of the `tokio::main` macro,
+/// which is applied like `#[tokio::main] async fn some_fn() { … }`, continues
+/// to work. However, tests cannot use `async fn`, so to test it, we need to
+/// have a non-`async` test function, which then applies the macro to an `async`
+/// function in its body, and invokes *that*.
+#[test]
+fn re_exported_macro_works() {
+    #[async_main]
+    async fn internal() -> &'static str {
+        let val = async { "Hello" }.await;
+        assert_eq!(val, "Hello", "Async is usable in async_main function");
+        val
+    }
+
+    assert_eq!(internal(), "Hello", "value returns correctly");
+}

src/SUMMARY.md

@@ -101,29 +101,33 @@
     - [Shared-State Concurrency](ch16-03-shared-state.md)
     - [Extensible Concurrency with the `Sync` and `Send` Traits](ch16-04-extensible-concurrency-sync-and-send.md)
 
-- [Object Oriented Programming Features of Rust](ch17-00-oop.md)
-    - [Characteristics of Object-Oriented Languages](ch17-01-what-is-oo.md)
-    - [Using Trait Objects That Allow for Values of Different Types](ch17-02-trait-objects.md)
-    - [Implementing an Object-Oriented Design Pattern](ch17-03-oo-design-patterns.md)
+- [Async and Await](ch17-00-async-await.md)
+    - [Futures and the Async Syntax](ch17-01-tasks.md)
+    - [something something tokio?!?](ch17-02.md)
+
+- [Object Oriented Programming Features of Rust](ch18-00-oop.md)
+    - [Characteristics of Object-Oriented Languages](ch18-01-what-is-oo.md)
+    - [Using Trait Objects That Allow for Values of Different Types](ch18-02-trait-objects.md)
+    - [Implementing an Object-Oriented Design Pattern](ch18-03-oo-design-patterns.md)
 
 ## Advanced Topics
 
-- [Patterns and Matching](ch18-00-patterns.md)
-    - [All the Places Patterns Can Be Used](ch18-01-all-the-places-for-patterns.md)
-    - [Refutability: Whether a Pattern Might Fail to Match](ch18-02-refutability.md)
-    - [Pattern Syntax](ch18-03-pattern-syntax.md)
-
-- [Advanced Features](ch19-00-advanced-features.md)
-    - [Unsafe Rust](ch19-01-unsafe-rust.md)
-    - [Advanced Traits](ch19-03-advanced-traits.md)
-    - [Advanced Types](ch19-04-advanced-types.md)
-    - [Advanced Functions and Closures](ch19-05-advanced-functions-and-closures.md)
-    - [Macros](ch19-06-macros.md)
-
-- [Final Project: Building a Multithreaded Web Server](ch20-00-final-project-a-web-server.md)
-    - [Building a Single-Threaded Web Server](ch20-01-single-threaded.md)
-    - [Turning Our Single-Threaded Server into a Multithreaded Server](ch20-02-multithreaded.md)
-    - [Graceful Shutdown and Cleanup](ch20-03-graceful-shutdown-and-cleanup.md)
+- [Patterns and Matching](ch19-00-patterns.md)
+    - [All the Places Patterns Can Be Used](ch19-01-all-the-places-for-patterns.md)
+    - [Refutability: Whether a Pattern Might Fail to Match](ch19-02-refutability.md)
+    - [Pattern Syntax](ch19-03-pattern-syntax.md)
+
+- [Advanced Features](ch20-00-advanced-features.md)
+    - [Unsafe Rust](ch20-01-unsafe-rust.md)
+    - [Advanced Traits](ch20-03-advanced-traits.md)
+    - [Advanced Types](ch20-04-advanced-types.md)
+    - [Advanced Functions and Closures](ch20-05-advanced-functions-and-closures.md)
+    - [Macros](ch20-06-macros.md)
+
+- [Final Project: Building a Multithreaded Web Server](ch21-00-final-project-a-web-server.md)
+    - [Building a Single-Threaded Web Server](ch21-01-single-threaded.md)
+    - [Turning Our Single-Threaded Server into a Multithreaded Server](ch21-02-multithreaded.md)
+    - [Graceful Shutdown and Cleanup](ch21-03-graceful-shutdown-and-cleanup.md)
 
 - [Appendix](appendix-00.md)
     - [A - Keywords](appendix-01-keywords.md)