diff --git a/.markdown-link-check.json b/.markdown-link-check.json index efb33341..3648de60 100644 --- a/.markdown-link-check.json +++ b/.markdown-link-check.json @@ -13,6 +13,8 @@ "ignorePatterns": [{ "pattern": "^!--" },{ + "pattern": "^https://aayushyavajpayee.substack.com" + }, { "pattern": "^https://github.com/instrumentisto/rust-incubator/generate" }, { "pattern": "^https://crates.io/search\\?" @@ -22,6 +24,8 @@ "pattern": "^https://dl.acm.org" }, { "pattern": "^https://dpc.pw" + }, { + "pattern": "^https://kerkour.com" }, { "pattern": "^https://www.aspecto.io" }, { diff --git a/1_concepts/1_2_box_pin/README.md b/1_concepts/1_2_box_pin/README.md index f00f0b89..1d5be420 100644 --- a/1_concepts/1_2_box_pin/README.md +++ b/1_concepts/1_2_box_pin/README.md @@ -42,6 +42,7 @@ For better understanding [`Pin`] purpose, design, limitations and use cases read - [Alice Ryhl answers on "Pin tutorial are confusing me"][9] - [Rust Forum: Why is it unsafe to pin a shared reference?][11] - [Ohad Ravid: Put a Pin on That][12] +- [Razieh Behjati: Leaky Abstractions and a Rusty Pin][13] @@ -132,3 +133,4 @@ After completing everything above, you should be able to answer (and understand [10]: https://www.sobyte.net/post/2022-07/rust-pin-unpin [11]: https://users.rust-lang.org/t/why-is-it-unsafe-to-pin-a-shared-reference/40309 [12]: https://ohadravid.github.io/posts/2023-07-put-a-pin-on-that +[13]: https://itnext.io/leaky-abstractions-and-a-rusty-pin-fbf3b84eea1f diff --git a/1_concepts/1_8_thread_safety/README.md b/1_concepts/1_8_thread_safety/README.md index 7ed1658d..100920fc 100644 --- a/1_concepts/1_8_thread_safety/README.md +++ b/1_concepts/1_8_thread_safety/README.md @@ -13,6 +13,7 @@ For better understanding [`Send`]/[`Sync`] purpose, design, limitations and use - [nyanpasu64: An unsafe tour of Rust's Send and Sync][6] - [Josh Haberman: Thread Safety in C++ and Rust][7] - [Cliff L. Biffle: Safely writing code that isn't thread-safe][8] +- [Louis Dureuil: Too dangerous for C++][10] @@ -59,3 +60,4 @@ After completing everything above, you should be able to answer (and understand [7]: https://blog.reverberate.org/2021/12/18/thread-safety-cpp-rust.html [8]: https://cliffle.com/blog/not-thread-safe [9]: https://web.archive.org/web/20220929143451/https://itsallaboutthebit.com/arc-mutex +[10]: https://blog.dureuill.net/articles/too-dangerous-cpp diff --git a/1_concepts/1_9_phantom/README.md b/1_concepts/1_9_phantom/README.md index fc1f01d7..407edfea 100644 --- a/1_concepts/1_9_phantom/README.md +++ b/1_concepts/1_9_phantom/README.md @@ -89,6 +89,7 @@ For better understanding [`PhantomData`] purpose, design, limitations and use ca - [Rustonomicon: 3.10. PhantomData][2] - [Reddit: Why PhantomData][3] - [RIP Tutorial: Using PhantomData as a Type Marker][4] +- [Aayushya Vajpayee: Write Cleaner, More Maintainable Rust Code with PhantomData][11] - [Sergey Potapov: Phantom Types in Rust][6] @@ -208,3 +209,4 @@ After completing everything above, you should be able to answer (and understand [8]: https://docs.rs/variance/0.1.3/src/variance/lib.rs.html#16 [9]: https://docs.rs/variance/0.1.3/src/variance/lib.rs.html#92 [10]: https://manishearth.github.io/blog/2017/01/11/rust-tidbits-what-is-a-lang-item +[11]: https://aayushyavajpayee.substack.com/p/coming-soon diff --git a/2_idioms/2_2_mem_replace/README.md b/2_idioms/2_2_mem_replace/README.md index f501d6ee..dc73a6ab 100644 --- a/2_idioms/2_2_mem_replace/README.md +++ b/2_idioms/2_2_mem_replace/README.md @@ -27,6 +27,7 @@ For better understanding [`mem::replace`], [`mem::swap`] and [`mem::take`] purpo - [Official `mem::swap` docs][`mem::swap`] - [Official `mem::take` docs][`mem::take`] - [Karol Kuczmarski: Moving out of a container in Rust][4] +- [Ferrous Systems: Using `mem::take` to reduce heap allocations][6] Some examples of useful applying these functions are described below. @@ -165,3 +166,4 @@ After completing everything above, you should be able to answer (and understand [3]: https://rust-unofficial.github.io/patterns/idioms/mem-replace.html [4]: http://xion.io/post/code/rust-move-out-of-container.html [5]: https://doc.rust-lang.org/edition-guide/rust-2021/disjoint-capture-in-closures.html +[6]: https://ferrous-systems.com/blog/rustls-borrow-checker-p1 diff --git a/3_ecosystem/3_10_threads/README.md b/3_ecosystem/3_10_threads/README.md index d75324ea..e6c3e2a4 100644 --- a/3_ecosystem/3_10_threads/README.md +++ b/3_ecosystem/3_10_threads/README.md @@ -49,6 +49,7 @@ For better understanding and familiarity with [Rust] synchronization primitives - [Aleksey Kladov: Mutexes Are Faster Than Spinlocks][27] - [Mara Bos: Comparing Rust's and C++'s Concurrency Library][31] - [Mahmoud Al-Qudsi: Implementing truly safe semaphores in rust][32] +- [Michael Snoyman: My Best and Worst Deadlock in Rust][35] @@ -168,3 +169,4 @@ After completing everything above, you should be able to answer (and understand [32]: https://neosmart.net/blog/implementing-truly-safe-semaphores-in-rust/ [33]: https://vgatherps.github.io/2022-11-28-dec [34]: https://blog.logrocket.com/implementing-data-parallelism-rayon-rust +[35]: https://www.snoyman.com/blog/2024/01/best-worst-deadlock-rust diff --git a/3_ecosystem/3_11_async/README.md b/3_ecosystem/3_11_async/README.md index 1036db90..a804adea 100644 --- a/3_ecosystem/3_11_async/README.md +++ b/3_ecosystem/3_11_async/README.md @@ -72,6 +72,8 @@ For better understanding [`Waker`] design, usage, and features, read through the - [Amos: Understanding Rust futures by going way too deep][25] - [Hayden Stainsby: how I finally understood async/await in Rust (part 4)][67] - [Saoirse Shipwreckt: Why async Rust?][69] +- [Saoirse Shipwreckt: Let futures be futures][70] +- [Saoirse Shipwreckt: FuturesUnordered and the order of futures][71] @@ -324,3 +326,5 @@ After completing everything above, you should be able to answer (and understand [67]: https://hegdenu.net/posts/understanding-async-await-4 [68]: https://without.boats/blog/thread-per-core [69]: https://without.boats/blog/why-async-rust +[70]: https://without.boats/blog/let-futures-be-futures +[71]: https://without.boats/blog/futures-unordered diff --git a/3_ecosystem/3_1_testing/README.md b/3_ecosystem/3_1_testing/README.md index f5a7d603..d974e10f 100644 --- a/3_ecosystem/3_1_testing/README.md +++ b/3_ecosystem/3_1_testing/README.md @@ -115,7 +115,7 @@ For better understanding and familiarity with [fuzzing][31] in [Rust], read thro ## More reading - [Aleksey Kladov: How to Test][63] - +- [Joshua Mo: Everything you need to know about testing in Rust][64] ## Integrated tests @@ -132,7 +132,6 @@ For better understanding and familiarity with [fuzzing][31] in [Rust], read thro - [one more example](https://out-of-cheese-error.netlify.app/the-way) - ## Task __Estimated time__: 1 day @@ -195,3 +194,4 @@ After completing everything above, you should be able to answer (and understand [61]: https://www.youtube.com/watch?v=VDfX44fZoMc [62]: https://nexte.st/ [63]: https://matklad.github.io/2021/05/31/how-to-test.html +[64]: https://www.shuttle.rs/blog/2024/03/21/testing-in-rust diff --git a/3_ecosystem/3_2_macro/README.md b/3_ecosystem/3_2_macro/README.md index 05f282be..0ed864d1 100644 --- a/3_ecosystem/3_2_macro/README.md +++ b/3_ecosystem/3_2_macro/README.md @@ -40,6 +40,7 @@ For better understanding declarative macros design, concepts, usage and features - [Rust By Example: 16. macro_rules!][14] - [The Little Book of Rust Macros][15] - [Rust Reference: 3.1. Macros By Example][16] +- [Aurorans Solis: macros_rule!][18] @@ -164,6 +165,7 @@ After completing everything above, you should be able to answer (and understand [15]: https://danielkeep.github.io/tlborm/book/README.html [16]: https://doc.rust-lang.org/reference/macros-by-example.html [17]: https://doc.rust-lang.org/rust-by-example/macros/variadics.html +[18]: https://auroranssolis.github.io/rust/2024/02/14/macros-rule.html [22]: https://rust-lang.github.io/api-guidelines/macros.html#item-macros-work-anywhere-that-items-are-allowed-c-anywhere [23]: https://doc.rust-lang.org/book/ch19-06-macros.html#procedural-macros-for-generating-code-from-attributes [25]: https://doc.rust-lang.org/reference/attributes.html diff --git a/3_ecosystem/3_6_serde/README.md b/3_ecosystem/3_6_serde/README.md index 2c5c6619..5799f73c 100644 --- a/3_ecosystem/3_6_serde/README.md +++ b/3_ecosystem/3_6_serde/README.md @@ -105,6 +105,7 @@ However, the __main "killer feature"__ of [`musli`] is its __ability to serializ For better understanding and familiarity with [`musli`]'s design, concepts, usage, and features, read through the following articles: - [Official `musli` crate docs][`musli`] +- [John-John Tedro: A fresh look on incremental zero copy serialization][23] @@ -180,5 +181,6 @@ After completing everything above, you should be able to answer (and understand [14]: https://manishearth.github.io/blog/2022/08/03/zero-copy-3-so-zero-its-dot-dot-dot-negative [21]: https://docs.rs/serde/latest/serde/trait.Deserializer.html#tymethod.deserialize_seq [22]: https://docs.rs/musli#modes +[23]: https://udoprog.github.io/rust/2023-10-19/musli-zerocopy.html [30]: https://rkyv.org/rkyv.html [31]: https://rkyv.org/zero-copy-deserialization.html diff --git a/3_ecosystem/3_8_log/README.md b/3_ecosystem/3_8_log/README.md index 51bb32b8..b6f4d06e 100644 --- a/3_ecosystem/3_8_log/README.md +++ b/3_ecosystem/3_8_log/README.md @@ -49,8 +49,10 @@ Speaking of [tracing][10], the [`tracing`] crate has good integrations with [Ope For better understanding and familiarity with [`tracing`]'s design, concepts, usage, and features, read through the following articles: - [Official `tracing` crate docs][`tracing`] +- [Joshua Mo: Getting Started with Tracing in Rust][13] - [Yoav Danieli: Guide to OpenTelemetry Distributed Tracing in Rust][11] -- [Tokio Blog: Diagnostics with Tracing][13] +- [Tokio Blog: Diagnostics with Tracing][14] +- [Hayden Stainsby: debugging tokio instrumentation][15] @@ -113,4 +115,6 @@ After completing everything above, you should be able to answer (and understand [10]: https://en.wikipedia.org/wiki/Tracing_(software) [11]: https://www.aspecto.io/blog/distributed-tracing-with-opentelemetry-rust [12]: https://www.thecodedmessage.com/posts/logging -[13]: https://tokio.rs/blog/2019-08-tracing +[13]: https://www.shuttle.rs/blog/2024/01/09/getting-started-tracing-rust +[14]: https://tokio.rs/blog/2019-08-tracing +[15]: https://hegdenu.net/posts/debugging-tokio-instrumentation diff --git a/4_backend/4_3_api/README.md b/4_backend/4_3_api/README.md index 62cd9db2..7a2d0f27 100644 --- a/4_backend/4_3_api/README.md +++ b/4_backend/4_3_api/README.md @@ -26,7 +26,7 @@ For more information about [REST], read through the following articles: > > An OpenAPI definition can then be used by documentation generation tools to display the API, code generation tools to generate servers and clients in various programming languages, testing tools, and many other use cases. -In [Rust] ecosystem, most [OpenAPI] crates follow the __code-first approach__ (generating [OpenAPI] schema from source code). The most notable crates for this are [`utoipa`] and [`okapi`]. +In [Rust] ecosystem, most [OpenAPI] crates follow the __code-first approach__ (generating [OpenAPI] schema from source code). The most notable crates for this are [`utoipa`], [`okapi`] and [`apistos`]. For the opposite (generating source code from [OpenAPI] schema) [Rust] ecosystem lacks its own pure implementation, and the original [OpenAPI] tool [`openapi-generator`] should be used (powered by the [`swagger`] crate). @@ -35,8 +35,11 @@ For more familiarity with [OpenAPI] and using it in [Rust], read through the fol - [SwaggerHub Documentation: OpenAPI 3.0 Tutorial][122] - [Official `utoipa` crate docs][`cynic`] - [Official `okapi` crate docs][`okapi`] +- [Official `apistos` crate docs][`apistos`] - [Twilio Docs: Generate a Rust client for Twilio's API][121] - [Fabian Odenthal: Auto-Generating & Validating OpenAPI Docs in Rust: A Streamlined Approach with Utoipa and Schemathesis][123] +- [Olly Dixon: Auto-generating API service using Rust, to TypeScript & Dart][124] +- [Joshua Mo: Working with OpenAPI using Rust][125] @@ -139,6 +142,7 @@ After completing everything above, you should be able to answer (and understand +[`apistos`]: https://docs.rs/apistos [`async-graphql`]: https://docs.rs/async-graphql [`cynic`]: https://docs.rs/cynic [`graphql-client`]: https://github.com/graphql-rust/graphql-client @@ -181,6 +185,8 @@ After completing everything above, you should be able to answer (and understand [121]: https://www.twilio.com/docs/openapi/generating-a-rust-client-for-twilios-api [122]: https://support.smartbear.com/swaggerhub/docs/tutorials/openapi-3-tutorial.html [123]: https://identeco.de/en/blog/generating_and_validating_openapi_docs_in_rust +[124]: https://www.polydelic.com/media/autogenerating-a-rust-api-to-typescript-and-dart +[125]: https://www.shuttle.rs/blog/2024/04/04/using-openapi-rust [200]: https://graphql.org/learn/queries [201]: https://graphql.org/learn/schema [202]: https://graphql.org/learn/introspection diff --git a/README.md b/README.md index 52c73d37..192069af 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,43 @@ Please, read [instructions][Getting Started]. Please, read [instructions][Submitting Solutions]. +### Toolchain + +- [rustup] for installing [Rust] toolchain and keeping it up-to-date. +- [CLion]/[IntelliJ IDEA] + [IntelliJ Rust] + [Toml][IntelliJ Toml] plugins as development environment (or any other on your choice). + + +### Bookshelf + +- [Rust Book] teaches and explains [Rust] basics. +- [Rust By Example] teaches you [Rust] basics using editable examples. +- [Rust Reference] is not a formal spec, but is more detailed and comprehensive than the [Rust Book]. +- [Cheats.rs] and [Rust SVG Cheatsheet] for quick reference. +- [Rust Edition Guide] for considering improvements of [Rust 2018] and [Rust 2021]. +- [Rust std lib] documentation. +- [Cargo Book] is a guide to [Cargo], [Rust]'s build tool and dependency manager. +- [Rustdoc Book] is a guide to `rustdoc` documentation tool. +- [Rust Cookbook] is a collection of simple examples that demonstrate good practices to accomplish common programming tasks, using the crates of the [Rust] ecosystem. +- [Rust Design Patterns] is an open source repository of [Rust] design patterns and idioms. +- [Effective Rust] is a collection of guidelines that had been learned from real world experience of creating software in [Rust]. +- [Rust API Guidelines] is a set of recommendations on how to design and present APIs for [Rust]. +- [Rust FAQ] answers common question about [Rust]. +- [Rust Playground] allows to share and check runnable [Rust] code snippets online. +- [Awesome Rust] is a curated list of [Rust] code and resources. +- [This Week in Rust] represents handpicked and subscribable [Rust] weekly updates. +- [Baby Steps] blog of [Nicholas Matsakis](https://github.com/nikomatsakis) shares useful [Rust] patterns, ideas and design decisions. + + + + +### Schedule + +Each step must be performed as a separate [PR (pull request)][PR] with an appropriate name and checkmarked here in README's schedule after completion. Each step is a [Cargo workspace member][13], so you can run/test it from the project root (i.e. `cargo run -p step_1_8`). __Consider to use [rustfmt] and [Clippy] when you're writing [Rust] code.__ + +Each step has the estimated time for completion. If any deeper investigation on step's theme is needed by you, then it's on your own. + +Do not hesitate to ask your mentor/lead with questions, however you won't receive any concrete answer, but rather a direction for your own investigation. _Mentor/Lead is the one who asks questions here, demanding concrete and complete answers._ + ## Curriculum - [ ] [0. Become familiar with Rust basics][Step 0] (1 week) @@ -216,3 +253,6 @@ Rustcamp materials were based on the [Rust Incubator](https://github.com/instrum [Rust Book]: https://doc.rust-lang.org/book [Progress Board]: https://github.com/rust-lang-ua/rustcamp_progress/blob/master/README.md [Graduates' Capstone Projects]: https://github.com/rust-lang-ua/rustcamp_projects + + +[13]: https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html