From ba1fcba196b44ff0ace10e1b9157e8119f6750cc Mon Sep 17 00:00:00 2001 From: glendc Date: Wed, 27 Sep 2023 11:00:20 +0200 Subject: [PATCH] refactor book from README blob to mdbook This was requested by some students in the past, and recently some in the community asked it again, so here you go. --- .github/workflows/deploy.yml | 39 + .gitignore | 1 + CNAME | 1 - README.md | 810 +----------------- _config.yml | 9 - book.toml | 11 + favicon.ico | Bin 15406 -> 0 bytes src/SUMMARY.md | 39 + src/appendix/appendix-i-install-rust.md | 43 + src/appendix/appendix-ii-webassembly-wasm.md | 34 + src/appendix/appendix-iii-native-apps.md | 24 + .../appendix-iv-rust-in-the-background.md | 38 + src/appendix/appendix-ix-shipping-rust.md | 20 + ...ppendix-v-python--javascript-developers.md | 16 + src/appendix/appendix-vi-more-material.md | 70 ++ src/appendix/appendix-vii-community-chat.md | 11 + src/appendix/appendix-viii-debugging-rust.md | 28 + ...-about-the-remaining-part-of-this-guide.md | 5 + ...project-or-start-a-project-from-scratch.md | 13 + ...r-the-first-time-to-an-existing-project.md | 11 + src/guide/learn-async-rust/README.md | 48 ++ src/guide/learn-async-rust/questions.md | 17 + .../learn-async-rust/rust-atomics-and-locs.md | 36 + src/guide/learn-async-rust/threading.md | 8 + src/guide/learn-async-rust/tower.md | 18 + src/guide/learn-more-rust/README.md | 4 + src/guide/learn-more-rust/extra.md | 64 ++ src/guide/learn-more-rust/questions.md | 15 + src/guide/learn-rust/README.md | 29 + src/guide/learn-rust/questions.md | 32 + src/guide/next-steps.md | 26 + ...ramming-for-experienced-developers-book.md | 27 + ...ing-the-zero-to-production-in-rust-book.md | 43 + src/intro/README.md | 24 + src/intro/about.md | 35 + {img => src/intro}/banner.png | Bin src/intro/learning-rust.md | 37 + src/intro/prologue.md | 11 + theme/favicon.png | Bin 0 -> 5283 bytes 39 files changed, 881 insertions(+), 816 deletions(-) create mode 100644 .github/workflows/deploy.yml create mode 100644 .gitignore delete mode 100644 CNAME delete mode 100644 _config.yml create mode 100644 book.toml delete mode 100644 favicon.ico create mode 100644 src/SUMMARY.md create mode 100644 src/appendix/appendix-i-install-rust.md create mode 100644 src/appendix/appendix-ii-webassembly-wasm.md create mode 100644 src/appendix/appendix-iii-native-apps.md create mode 100644 src/appendix/appendix-iv-rust-in-the-background.md create mode 100644 src/appendix/appendix-ix-shipping-rust.md create mode 100644 src/appendix/appendix-v-python--javascript-developers.md create mode 100644 src/appendix/appendix-vi-more-material.md create mode 100644 src/appendix/appendix-vii-community-chat.md create mode 100644 src/appendix/appendix-viii-debugging-rust.md create mode 100644 src/guide/a-note-about-the-remaining-part-of-this-guide.md create mode 100644 src/guide/contribute-an-advanced-feature-to-an-existing-project-or-start-a-project-from-scratch.md create mode 100644 src/guide/contribute-for-the-first-time-to-an-existing-project.md create mode 100644 src/guide/learn-async-rust/README.md create mode 100644 src/guide/learn-async-rust/questions.md create mode 100644 src/guide/learn-async-rust/rust-atomics-and-locs.md create mode 100644 src/guide/learn-async-rust/threading.md create mode 100644 src/guide/learn-async-rust/tower.md create mode 100644 src/guide/learn-more-rust/README.md create mode 100644 src/guide/learn-more-rust/extra.md create mode 100644 src/guide/learn-more-rust/questions.md create mode 100644 src/guide/learn-rust/README.md create mode 100644 src/guide/learn-rust/questions.md create mode 100644 src/guide/next-steps.md create mode 100644 src/guide/study-using-the-rust-for-rustaceans-idiomatic-programming-for-experienced-developers-book.md create mode 100644 src/guide/study-using-the-zero-to-production-in-rust-book.md create mode 100644 src/intro/README.md create mode 100644 src/intro/about.md rename {img => src/intro}/banner.png (100%) create mode 100644 src/intro/learning-rust.md create mode 100644 src/intro/prologue.md create mode 100644 theme/favicon.png diff --git a/.github/workflows/deploy.yml b/.github/workflows/deploy.yml new file mode 100644 index 0000000..7a5c126 --- /dev/null +++ b/.github/workflows/deploy.yml @@ -0,0 +1,39 @@ +name: Deploy +on: + push: + branches: + - main + +jobs: + deploy: + runs-on: ubuntu-latest + permissions: + contents: write # To push a branch + pull-requests: write # To create a PR from that branch + steps: + - uses: actions/checkout@v3 + with: + fetch-depth: 0 + - name: Install latest mdbook + run: | + tag=$(curl 'https://api.github.com/repos/rust-lang/mdbook/releases/latest' | jq -r '.tag_name') + url="https://github.com/rust-lang/mdbook/releases/download/${tag}/mdbook-${tag}-x86_64-unknown-linux-gnu.tar.gz" + mkdir mdbook + curl -sSL $url | tar -xz --directory=./mdbook + echo `pwd`/mdbook >> $GITHUB_PATH + - name: Deploy GitHub Pages + run: | + # This assumes your book is in the root of your repository. + # Just add a `cd` here if you need to change to another directory. + mdbook build + git worktree add gh-pages + git config user.name "Deploy from CI" + git config user.email "" + cd gh-pages + # Delete the ref to avoid keeping history. + git update-ref -d refs/heads/gh-pages + rm -rf * + mv ../book/* . + git add . + git commit -m "Deploy $GITHUB_SHA to gh-pages" + git push --force --set-upstream origin gh-pages \ No newline at end of file diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..7585238 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +book diff --git a/CNAME b/CNAME deleted file mode 100644 index 422e6c2..0000000 --- a/CNAME +++ /dev/null @@ -1 +0,0 @@ -rust-lang.guide \ No newline at end of file diff --git a/README.md b/README.md index a06d5a3..32335c9 100644 --- a/README.md +++ b/README.md @@ -33,811 +33,9 @@ This guide is fully open source and the complete source code can be found at . The videos are however not of the highest quality, especially given the many better resources out there. -## Learning Rust +## Learning Guide -Becoming proficient in Rust requires the fulfillment of three pillars: +Source code for this guide is available under [./src](./src). -- Pillar I: Learn Rust and get your foundations right - - [1. Learn Rust](#1-learn-rust) - - [2. Learn More Rust](#2-learn-more-rust) - - [3. Learn Async Rust](#3-learn-async-rust) - - [6. Study using the "Rust for Rustaceans: Idiomatic Programming for Experienced Developers" book](#6-study-using-the-rust-for-rustaceans-idiomatic-programming-for-experienced-developers-book) -- Pillar II: Develop with Rust (Practical Experience) - - [4. Study using the "Zero to Production in Rust" book](#4-study-using-the-zero-to-production-in-rust-book) - - [5. Contribute for the first time to an existing project](#5-contribute-for-the-first-time-to-an-existing-project) - - [7. Contribute an advanced feature to an existing project or start a project from scratch](#7-contribute-an-advanced-feature-to-an-existing-project-or-start-a-project-from-scratch) -- Pillar III: Be part of the Rust Ecosystem: - - [Next Steps](#next-steps) - -What steps of each pillar you do is not of too much problem, do whatever feels best for you. -You can of course complete all steps, and do them in the order as given, but most likely -you probably want to use this learning guide more as a reference and for inspiration, -rather then to follow it word by word. - -The above paths are just a suggestion and also should make clear that there are many ways and approaches to using this guide. -Most important is that you do enjoy the journey and that you learn consistently (e.g. ~ X hours per week). How you'll walk the path and how often you revisit things will depend on your learning style and capabilities. There are however no wrong ways to go. E.g. maybe you want to dive into some code yourself as soon as possible and only then will start covering foundations. Or perhaps you first wanna feel very comfortable to only then start really coding yourself once you think you understand the foundations well. All up to you really. - -Only thing I would really want to hammer on is to do a lot of coding yourself. The best way to learn is to do. So don't be afraid to make mistakes and to try things out. You'll learn a lot more that way. It will be a very confronting journey but it will be worth it. If all you do is read and read you'll never really get a feel for the language and you'll never really get a feel for what you can do with it. So please, do a lot of coding yourself. Plus at times we can trick our brain into thinking we understand something when we don't. - -Also even if you start to reach advanced topics (e.g. Rust for Rustaceans), it is still very important to keep doing the basics. You'll be surprised how quickly you can forget things. So keep doing the basics and keep doing the advanced topics. It is a never ending journey. - -You'll notice when reading this guide that there are often alternatives mentioned or several layers of difficulty. With this in mind it might very well be your choice to go through a section shallow to start, going through the basic/foundational material, to then come back to it after having gone through other sections already with more experience under your belt. At this point you might have more confidence to get to the more advanced material of the section or have gained the background or mindset to understand that content and get more out of it. The spatial repetition as a result is on top of this all an excellent way to slowly but surely mold your grey mass into the desired shape. - -In case you are not planning to work on a project anytime soon that requires Async programming. Feel free to skip [that section](#3-learn-async-rust) for the time being should it be the case. For now just know that official Async support in Rust exists and that it has an important place within the Rust ecosystem. You can always come (back) to it at a future point when you do decide or realize that strong foundations in this section can help out. - -If you ever feel stuck, or want a guide, teacher or mentor. Feel free to reach out to Glen at [glen@plabayo.tech](mailto:glen@plabayo.tech) to book a 1-on-1 session or a workshop for your organization. It can be a one time thing or we can meet regularly to help you along the way. - -## Sponsors - -Support this project by becoming a [sponsor](https://github.com/sponsors/plabayo). - -## [Index](#index) - -- [About](#about) -- [1. Learn Rust](#1-learn-rust) -- [2. Learn More Rust](#2-learn-more-rust) - - [Learn More Rust: Extra](#learn-more-rust-extra) - - [Code like a pro in Rust](#code-like-a-pro-in-rust) - - [A Crust of Rust](#a-crust-of-rust) - - [API Design](#api-design) -- [3. Learn Async Rust](#3-learn-async-rust) - - [Threading](#threading) - - [Tower](#tower) - - [Rust Atomics and Locks](#rust-atomics-and-locks) -- [A note about the remaining steps of this guide](#a-note-about-the-remaining-part-of-this-guide) -- [4. Study using the "Zero to Production in Rust" book](#4-study-using-the-zero-to-production-in-rust-book) -- [5. Contribute for the first time to an existing project](#5-contribute-for-the-first-time-to-an-existing-project) -- [6. Study using the "Rust for Rustaceans: Idiomatic Programming for Experienced Developers" book](#6-study-using-the-rust-for-rustaceans-idiomatic-programming-for-experienced-developers-book) -- [7. Contribute an advanced feature to an existing project or start a project from scratch](#7-contribute-an-advanced-feature-to-an-existing-project-or-start-a-project-from-scratch) -- [Next Steps](#next-steps) -- Appendix: - - [Appendix I. Install Rust](#appendix-i-install-rust) - - [Linting and styling](#linting-and-styling) - - [Appendix II. WebAssembly (WASM)](#appendix-ii-webassembly-wasm) - - [WASM Learning Resources](#wasm-learning-resources) - - [Appendix III. Native Apps](#appendix-iii-native-apps) - - [Tauri](#tauri) - - [Appendix IV. Rust in the background](#appendix-iv-rust-in-the-background) - - [Appendix V. Python / Javascript developers](#appendix-v-python--javascript-developers) - - [Appendix VI. More Material](#appendix-vi-more-material) - - [Keep up to date](#keep-up-to-date) - - [Lists](#lists) - - [Read](#read) - - [Educational](#educational) - - [Appendix VII. Community Chat](#appendix-vii-community-chat) - - [Appendix VIII. Debugging Rust](#appendix-viii-debugging-rust) - - [Appendix IX. Shipping Rust](#appendix-ix-shipping-rust) - -## [About](#about) - -[Glen De Cauwsemaecker](https://www.glendc.com/) created this Educational track to help you get started with [Rust][rust] from an absolute beginner all the way until you're an expert in it. He is open to mentor people, lead workshops and more. If you're a team lead that wants to introduce Rust to their team, feel free to talk to him. Glen started with Rust around 2015, when Rust was still unstable and fast moving. Coming from a C++ background in a system programming job the benefits were immediately clear to him. In the meanwhile things have changed a lot and many companies have been starting to adopt Rust in their toolset: - -- Amazon Web Services (AWS) has used Rust since 2017 for its serverless computing offerings, AWS Lambda and AWS Fargate. With that, Rust has gained further inroads. The company has written the Bottlerocket OS and the AWS Nitro System to deliver its Elastic Compute Cloud (EC2) service. -- Cloudflare develops many of its services, including its public DNS, serverless computing, and packet inspection offerings with Rust. -- Dropbox rebuilt its backend warehouse, which manages exabytes of storage, with Rust. -- Google develops parts of Android, such as its Bluetooth module, with Rust. Rust is also used for the crosvm component of Chrome OS and plays an important role in Google's new operating system, Fuchsia. -- Facebook uses Rust to power Facebook's web, mobile, and API services, as well as parts of HHVM, the HipHop virtual machine used by the Hack programming language. -- Microsoft writes components of its Azure platform including a security daemon for its Internet of Things (IoT) service in Rust. -- Mozilla uses Rust to enhance the Firefox web browser, which contains 15 million lines of code. Mozilla's first two Rust-in-Firefox projects, its MP4 metadata parser and text encoder/decoder, led to overall performance and stability improvements. -- GitHub's npm, Inc., uses Rust to deliver "upwards of 1.3 billion package downloads per day." -- Oracle developed a container runtime with Rust to overcome problems with the Go reference implementation. -- Samsung, via its subsidiary SmartThings, uses Rust in its Hub, which is the firmware backend for its Internet of Things (IoT) service. -- [The U.S. Department of Commerce's National Institute of Standards and Technology (NIST) has added Rust to its list of "Safer Languages" as part of its Software Assurance Metrics and Tool Evaluation (SAMATE)](https://foundation.rust-lang.org/news/rust-identified-as-safer-coding-tool-by-nist/). - -Google also has a nice article about Facts and Debunked Myths about Rust which you can find at (2022). - -The language and its ecosystem have also very matured. Concepts like Async have also landed and Async runtimes such as Tokio have become stable and can be used without fear. While it was harder to convince companies to jump on the Rust wagon in the past, by now it should be a lot easier to sell. Is it one language to replace them all? Of course not, but neither should it be overlooked. Are you not sure how Rust might benefit your team for one thing or another? Contact [Glen](https://www.glendc.com/) and figure it out together. - -If you are a bit of a history nerd you might also enjoy: - -- this article: [How Rust went from a side project to the world's most-loved programming language](https://www.technologyreview.com/2023/02/14/1067869/rust-worlds-fastest-growing-programming-language/) -- or this podcast: [History of Rust with Ben Striegel — Rustacean Station](https://rustacean-station.org/episode/042-ben-striegel/) - -There's a [last section on the end of the Rust learning content](#appendix-vi-more-material). -This one contains useful references and sources that you can check as part of your -continuous journey as a capable Rust developer. - -In case you are a Python or Javascript developer you might find the [Appendix V. Python / Javascript developers](#appendix-v-python--javascript-developers) section useful. - -Not convinced yet? Read here what others have to say about Rust: - -## [1. Learn Rust](#1-learn-rust) - -In case you're new to the language we suggest you to take a look at [Learn Rust](https://www.rust-lang.org/learn) (free): - -- [The Rust Programming Language - The Rust Programming Language](https://doc.rust-lang.org/book/) gives you a very nice overview; - - There are plenty of exercises in the book and at the end of your learning journey you'll get to [build your own multi-threaded web server](https://doc.rust-lang.org/book/ch20-00-final-project-a-web-server.html)! -- [GitHub - rust-lang/rustlings](https://github.com/rust-lang/rustlings): Small exercises to get you used to reading and writing Rust code! is an alternative more pragmatic approach on learning the language; -- [Introduction - Rust By Example](https://doc.rust-lang.org/stable/rust-by-example/) is there for people who like learning from real-world examples; -- is yet another alternative, this time offered by Microsoft, - which seems very similar to the rust book, but more pragmatic tones and you can earn XP! - -Sooner or later you might also need help for a project you work on or simply to learn a concept you do not really understand. Not everybody has a senior or friend around that can help them out with this. For all of this and more you want to probably join one or multiple of the community chat servers listed in [Appendix VII. Community Chat](#appendix-vii-community-chat). - -> ⓘ **Hardcore** alternative -> -> [Programming Rust, 2nd Edition](https://www.oreilly.com/library/view/programming-rust-2nd/9781492052586/) (O'Reilly Publishing) is a big book and will take you some time to get through. It is not for the faint of heart. However… If you do choose for this route as an alternative to [(1) Learn Rust](#1-learn-rust), you will absolutely not regret it. In fact, your entire rest of the Journey will be a breeze. -> -> The "Programming Rust, 2nd Edition" book is a gem and in case you can handle big dry Technical books such as these it is one that will give you just as much love back as the energy that you put into it. Take your time, get through it, play with it, and enjoy. In fact, it can be easily paired with Rustlings by doing the exercises linked to the content you're reading. Rust by Example can also be added on top of that to see some more code related to the stuff you're learning. -> -> Soak it in. It's a hardcore alternative, but if you're up for it, it's there for you to grab. -> -> If you've never done any Systems programming before, this will be an especially helpful book given it will explain a lot of the magic you've encountered in your very protected professional life so far. You're welcome. - -Questions you should be able to answer at the end of this step: - -1. Rust is a Memory-Safe language. How? Why? In what way is this different from other Memory Safe languages such as Go? -2. Rust is a performant language. Why can it claim this. How? -3. How do you structure data in Rust? -4. Is data passed by Reference or value in Rust? And what does it mean? -5. Is data mutable or immutable by default? How do we make it the other way? -6. What are traits and how are these related to the data models that you structure in Rust? -7. How can you extend the behavior of external types? -8. Can you extend behavior of external types using external traits? Why or why not? -9. What is a constant? Where can we define these? -10. What is a static variable? How is it different from a constant? What's special about mutable variables? -11. How does Rust support Async Rust? How do you use it? What are Futures? -12. How do you achieve parallel programming in Rust? -13. What's the difference between async programming and parallel programming? How are they related? -14. What is the borrow checker? What is ownership? How are these concepts related? -15. Data can be moved and it can also be dropped. What do we mean with this? How do we have control over this? -16. How do we achieve shared mutable references to the same data? How can this be done safe? -17. What are lifetimes? How do they work? Can you give some examples of where these are used? -18. What are generics? Why do we use them? -19. What are Rust Macros? When do we use these? What type of Macros are there? -20. How do you build Rust projects? -21. How do we use dependencies of other developers into our projects? And how do we call such dependencies? -22. What are sum types? What are product types? -23. What is an Enum in Rust and how can we use it? How can we define it? -24. What is pattern matching in Rust? How do we do it? How is it more powerful than a switch? -25. How do we write tests in Rust? What kind of tests are there? -26. What are closures and how are they related to functions? What do they have in common? How do they differ? -27. What kind of smart pointers does the Rust std library provide you? What are their use cases, differences, and so on? -28. What is unsafe Rust? How do we use it? When do we use it? What guarantees do we still get, even when using unsafe Rust? - -### [Alternative or Companion resources](#alternative-or-companion-resources) - -[Welcome to Comprehensive Rust 🦀 - Comprehensive Rust 🦀](https://google.github.io/comprehensive-rust/): a small bootcamp course by Google focused on Android Engineers. Most of it is however applicable to anyone coming to Rust from another language and could be a great alternative or companion for some of the resources above. - -[The "Effective Rust" book](https://www.lurklurk.org/effective-rust/) is an excellent book that might just as well be official Rust material, and -recommended for all Rust learners. So once you think you understand the content of "the Rust book" and the like, you probably want to start reading "Effective Rust", you won't regret it. - -## [2. Learn more Rust](#2-learn-more-rust) - -- [Introduction - The Cargo Book](https://doc.rust-lang.org/cargo/index.html): Cargo is the Rust package manager. Cargo downloads your Rust package's dependencies, compiles your packages, makes distributable packages, and uploads them to crates.io: [Rust Package Registry](http://crates.io/), the Rust community's package registry; -- [Getting started - Command Line Applications in Rust](https://rust-cli.github.io/book/index.html): Gives you another practical approach in your Rust Learning, by specifically learning how to write CLI applications in it; - -Questions you should be able to answer at the end of this step: - -1. Make sure to be able to answer all questions of step (1). -2. What is cargo and why does it exist? -3. What kind of extensions exist for Cargo, how do we install them, how do we use them and what are some commonly used ones? -4. What is the Cargo.toml file? -5. What is the Cargo.lock file? -6. What are build scripts? Why do we use these? How do we use these? -7. How can we build code? How do we test code? -8. How can we check code without building the final binaries? -9. How do we make a simple CLI application? How do we pass arguments and flags? How do we handle signals? -10. How can we structure our code and package(s)? -11. What does public and private mean in the context of Rust? At what scope do these operate? - -### [Learn More Rust: Extra](#learn-more-rust-extra) - -Once you went through the resources in the previous two chapters you might want to start working on a real project to start applying and solidifying your knowledge. A classic way to do this is by porting a small specialized codebase from one language to Rust, keeping in mind to not 1-to-1 map the lines of code but to instead focus on porting the logic with the "Rust way to do things" in mind. - -Should you want some inspiration or a more guided approach, here are some resources that could help you out with this extra optional, but recommended step: - -- [Command-Line Rust](https://www.oreilly.com/library/view/command-line-rust/9781098109424/): build a cli tool such as grep in rust, using test driven development (TDD), all to learn Rust -- [Rust Application Books - The Little Book of Rust Books](https://lborb.github.io/book/applications.html): lists a lot of different books, including ones that allow you to develop small projects using Rust, usually in a well guided fashion; - - You might find an interesting companion article as it gives some (common) ideas that you can apply to the CLI tool you're building; - - [Introduction - PNGme: An Intermediate Rust Project](https://picklenerd.github.io/pngme_book/introduction.html) is an especially fun small project. It allows you to apply the knowledge that you learned above in a very narrow program, that is for once not network related. At the end you'll have a cli tool that allows you to encode and decode "hidden" messages in a PNG image; -- [Introduction - MacroKata](https://tfpk.github.io/macrokata/index.html): Macro's are in general not very covered in the resources above, as it is not that common that you have to write your own macros. They can however be convenient in certain situations. This book can be seen as a bootstrap tutorial to get you started with one kind of Rust macros. - - If you are interested in (also) learning procedural macros you can perhaps consult the following resources: - - [GitHub - dtolnay/proc-macro-workshop: Learn to write Rust procedural macros [Rust Latam conference, Montevideo Uruguay, March 2019]](https://github.com/dtolnay/proc-macro-workshop) - - [Procedural Macros in Rust (part 1)](https://www.youtube.com/watch?v=geovSK3wMB8) - - Check out "[Diesel is a Safe, Extensible ORM and Query Builder for Rust](https://diesel.rs/)" if you want to see a very cool example of macros (besides all the derives, formatting and printing you might already have been doing) - - [json in serde_json - Rust](https://docs.rs/serde_json/latest/serde_json/macro.json.html) is another neat example as it allows you to quickly define a Json value directly in Rust - - Taking a couple of hours is also a life well spent reading through this codebase as it will teach you a lot of nice things about Rust, especially given how simple and scoped the problem of json serialization is. It will really show you and teach you how serde works and why it works; - - Most web frameworks (if not all) in Rust also heavily make use of Macro's to give you a very neat and clean API - - And of course do not forget to consult the "classic" macro Rust book: [The Little Book of Rust Macros](https://danielkeep.github.io/tlborm/book/index.html) - - If you want to get a quick intro and overview of Macros this video can help a lot as well: [Rust's Witchcraft](https://www.youtube.com/watch?v=MWRPYBoCEaY) - -If you have a lot of free time at your hand and you want to build something really cool that is totally useless, here are some more ideas: - -- Build your own Gameboy (classic) emulator: [Introduction - DMG-01: How to Emulate a Game Boy](https://rylev.github.io/DMG-01/public/book/introduction.html) -- Build your own CHIP-8 (8-bit computer) interpreter: [Cowgod's Chip-8 Technical Reference](http://devernay.free.fr/hacks/chip8/C8TECH10.HTM) (no Rust guidance, directly from the CHIP-8 specification instead, you can do it, I believe in you) -- Build your own Ray Tracer (not a Rust tutorial, but can easily be implemented in Rust as well): [Ray Tracing in One Weekend Series](https://raytracing.github.io/) (fun if you always had the dream to start dabbling into the world of Graphics Programming) - - might be a useful blog series if you want a more guided approach on how you might make a Ray Tracer in Rust; - - is an interesting article in this area as well, where it introduces you to a language called PO; - -Seriously though, do not consider the above recommended or mandatory in any way. If you however really like to develop stuff and you do like to do it extensively in your free time, then, and only then, I do believe that the above are a great way to really solidify your current Rust knowledge and give yourself a great (pragmatic) foundation. - -At this point you might also be ready to start reading alternative — community driven — learning resources on foundational Rust knowledge. With such content you do however always need to be careful as they might contain mistakes, not well rounded or closed opinions. An example of possible valuable learning resources are the following blog series about the Rust type system: - -- part 1 (): ownership and move semantics, aliasing and mutation, lifetime and region based resource management; -- part 2 (/): type as sets, algebraic data types, patterns in Rust using Algebraic types, traits, generic associated types (GAT), operator overloading, use cases; -- part 3 (/): container types, interior mutability, concurrency, deadlocks without threads. - -More parts to come as well. - -For the brave among you with the time for it, learn to build your own Operating System (OS) using Rust: - -### [Code like a pro in Rust](#code-like-a-pro-in-rust) - -At this point of your Rust learning journey you've come a far way already, relatively speaking. Perhaps you want to shortcut, at least for now. - -If so, [the still to be published "Code like a pro in Rust" book](https://www.manning.com/books/code-like-a-pro-in-rust) might be enough for you to quickly get from beginner to advanced Rust programmer. - -### [A Crust of Rust](#a-crust-of-rust) - -Once you get at this point you are around the level of a beginner or intermediate Rust programmer. At this point you could already start to tackle stuff like ["Rust for Rustaceans" of step (6)](#6-study-using-the-rust-for-rustaceans-idiomatic-programming-for-experienced-developers-book). However it might be a bit much. - -Therefore while you go through the next couple of sections it could be helpful to now and then (e.g. while washing dishes or instead of Netflix) an education Rust code video. In the appendix at the bottom of this page there a couple of such suggestions. - -Particular to this context you might want to save [the "Crust of Rust" playlist](https://www.youtube.com/playlist?list=PLqbS7AVVErFiWDOAVrPt7aYmnuuOLYvOa). Each video will go over a specific topic, e.g. Lifetimes, macros, Atomics, … No need to watch them one by one, feel free to jump to them in whatever orders and only those that interest you (which is the same tip that I can give for the "Rust for Rustaceans" book). - -### [API Design](#api-design) - -Designing APIs is a big part of being a Rust programmer, any programmer really. Once you start to get comfortable enough in Rust or start building your own public crate, it is a topic you'll want to invest in. - -A good starting point is the [API Guidelines](https://rust-lang.github.io/api-guidelines/about.html) which are a set of guidelines that are meant to help you design good APIs. They are not meant to be followed blindly, but rather to be used as a reference to help you make the right decisions. - -A next and continuous step is to read blog posts and watch videos about API design. The Rust newsletter often has an article listed in its weekly edition. But other platforms such as HackerNews will have interesting Rust articles pop up as well. is for example a great article talking about one might to give errors as much love as the other parts of the API, and also talks about why crates like `thiserror` might not be that great. All in all, similar to other parts of your continuous Rust learning journey, you'll want to remain critical and open to new ideas and see what works for you and what not. - -If you are however still in the camp of `thiserror`, you might be able to make good use of blog posts such as that guide you through adding instrumentation to your Axum based web service, -using `thiserror` among other excellent crates such as `tracing`. A great read, especially if you're not that experienced with instrumentation -that goes beyon the basic single line logs. - -## [3. Learn Async Rust](#3-learn-async-rust) - -There is no standard / official Asynchronous runtime. This in contrast to actual CPU threads [which you can create from within the std library](https://doc.rust-lang.org/std/thread/fn.spawn.html). - -The most popular and recommended by many Async Runtime is [the Tokio runtime](https://tokio.rs/). Which brings us to the next chapter: - -- To start with your Async Learning Journey you might want to start with: [Getting Started - Asynchronous Programming in Rust](https://rust-lang.github.io/async-book/); -- Afterwards you can finally start going through the Tokio [learning journey Tutorial](https://tokio.rs/tokio/tutorial) - -Please also join the Tokio Discord community as part of your async Journey, a place where you can ask any questions you want as well: . This server also has individual channels for the different projects in the Tokio ecosystem such as Hyper, Axum, Tower and more. The maintainers of the different projects are also very active in the server and are happy to help you out, but of course please do not take this for granted. Be respectful and if possible contribute back to the community as well. - -The following article is a very nice introduction to Rust async: . - -Extra Learning Resources: - -- ; -- : great article to make you think about why Async rust might feel so wrong. - - A big problem is that most people use Tokio in multithreade mode which puts extra restrictions (Send + 'Static), - which makes Async feel extra difficult. - - It's also important that people, next to having experience with Tokio and getting a good understanding of Async rust and all it entails, - to also discover, play and use other async runtimes. - - is a great alternative Async runtime that you might want to try out; -- Learn more about Async Rust and what the current situation is/was in 2023: - -As an extra, and perhaps slighty sidetracked, you may also want to read and develop alongside the following articles: - -- [The HTTP crash course nobody asked for](https://fasterthanli.me/articles/the-http-crash-course-nobody-asked-for) -- [Understanding Rust futures by going way too deep](https://fasterthanli.me/articles/understanding-rust-futures-by-going-way-too-deep) -- To get to get a deeper understanding about the concepts of pinning and the like you might find the following articles helpful: - - [Put a pin on That](https://archive.is/pHfCn) - - This article refers also to [Pin, Unpin and why Rust neeeds them](https://archive.is/LH91o) - - as well as [Pin and Suffering](https://archive.is/32RlT) - - All of the above are great articles to get you quickly up to speeds with the concept, and helpful as a repeater or because you hvae no desire or time to read some of the books that talk about this topic and that I recommend in other parts of this guide; - -In order to help you understand how Async code works (e.g. what about the Async keyword and How do futures really work. And how do you define traits with futures. And How do you implement them), you might want to read through the articles linked in the [Tower](#tower) section, as seeing how to implement your own _Tower_ middleware might answer many of such questions. Gaining a deeper theoretical but still pragmatic enough understanding behind it is probably better done by reading some of the books listed in this guide. - -> ⓘ Note: Tokio also provides support to [the new Linux kernel io_uring concept](https://unixism.net/loti/), a new powerful way to allow async programming on Linux. Support for it can be found at: [GitHub - tokio-rs/tokio-uring: An io_uring backed runtime for Rust](https://github.com/tokio-rs/tokio-uring) -> -> Synacktiv made an IO network scanner using io_uring as can be seen at [GitHub - synacktiv/io_uring_scanner: io_uring based network scanner written in Rust](https://github.com/synacktiv/io_uring_scanner), using tokio's low level userspace bindings to io_uring. - -To get a better idea about how futures work and the executor which polls them, you might want to read this article: . - -The blog series as found at can be another great reference to help you understand the entire `async/await` part of Rust: - -- [part 1: why doesn’t my task do anything if I don’t await it?](https://hegdenu.net/posts/understanding-async-await-1/) -- [part 2: how does a pending future get woken?](https://hegdenu.net/posts/understanding-async-await-2/) -- [part 3: why shouldn’t I hold a mutex guard across an await point?](https://hegdenu.net/posts/understanding-async-await-3/) -- [part 4: why would I ever want to write a future manually?](https://hegdenu.net/posts/understanding-async-await-4/#why-would-i-ever-want-to-write-a-future-manually) - -Questions you should be able to answer at the end of this step: - -1. How does Async programming work in Rust, if you didn't understand this already? -2. What types of concurrent programming does Rust support? How many are there in general? -3. What are Futures and how do they work? What function they have? How do they affect you? -4. What is Send and Sync? What is it used for? How does it affect you? -5. What are good use cases of Async code? What kind of tasks aren't a good fit for this? -6. What are Async Executors? What are Async Runtimes? -7. What is Tokio? How do you use it? What does it give you? -8. What are some other libraries in the Tokio ecosystem? -9. What can you build with Tokio? -10. Why would you use Tokio? -11. How do you achieve Async Rust programming with only standard library (stdlib) code? -12. Why does Rust not bundle an Async runtime? -13. What is parallel programming? How do you do it in Rust? How does it relate to Async programming? - -### [Threading](#threading) - -Please do remember that Async programming is only beneficial to optimize the idle time of your threads away. -For tasks where you already near 100% utilize your threads (e.g. computation heavy algorithms) something -like async will not help you and will in fact make your codebase a lot more complex and difficult to reason about. - -Should you have computation-heavy algorithms which you want to parallelize you can achieve that by making use -of [threading](https://doc.rust-lang.org/std/thread/) alone. A crate such as might help you a lot with this as well. - -### [Tower](#tower) - -Once you step into the world of Async Rust, Tokio and Web Services you'll sooner or later come across [Tower](https://github.com/tower-rs/tower), in a similar fashion as [Serde](https://serde.rs/) blew your mind away for your serialization needs. Yes it did, you can admit it, this is a safe space. - -> ⓘ Tower is a library of modular and reusable components for building robust networking clients and servers. - -With [Tower](https://github.com/tower-rs/tower) everything is a service. A service takes in a request and outputs either an error or a response. -What the actual types for these request-response pairs are, is up to you and depend mostly on the layer it is used. - -In tower it is typical that a service wraps another service, called "layers", as such all your services and middleware will stack on top of each other, -like a... _tower_. - -- if you are new to Tower, you can start learning how to use it by building your own tower middleware from scratch by following the guide at: ; - - if you are not convinced on the usefulness of Tower, you can perhaps read [the "inventing your own Service trait" guide](https://tokio.rs/blog/2021-05-14-inventing-the-service-trait). - -If you want to get an idea of how `Tower` might look like in a Rust ecosystem since 2024, -you can enjoy this future today already at . -Have fun not requiring to implement futures by hand. - -### [Rust Atomics and Locks](#rust-atomics-and-locks) - -Understanding concurrency, the primitives used to do so safely and how it all works "under the hood" (e.g. the OS level) is not critical but it will help you big time the rest of your Async professional career. - -The book "[Rust Atomics and Locks](https://marabos.nl/atomics/)" by O'Reilly is an amazingly good book by Mara Bos, an important Rust Contributor. Going through the book will take you some time despite its smaller size, but doing so is very rewarding. As with any technical book it is best to read this book as well as do its exercises and apply its knowledge using one program or another. Learn, Apply, Repeat. Play with it, Understand it. - -This book is so good, that even Go, Python or JS developers that will never ever touch Rust, might want to learn Rust just to understand the knowledge that can be found in this Gem of a book. Read it. You won't regret it. - -As it is more advanced knowledge it can however be seen as "Extra", so in case you are in a hurry to finish [section (3) of the Rust track](#3-learn-async-rust), feel free to skip it. But even if so, keep its existence in mind and come back to it perhaps when you start to get yourself into trouble. - -Questions you should be able to answer at the end of this extra step: - -1. What primitives are there in general to achieve concurrency? -2. What primitives does the OS give you? -3. What is the difference between threads and async programming? -4. Why is async programming faster? -5. When would you use threads? When would you use async programming? -6. What's a Mutex? How could you implement one? -7. What's a Conditional Variable? How could you implement one? -8. What's a Signal? How could you implement one? -9. What's a Channel? How do you implement it? What types of channels are there? -10. What is Reordering? How can we deal with this? How does it affect us? -11. How can we efficiently make a thread go to "Sleep" and have it woken up again? -12. What's a Spin Lock? How do we build one? -13. What's an atomic? What kind of atomics are there? How do they work under the hood? -14. How does Rust achieve thread safety? -15. What's Memory Ordering? What's the Memory Model? What types are there? Which ones can you use? -16. What is Acquire and Release? What is this an example of? -17. When we talk about a "happens-before relationship". What do we mean with it? Why is it important? -18. What is caching in context of your CPU? How does it affect us? What can we do about it? - -> FYI: if you ever write real-world production low level sync/atomic/concurrent code, -> you might want to check out Loom, as it will help you test that code better then possible with regular tests: -> . - -## [A Note About the remaining part of this guide](#a-note-about-the-remaining-part-of-this-guide) - -The next sections are all optional and are not required to really be productive in Rust. Some of it are alternative resources or extra content to learn from. Others is just miscellaneous content that is not really required to be productive in Rust, but might be interesting to you. - -This guide is either way not meant to be read in a single session or series. Take it as yours and just use it as part of your learning journey. Take your time as learning Rust isn't easy, but it is a very rewarding one once you did climb the mountain and are dancing with a double rainbow in the background. - -## [4. Study using the "Zero to Production in Rust" book](#4-study-using-the-zero-to-production-in-rust-book) - -> 🔗 - -Go through the entire book, filling any gaps you might still have and do all the exercises as well. - -At the end of the book you should be able to present your own GitHub or GitLab hosted projected based on the exercises and projects of the books, where you applied all your knowledge and also put in something of yourself in it. - -> ⓘ Backend frameworks like [Rocket](https://rocket.rs/) and [Actix](https://actix.rs/) are pretty commonly used in books. However know that [the Axum framework](https://docs.rs/axum/latest/axum/) is currently probably your best if you need to choose a backend framework for your next or current Rust project. -> -> Learning Axum in specific could be done by following tutorials -> such as , which seem pretty complete and focussed. -> -> Given how much Axum is built with [Tower in mind, you probably also want to learn that](#tower). - -> There's also a "Crust of Rust" episode, by Jon Gjengset, about "decrusting" -> Axum — and by extension _Tower_ — available at . - -Questions you should be able to answer at the end of this step: - -1. How can we write a Full stack app in Rust? -2. How can we deploy and host a Full stack Rust app in the cloud? -3. How can we add telemetry? -4. How can we interact with Databases using Rust? -5. How can we debug production-quality Rust applications? -6. How can we test Rust applications? -7. How do we make Async applications in Rust? -8. How do we achieve TLS capabilities with Rust? -9. How do we make a web server with Rust? -10. The book uses Actix. What are some alternatives these days? - -### Alternatives - -The goal of hands-on learning with "Zero to Production" is mostly to help you get started writing some -actual Rust projects, there are however also plenty of alternatives to achieve the same. - -- is an interactive book to help you practice Rust by doing projects; -- is a similar concept, which also has a discord and a bit more variety in projects; -- most Rust conferences also have workshops, free or paid, to help you get into Rust or tackle more advanced concepts; -- Shuttle, which allows you to build and ship Rust code, also has a series of tutorials to create, build and ship all kind of projects, - available at ; -- is a paid platform (with very limited free tier) is a platform to help you build projects like your own - Redis, Git, Grep, Docker and more. And that all using Rust (among other languages available); - -## [5. Contribute for the first time to an existing project](#5-contribute-for-the-first-time-to-an-existing-project) - -Contribute to an open source project that you like or may want to strongly depend upon in the future. - -Many projects have a `good first issue` label, which is a good place to start. You can also look for issues that are labeled `help wanted` or `easy`. - -There's also the Rust Mentorship program, which pairs up new contributors with experienced Rustaceans. You can find more information about it at: - -In [The weekly Rust Newsletter](https://this-week-in-rust.org/) you can find a list of projects that are looking for contributors. - -If you are a seasoned programmer already you might also opt to already start making your own new project or porting a scoped project from another language to Rust. - -## [6. Study using the "Rust for Rustaceans: Idiomatic Programming for Experienced Developers" book](#6-study-using-the-rust-for-rustaceans-idiomatic-programming-for-experienced-developers-book) - -> 🔗 - -Go through the entire book, getting a deep(er) understanding of the advanced concepts and inner workings of them. - -At the end of the book you should be able to present your own GitHub or GitLab hosted projected based on the exercises and projects of the books, where you applied all your knowledge and also put in something of yourself in it. - -Questions you should be able to answer at the end of this step: - -1. Be able to answer all questions from previous sections, in full confidence and in a lot more depth than you could do before. -2. How is memory laid out for your Rust Data structures? Can you control it? If so, how? -3. Explain in full detail so someone new to Rust can understand it what borrowing and lifetimes are, how do they work, why are they important, how do they affect us, how do we encounter it, why do we use it? -4. What primitive types are there in Rust and how are they laid out in memory? -5. What is the Orphan rule? Why is it important? -6. What is polling in the context of Asynchronous programming? -7. List some additional testing tools beyond unit tests? Why does each one of them matter? -8. What is Pin and Unpin? - - Note: Crust of Rust also has a great video about it should you need some more explanations about this tricky concept; -9. Why is Asynchronous programming more complicated than parallel programming? -10. How can you test your Asynchronous code? And because it is Rust, what kind of Asynchronous problems do we not need to test if we structure our code right? And why not? -11. In the context of concurrent programming, what are actors? - - Bonus question: why do some people see this as the future? -12. What is FFI? Why do we use it? -13. What is Rust without the STD? How do we use it and why? -14. What are some common patterns found in the wild and that are discussed in the book? -15. How can you continue to learn Rust? - -## [7. Contribute an advanced feature to an existing project or start a project from scratch](#7-contribute-an-advanced-feature-to-an-existing-project-or-start-a-project-from-scratch) - -Start a project for yourself, your dog, your organization or mother. This might be a microservice, library or small tool. Everything is possible. - -Another option is to contribute to an open source project that you like or may want to strongly depend upon in the future. - -See [section (5) about your first contribution](#5-contribute-for-the-first-time-to-an-existing-project) for some inspiration on where to start. - -> As it is assumed that at this point you are doing intermediate level work in Rust -> it will be the case that sooner or later you'll need to debug. Or perhaps you are about -> to deploy your own small project to production. In any case, you'll need to know how to -> debug Rust applications. You can read all about this and tracing in -> [Appendix VIII. Debugging Rust](#appendix-viii-debugging-rust). - -## [Next Steps](#next-steps) - -If you have completed all the steps above, you have done more then enough and can call yourself a Rustacean. You can now start to contribute to the Rust ecosystem and help others to learn Rust. Perhaps more importantly, you have all the knowledge you need to build your own projects in Rust. - -What you'll build depends on your interest or perhaps in the type of industry or company you're working in. - -- If you're doing full stack development you can get inspired on what's next by checking out [WASM Learning Resources Appendix](#wasm-learning-resources); - - For all your web dev needs you might also get inspired on what frameworks to use by checking out a website such as ; - - By coincidence, some of the books and articles listed in this guide also teach you a lot about web development, so if you did indeed complete these guide you're really already well on your way to becoming a full stack developer in Rust, or backend, whatever floats your boat; -- Some call WASM (on the server side) the next thing after docker containers. So perhaps even as a "pure" backend developer you might want to check out [that _same_ appendix](#wasm-learning-resources) to help you get started; -- If you're a game developer (or inspiring to be) you can check out resources such as to figure out what Rust technologies are out there in the ecosystem to help you build the next fantastic game; - - If you're a game developer you might also want to check out the [Rust GameDev Working Group](https://gamedev.rs/) (they also have a monthly news letter); - - You could also subscribe to the a podcast about GameDev in Rust called [Rust GameDev Podcast](https://rustgamedev.com/); -- If you want to develop Operating Systems I already listed some resources to help you get started with that. - - Once (and if) Rust is accepted as a second language (next to C) to develop patches for the Linux kernel you can also start contributing to the Linux kernel in Rust. Future dreams; - - Or you might want to apply to Google and help build [their Fuchsia OS](https://fuchsia.dev/) in Rust. Have fun; - - It's open source so nobody can stop you to contribute it either way, well except them I guess; -- If you want to develop blockchain technology... Well, not going to guide you in that one, there's a running joke that it's hard to find a job in Rust that's not blockchain tech, so, you should have no problem finding a job in that field if that's what you want to do; - - Ok, ok. Here also a list for you folks: -- If you want to develop embedded systems, you can check out the [Rust Embedded Working Groups's Blog](https://blog.rust-embedded.org/). There are also plenty of companies who sometimes appear in articles or podcasts listed in [the More Material appendix](#appendix-vi-more-material), so you can also check that out for yourself. - - A podcast episode about the embedded WG can be found at: - - You can interact with the WG using the matrix chat: -- If you are interested in using Rust for Data Engineering then could be a great start; -- Related to the previous, if you want to use ML from within Rust (or together with it), you might find the following list a great resource: - -There's a lot more of course. You probably know best where you're going. A lot of exciting stuff is happening. Plenty of conferences (e.g. Rust Conf) to help you get inspired on it if you're not already. And of course, plenty of people to help you out if you get stuck. So, good luck and have fun! - -## [Appendix](#appendix) - -### [Appendix I. Install Rust](#appendix-i-install-rust) - -In order to start using Rust you have to install and configure its tooling on your machinery. - -- The Rust compiler (`rustc`), standard library and tooling (e.g. `cargo`) are all managed using `rustup`. - - You can learn how to get started by going to: - - Once you finished with this you'll have Rust ready on your machine out of the box. Each time there is a new version of Rust you can update it, simply by running `rustup update` - -With this installed you should now be able to run the following command: - -``` -cargo version -``` - -Which will output something like: - -``` -cargo 1.67.1 (8ecd4f20a 2023-01-10) -``` - -You can learn to create, compile and run your first Rust program at "[First Steps with Cargo - The Cargo Book](https://www.rust-lang.org/learn/get-started)". - -> If you are looking for a fun bigger project to help you learn Rust, -> you might find it fun to buy your own cargo-like tool: - -#### [Linting and styling](#linting-and-styling) - -- Install `clippy` using `rustup component add clippy` - - This way you can use the command `cargo clippy` to help guarantee the quality of your code -- Install `rustfmt` using `rustup component add rustfmt` - - This way you can use `cargo fmt` to format your code (best to also configure this in your IDE to be done each time you save the file) - -No custom linting configurations or agreements are required beyond this. If you use these two tools, you're golden. These tools also work nicely with any IDE you might use. Within your CI environment these same tools will be used to check that your code adheres to its standards. - -Clippy can be seen as a testing ground to see what lints are useful and which ones aren't. The ones that are often get shipped into the official compiler a while later. Some lints are also ignored by default for whatever reasons. You can find all lints (AFAIK) at , should you want to enable even more lints. - -Some useful reasons why you might stil want to enable custom lints are: - -- to enable nightly features; -- to prevent the usage (in your own codebase) of `unsafe` code. - -For reference you can check the mono repository's `lib.rs` files, -where I enable such opt-in lints myself, which itself is based on the original `tower-rs` code. - -### [Appendix II. WebAssembly (WASM)](#appendix-ii-webassembly-wasm) - -> ⓘ WebAssembly (abbreviated Wasm) is a binary instruction format for a stack-based virtual machine. Wasm is designed as a portable compilation target for programming languages, enabling deployment on the web for client and server applications. -> -> 🔗 - -WebAssembly on itself is completely isolated from Rust, but it must be said that among the WASM community, the Rust part is probably the biggest and most active one. Compiling Rust to WASM is a true pleasure and allows for browser client code to be written in Rust, be it a small library to be used from JS or an entire web client. WASM projects can also be used to quickly deploy web services (in the backend). These are similar to lambda functions but are even faster to use and in a way also safer. - -#### [WASM Learning Resources](#wasm-learning-resources) - -- RustWasm book: [Introduction - Rust and WebAssembly](https://rustwasm.github.io/docs/book/) - - This is the officially recommended book to get you started, as can be seen at -- [Programming WASM with Rust: Programming WebAssembly with Rust](https://www.oreilly.com/library/view/programming-webassembly-with/9781680506846/) -- Build a web app with Rust (using Yew framework): -- Rust to WebAssembly the hard way: [Rust to WebAssembly the hard way — surma.dev](https://surma.dev/things/rust-to-webassembly/index.html) - -Frameworks that you might want to check if you want to make a front-end (web) app using Rust: - -- Make desktop apps using web tech (think Electron, but better): [GitHub - tauri-apps/tauri: Build smaller, faster, and more secure desktop applications with a web frontend](https://github.com/tauri-apps/tauri); -- Very popular and fast front-end framework for Rust: [GitHub - yewstack/yew: Rust / Wasm framework for building client web apps](https://github.com/yewstack/yew) -- Another front-end framework: [GitHub - chinedufn/percy: Build frontend browser apps with Rust + WebAssembly](https://github.com/chinedufn/percy). Supports server side rendering. -- Yet another front-end framework: [GitHub - sycamore-rs/sycamore](https://github.com/sycamore-rs/sycamore): A library for creating reactive web apps in Rust and WebAssembly -- If you are looking for a complete framework you might want to give a chance, it builds on top of Sycamore; -- Exciting new and very fast front-end framework: [GitHub - leptos-rs/leptos: Build fast web applications with Rust](https://github.com/leptos-rs/leptos). -- Another front-end framework (or perhaps rather a GUI framework) that you might want to know about is Dioxus () which is made not only for web-apps, but also with CLI, mobile and Desktop in mind. -- Also a pretty nice front-end framework: [GitHub - framesurge/perseus: A state-driven web development framework for Rust with full support for server-side rendering and static generation](https://github.com/framesurge/perseus). - -Run WASM Backend Services in the cloud: - -- Cloudflare workers: [Cloudflare Workers®](https://workers.cloudflare.com/) -- Fermyon Cloud (free for now): [Deploy & manage cloud native WebAssembly apps](https://www.fermyon.com/cloud) -- Wasmer's goal is to run any code on any client (think Java's dream, but for real): - -As you can see, WASM on the backend is a thing. Whether it's more then just hype is something the future will tell, but either way a lot of interesting stuff is happening and there's big money behind it somehow. So you might as well jump in the car, especially if you missed the Docker train somehow. Happens. - -### [Appendix III. Native Apps](#appendix-iii-native-apps) - -Native apps are applications written for a specific platform. While that could be any platform, it usually refers to anything that is not the "web" and even more so, these days, it pretty much always refers to Desktop, Mobile or the combination of. Cross platform apps mean that multiple platforms are supported, which could be any set of web or non-web platforms. - -> If you ever need to interact with other native languages: -> -> - For C you probably want to just use bindgen; -> - For C++ you can make use of (cxx); - -#### [Tauri](#tauri) - -**Tauri** is the toolset you want to check out if you want to build native apps with a Gui in Rust. You can find all information about it on their official website: - -> ⓘ Build an optimized, secure, and frontend-independent application for multi-platform deployment. - -Tauri applications can be compared to Electron, but it uses a very different approach. Multiple rendering engines are supported, with web view like rendering engines being the default. But this is still different then shipping a Node runtime and Chromium with each one of your apps. Meaning your desktop applications can be as small as a couple of megabytes, compared to the usually bloated 150MB apps. And once running, they will also be a lot less resource hungry compared to your topical Electron app. - -Mobile applications are not yet officially supported, but they will soon get support as well, as the underlying technology for it is already more or less ready. - -In case you want to write applications that work on both the web and a non-web platform you can achieve this by splitting your business logic from your minimal front-end logic, such that you can write one front-end in any of the available front-end approaches (e.g. leptos or perseus) and another one using Tauri, with most of your code being available as one or more Rust libraries. - -The front-end logic can be written using any web application front-end framework, e.g. Svelte. - -You can also opt to go fully native by using plugins such as tauri-egui: - -### [Appendix IV. Rust in the background](#appendix-iv-rust-in-the-background) - -As with any (new) language, there's no point in replacing every existing technology written before, with a new implementation written in Rust. While at times there are benefits such as with [ripgrep](https://github.com/BurntSushi/ripgrep) instead of grep, this is not a generally useful strategy not a desired one. - -There's also a great modern alternative to Makefiles, as much as love as we have for it. It's named 'just' -and you can find it at , basically 'Make' with variables + more. - -- In [Appendix II.](#appendix-ii-webassembly-wasm) we already saw that Rust can be compiled to WASM, and as such you can build an entire WebApp in Rust. However instead of replacing your entire WebApp, it is also just as well possible that you only replace the components of your App where it makes sense, e.g. where you need to do a lot of computations; -- In [Appendix III.](#appendix-iii-native-apps) we learned about Tauri to build native apps with Rust, and also here noted that it can be done while at the same time building your core frontend logic in the frameworks you are used to; - -At times however you might be able to incorporate the benefits of Rust in your existing benefits without having to expose the language to anyone: - -- [FNM](https://github.com/Schniz/fnm) is a replacement for NVM. While the latter is more powerful the first is a lot faster, which speeds up terminal start up times by a lot, just to give one benefit; -- [Deno](https://deno.land/) can be used as a replacement for NodeJS, and can not only run javascript but also typescript (for which you would otherwise use something like ts-node). It is not a 1-to-1 replacement, and it will require some effort, but it is already today a faster and more secure alternative; -- [SWC](https://swc.rs/) is a speedy light alternative to babel, with the first outperforming the last with its eyes closed and 1 foot still in the bed; - -These give just a small taste of what Rust can mean for Web developers even if they do not know or use Rust themselves directly. - -In fact some thing most Rust users will be users that do not even know they are using Rust. This is not only True -for the Javacript world but for many others as well, such as Python for example. - -- [Pydantic](https://github.com/pydantic/pydantic) is a library for Data validation using Python type hints. -- [Ruff](https://github.com/astral-sh/ruff) is An extremely fast Python linter, written in Rust. - -Python web developers can also make use of Rust to write their Python web services, without having to know Rust: - -- Granian (): - - A Rust HTTP server for Python applications (written on top of Hyper); - - Supports ASGI/3, RSGI and WSGI interface applications; - - Example usage: run your FastAPI web service :) -- Robyn (): - - A High-Performance, Community-Driven, and Innovator Friendly Web Framework with a Rust runtime. - - In contrast to `Granian` this does mean you need to write your service using the Robyn way to do things, - so not possible to use an existing service built with FastAPI. - -And plenty more will follow surely. - -A language is a tool, but a tool is not to be applied to any problem. Rust has its advantages and use cases, it would be foolish not to use it where desirable. - -### [Appendix V. Python / Javascript Developers](#appendix-v-python--javascript-developers) - -In case you come from Python or Javascript you can alternatively replace the first four steps of this learning guide with a single book. [Rust Web Programming](https://www.packtpub.com/product/rust-web-programming-second-edition/9781803234694) (Packt Publishing) aims to get web developers (including Python developers) started with Rust and has a very pragmatic approach. - -Given how important Async is in our work environment it is still worth to go through section [(3) "Learn Async Rust"](#3-learn-async-rust) to make sure you do really grasp that very well. It is also where a lot of your Rust knowledge starts to come together, so if you get that you know you're on the right track. - -Should you after completing this book (even if partly) want to have some more hands on experience you can opt to never the less do section (4) as well and go through [the "Zero to Production in Rust" book](#4-study-using-the-zero-to-production-in-rust-book) - -However, in case you are confident you did get all the foundational concepts of Rust and want to just develop stuff already and get it "into your fingers" you might want to opt to after this (and before jumping onto section (5)) read ["Rust In Action"](https://www.manning.com/books/rust-in-action) first. It gives a lot of fun things to build. Alternatively you can check the "Learn More Rust: Extra" part of [section (2) Learn more Rust](#2-learn-more-rust), where we also go over many ideas for you to get more experience and help you solidify your Rust knowledge. - -The "Rust in Action" book can also be seen as yet another alternative all together, as it is also aimed at introducing Rust to people who never did any Systems programming, So you could also do it instead of the Rust Web Programming book. - -Do you ever want to develop something using both Rust and Python? - -- Check out the pyo3 project: -- You might also like the following resource in your learning journey of it: - -### [Appendix VI. More Material](#appendix-vi-more-material) - -Learning to master a language has a beginning but it doesn't have an ending. You'll want to continue to learn, teach others and keep up to date. In this appendix you'll find material to help you with all this and more. - -#### [Keep up to date](#keep-up-to-date) - -Official Blogs: - -- [The Rust Programming Language Blog](https://blog.rust-lang.org/) - - e.g. in October of 2022 GAT's (Generic Associated Types) were finally stabilised, after 6+ years of work: [Generic associated types to be stable in Rust 1.65 — Rust Blog](https://blog.rust-lang.org/2022/10/28/gats-stabilization.html) - - [The "Inside Rust" Blog](https://blog.rust-lang.org/inside-rust/index.html) - -Conferences: - -- RustConf#2022: - -Podcasts: - -- Rustacean Station is a pretty great podcast with very interesting guests and even more interesting knowledge to share. Listen to it, you won't regret: -- In order to learn Rust you can also listen to the New Rustacean podcast, which is a podcast about learning Rust: - - It no longer airs, but its content remains useful and available - -Actuality: - -- ["This week in Rust"](https://this-week-in-rust.org/) is a weekly newsletter helping you stay up to date with Rust from the lazy comfort of your Mailbox. Easy. They can also be read online in case you prefer a browser instead or do not want to subscribe for w/e reason. - - Blog articles from the community get shared here as well, some accessible to new comers to Rust, others a bit more advanced - - They also share VOD's of recent conferences, e.g. the issue in which they share the rust talks from [FOSDEM 2023: This Week in Rust 481 · This Week in Rust](https://this-week-in-rust.org/blog/2023/02/08/this-week-in-rust-481/) -- ["Rust Magazine"](https://rustmagazine.org/): an online magazine dedicated to Rust - -#### [Lists](#lists) - -community curated crate lists: - -- [Crate List - Blessed.rs](https://blessed.rs/crates) - -#### [Read](#read) - -Free Rust Resources that we haven't mentioned yet, but are great to read at one point or another: - -- The Rust Performance Book: -- Rust Fuzz Book (Fuzz Testing): -- Idiomatic solutions to common programming tasks: -- The little book of Rust books: [Unofficial Rust Books - The Little Book of Rust Books](https://lborb.github.io/book/unofficial.html) (which we also already linked in an earlier section) - -If you learn by doing and haven't gotten enough from the resources we linked already in "Learn more Rust", here are some more tips: - -- Implement a Redis client and server using Tokio, a very well documented and excellent guide on how to write Asynchronous code in Rust: - for learning purposes only -- If you want to improve your borrowing and reference skills, implementing a Linked List data structure might be for you: -- Or perhaps you want to write your own OS in Rust: - -A blog you might want to RSS subscribe to is Amos's his blog which is always fun to read, be it sometimes a bit heavy: - -A nice reference sheet if you need one can be found at: - -#### [Educational](#educational) - -- Crust of Rust video series by "Jon Gjengset", for those that want to see an experienced Rust Developer work through problems: [Crust of Rust](https://www.youtube.com/playlist?list=PLqbS7AVVErFiWDOAVrPt7aYmnuuOLYvOa) - - You can combine it while learning a bit about networking and implement TCP in Rust yourself: -- If you like to learn by watching you can find a Rust streaming list at -- Interesting youtube channel with a lot of great stuff to learn about Rust: -- If any of the basic (textual) learning resources from the actual learning journey didn't quite work for you, you might find a video course more useful. If so, here are two of them: - - [Ultimate Rust Crash Course](https://www.udemy.com/course/ultimate-rust-crash-course/) - - [Ultimate Rust 2: Intermediate Concepts](https://www.udemy.com/course/ultimate-rust-2/) -- If you need inspiration on things you can build with Rust to get the language in your fingers as well as learn how software that you use is implemented, you might want to check out: -- Learn Full Stack Rust Interactively: [Rust Insight! - an interactive book for practicing Rust on the laptop](https://rustinsight.com/) (early access) -- A big index of many more learning resources, named aptly "How to learn Modern Rust — A Guide to the adventurer": - - Do not take the list as-is and use mostly as inspiration. No need to really do all on that list, but if you need more learning resources, there is plenty of good content and inspiration in there! -- Black Hat Rust book: (could be nice for inspiration on some hands-on experience while becoming more familiar with Rust) -- If you want to test your Rust concept skills you might also enjoy taking [the Rust Quiz](https://dtolnay.github.io/rust-quiz/). The more answers you have wrong the better, as it means you'll learn new things from the explanation :) -- If you want to learn by doing by contributing to an existing Rust OSS project (including the Rust language and tooling) you can try to find a mentor to help you for free online in achieving this, by going to Awesome Rust Mentors: - -### [Appendix VII. Community Chat](#appendix-vii-community-chat) - -Learning from and working with a community is one of the many perks of Rust, which is rightfully known for its warm, inclusive and charming community. Always open and friendly to others. - -Here are some chat servers you can join to interact with this fantastic community. All of them are great places to meet other Rust developers, find help, share news or a project and also to give back to the community yourself: - -- Discord chat server for the Tokio ecosystem and its community: ; -- Discord chat server for the Rust community in general (has a great channel for beginners to find help, and in a very fast manner): ; -- zulip chat server for Rust, great for core work and advanced purposes: . - -There are others of course but these are the ones which are both active, inclusive, friendly and known to the authors of this guide as being a great place to be and be part of. - -### [Appendix VIII. Debugging Rust](#appendix-viii-debugging-rust) - -Debugging Rust code can be seen on three different levels: - -1. Write Rustic code, making full use of the language and its expressive type system; -2. Have good logging and metrics in place for your production infrastructure; -3. Know your way around a debugger. - -Underappreciated is point (1). Ensuring that impossible state and behavior is in fact impossible -at compile team and thus guaranteed by the compiler is a big class of errors that you simply -can no longer make and thus never have to debug. Using maker types and enums can help you a lot here. - -Rust is also a typed language so ensuring to use the proper types and use them consistently, -will also help avoid a big category of bugs. Similarly, you probably do not really ever want to -unwrap/expect any of your library code and only do so at the very top level, as to avoid nasty edge cases at runtime. - -That being said, sometimes things do go wrong. And debugging in production is not always fun. -In fact, trying to reproduce rare scenarios locally is even less fun. For that you really -want to ensure you know the right tools and crates to help you deal with point (2). - -- If you use [Tokio](https://tokio.rs) then the [`tracing` crate](https://tracing.rs/tracing/) and its mini ecosystem will be your friend, to help you define logs, metrics and more. - - The more data you have for your production infrastructure the easier it should be to spot potential issues that you didn't foresee but that you do clearly see in your logs and/or metrics; - - If you really want to dive deep and also learn about its macros, a blog article like might help you get into that; - - A blog article like might help you get started with Tracing in Rust, - and introduce you to "Open Telemetry" in general. -- If you do not use _Tokio_, then a crate like [log](https://crates.io/crates/log) is your best bet, and it will ensure that no matter what application makes use of your crate, will be able to consume your logs the way they want :) - -Finally when shit really hits the fan, and you do not see what's wrong from metrics and logs (alone), you might need to grab a debugger. The book might be able to give you a good starting point. Articles such as might help you get started on debugging in case you are using VSCode for Rust, which is what plenty of people seem to use these days. There's also a Gist about it for VSCode at . - -### [Appendix IX. Shipping Rust](#appendix-ix-shipping-rust) - -Shipping Rust does not have to be different from shipping code in other languages. -So all the knowledge you have or will learn about the Cloud, Docker, Bare Metal, Vms, -Lambda functions, WASM workers, containers, and whatever else also can be applied here. - -If you however find cloud platforms like AWS or GCloud a bit dounting (or have choice stress), -and find deploying to your own VPS or VM a bit too barebones, you might find some of the following -solutions to be helpful, specifically with the goal of shipping rust code such as a web service: - -- : allows you to ship rust code fairly painlessly by using docker containers; -- has a pretty unique approach by letting you deploy your Rust code directly, without containers, - and by adding your stack dependencies (e.g. database needs) as macros to your Rust `main.rs` code; -- Using you can ship your Rust code to Cloudflare's workers platform; -- is another similar cloud platform that also allows you to ship Rust (WASM) workers; - -If you want to ship on a more standard cloud platform such as _AWS_ -you can learn to do so as part of practicing Rust using "[4. Study using the "Zero to Production in Rust" book](#4-study-using-the-zero-to-production-in-rust-book)". - -Finally, in the spirit of KISS, nothing wrong with deploying like this: . +This is the source code of an [mdBook](https://rust-lang.github.io/mdBook/index.html) +served at . diff --git a/_config.yml b/_config.yml deleted file mode 100644 index af21f35..0000000 --- a/_config.yml +++ /dev/null @@ -1,9 +0,0 @@ -title: Learn Rust 101 -description: A guide to aid you in your journey of becoming a Rustacean (Rust developer). - -exclude: - - demo/ -include: - - ./README.md - -theme: minima \ No newline at end of file diff --git a/book.toml b/book.toml new file mode 100644 index 0000000..edc24d4 --- /dev/null +++ b/book.toml @@ -0,0 +1,11 @@ +[book] +authors = ["Glen Henri J. De Cauwsemaecker "] +language = "en" +multilingual = false +src = "src" +title = "Rust 101" + +[output.html] +git-repository-url = "https://github.com/plabayo/learn-rust-101" +git-repository-icon = "fa-github" +cname = "rust-lang.guide" diff --git a/favicon.ico b/favicon.ico deleted file mode 100644 index b9f39454f27d874204d5fc100358fa4e87961966..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 15406 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 C+CS?6 diff --git a/src/SUMMARY.md b/src/SUMMARY.md new file mode 100644 index 0000000..c014e24 --- /dev/null +++ b/src/SUMMARY.md @@ -0,0 +1,39 @@ +# Summary + +# Introduction + +- [Introduction](./intro/README.md) +- [Prologue](./intro/prologue.md) +- [Learning Rust](./intro/learning-rust.md) +- [About](./intro/about.md) + +# Learning Guide + +- [Learn Rust](./guide/learn-rust/README.md) + - [Learn Rust: Questions](./guide/learn-rust/questions.md) +- [Learn More Rust](./guide/learn-more-rust/README.md) + - [Learn More Rust: Questions](./guide/learn-more-rust/questions.md) + - [Learn More Rust: Extra](./guide/learn-more-rust/extra.md) +- [Learn Async Rust](./guide/learn-async-rust/README.md) + - [Learn Async Rust: Questions](./guide/learn-async-rust/questions.md) + - [Rust Atomics and Locs](./guide/learn-async-rust/rust-atomics-and-locs.md) + - [Threading](./guide/learn-async-rust/threading.md) + - [Tower](./guide/learn-async-rust/tower.md) +- [A note about the remaining steps of this guide](./guide/a-note-about-the-remaining-part-of-this-guide.md) +- [Study using the "Zero to Production in Rust" book](./guide/study-using-the-zero-to-production-in-rust-book.md) +- [Contribute for the first time to an existing project](./guide/contribute-for-the-first-time-to-an-existing-project.md) +- [Study using the "Rust for Rustaceans: Idiomatic Programming for Experienced Developers" book](./guide/study-using-the-rust-for-rustaceans-idiomatic-programming-for-experienced-developers-book.md) +- [Contribute an advanced feature to an existing project or start a project from scratch](./guide/contribute-an-advanced-feature-to-an-existing-project-or-start-a-project-from-scratch.md) +- [Next Steps](./guide/next-steps.md) + +# Appendix + +- [Appendix I. Install Rust](./appendix/appendix-i-install-rust.md) +- [Appendix II. WebAssembly (WASM)](./appendix/appendix-ii-webassembly-wasm.md) +- [Appendix III. Native Apps](./appendix/appendix-iii-native-apps.md) +- [Appendix IV. Rust in the background](./appendix/appendix-iv-rust-in-the-background.md) +- [Appendix V. Python / Javascript developers](./appendix/appendix-v-python--javascript-developers.md) +- [Appendix VI. More Material](./appendix/appendix-vi-more-material.md) +- [Appendix VII. Community Chat](./appendix/appendix-vii-community-chat.md) +- [Appendix VIII. Debugging Rust](./appendix/appendix-viii-debugging-rust.md) +- [Appendix IX. Shipping Rust](./appendix/appendix-ix-shipping-rust.md) \ No newline at end of file diff --git a/src/appendix/appendix-i-install-rust.md b/src/appendix/appendix-i-install-rust.md new file mode 100644 index 0000000..7b638d6 --- /dev/null +++ b/src/appendix/appendix-i-install-rust.md @@ -0,0 +1,43 @@ +### Appendix I. Install Rust + +In order to start using Rust you have to install and configure its tooling on your machinery. + +- The Rust compiler (`rustc`), standard library and tooling (e.g. `cargo`) are all managed using `rustup`. + - You can learn how to get started by going to: + - Once you finished with this you'll have Rust ready on your machine out of the box. Each time there is a new version of Rust you can update it, simply by running `rustup update` + +With this installed you should now be able to run the following command: + +``` +cargo version +``` + +Which will output something like: + +``` +cargo 1.67.1 (8ecd4f20a 2023-01-10) +``` + +You can learn to create, compile and run your first Rust program at "[First Steps with Cargo - The Cargo Book](https://www.rust-lang.org/learn/get-started)". + +> If you are looking for a fun bigger project to help you learn Rust, +> you might find it fun to buy your own cargo-like tool: + +#### [Linting and styling](#linting-and-styling) + +- Install `clippy` using `rustup component add clippy` + - This way you can use the command `cargo clippy` to help guarantee the quality of your code +- Install `rustfmt` using `rustup component add rustfmt` + - This way you can use `cargo fmt` to format your code (best to also configure this in your IDE to be done each time you save the file) + +No custom linting configurations or agreements are required beyond this. If you use these two tools, you're golden. These tools also work nicely with any IDE you might use. Within your CI environment these same tools will be used to check that your code adheres to its standards. + +Clippy can be seen as a testing ground to see what lints are useful and which ones aren't. The ones that are often get shipped into the official compiler a while later. Some lints are also ignored by default for whatever reasons. You can find all lints (AFAIK) at , should you want to enable even more lints. + +Some useful reasons why you might stil want to enable custom lints are: + +- to enable nightly features; +- to prevent the usage (in your own codebase) of `unsafe` code. + +For reference you can check the mono repository's `lib.rs` files, +where I enable such opt-in lints myself, which itself is based on the original `tower-rs` code. diff --git a/src/appendix/appendix-ii-webassembly-wasm.md b/src/appendix/appendix-ii-webassembly-wasm.md new file mode 100644 index 0000000..950c93e --- /dev/null +++ b/src/appendix/appendix-ii-webassembly-wasm.md @@ -0,0 +1,34 @@ +### Appendix II. WebAssembly (WASM) + +> ⓘ WebAssembly (abbreviated Wasm) is a binary instruction format for a stack-based virtual machine. Wasm is designed as a portable compilation target for programming languages, enabling deployment on the web for client and server applications. +> +> 🔗 + +WebAssembly on itself is completely isolated from Rust, but it must be said that among the WASM community, the Rust part is probably the biggest and most active one. Compiling Rust to WASM is a true pleasure and allows for browser client code to be written in Rust, be it a small library to be used from JS or an entire web client. WASM projects can also be used to quickly deploy web services (in the backend). These are similar to lambda functions but are even faster to use and in a way also safer. + +#### WASM Learning Resources + +- RustWasm book: [Introduction - Rust and WebAssembly](https://rustwasm.github.io/docs/book/) + - This is the officially recommended book to get you started, as can be seen at +- [Programming WASM with Rust: Programming WebAssembly with Rust](https://www.oreilly.com/library/view/programming-webassembly-with/9781680506846/) +- Build a web app with Rust (using Yew framework): +- Rust to WebAssembly the hard way: [Rust to WebAssembly the hard way — surma.dev](https://surma.dev/things/rust-to-webassembly/index.html) + +Frameworks that you might want to check if you want to make a front-end (web) app using Rust: + +- Make desktop apps using web tech (think Electron, but better): [GitHub - tauri-apps/tauri: Build smaller, faster, and more secure desktop applications with a web frontend](https://github.com/tauri-apps/tauri); +- Very popular and fast front-end framework for Rust: [GitHub - yewstack/yew: Rust / Wasm framework for building client web apps](https://github.com/yewstack/yew) +- Another front-end framework: [GitHub - chinedufn/percy: Build frontend browser apps with Rust + WebAssembly](https://github.com/chinedufn/percy). Supports server side rendering. +- Yet another front-end framework: [GitHub - sycamore-rs/sycamore](https://github.com/sycamore-rs/sycamore): A library for creating reactive web apps in Rust and WebAssembly +- If you are looking for a complete framework you might want to give a chance, it builds on top of Sycamore; +- Exciting new and very fast front-end framework: [GitHub - leptos-rs/leptos: Build fast web applications with Rust](https://github.com/leptos-rs/leptos). +- Another front-end framework (or perhaps rather a GUI framework) that you might want to know about is Dioxus () which is made not only for web-apps, but also with CLI, mobile and Desktop in mind. +- Also a pretty nice front-end framework: [GitHub - framesurge/perseus: A state-driven web development framework for Rust with full support for server-side rendering and static generation](https://github.com/framesurge/perseus). + +Run WASM Backend Services in the cloud: + +- Cloudflare workers: [Cloudflare Workers®](https://workers.cloudflare.com/) +- Fermyon Cloud (free for now): [Deploy & manage cloud native WebAssembly apps](https://www.fermyon.com/cloud) +- Wasmer's goal is to run any code on any client (think Java's dream, but for real): + +As you can see, WASM on the backend is a thing. Whether it's more then just hype is something the future will tell, but either way a lot of interesting stuff is happening and there's big money behind it somehow. So you might as well jump in the car, especially if you missed the Docker train somehow. Happens. diff --git a/src/appendix/appendix-iii-native-apps.md b/src/appendix/appendix-iii-native-apps.md new file mode 100644 index 0000000..5a8c116 --- /dev/null +++ b/src/appendix/appendix-iii-native-apps.md @@ -0,0 +1,24 @@ +### Appendix III. Native Apps + +Native apps are applications written for a specific platform. While that could be any platform, it usually refers to anything that is not the "web" and even more so, these days, it pretty much always refers to Desktop, Mobile or the combination of. Cross platform apps mean that multiple platforms are supported, which could be any set of web or non-web platforms. + +> If you ever need to interact with other native languages: +> +> - For C you probably want to just use bindgen; +> - For C++ you can make use of (cxx); + +#### Tauri + +**Tauri** is the toolset you want to check out if you want to build native apps with a Gui in Rust. You can find all information about it on their official website: + +> ⓘ Build an optimized, secure, and frontend-independent application for multi-platform deployment. + +Tauri applications can be compared to Electron, but it uses a very different approach. Multiple rendering engines are supported, with web view like rendering engines being the default. But this is still different then shipping a Node runtime and Chromium with each one of your apps. Meaning your desktop applications can be as small as a couple of megabytes, compared to the usually bloated 150MB apps. And once running, they will also be a lot less resource hungry compared to your topical Electron app. + +Mobile applications are not yet officially supported, but they will soon get support as well, as the underlying technology for it is already more or less ready. + +In case you want to write applications that work on both the web and a non-web platform you can achieve this by splitting your business logic from your minimal front-end logic, such that you can write one front-end in any of the available front-end approaches (e.g. leptos or perseus) and another one using Tauri, with most of your code being available as one or more Rust libraries. + +The front-end logic can be written using any web application front-end framework, e.g. Svelte. + +You can also opt to go fully native by using plugins such as tauri-egui: diff --git a/src/appendix/appendix-iv-rust-in-the-background.md b/src/appendix/appendix-iv-rust-in-the-background.md new file mode 100644 index 0000000..4af2ea1 --- /dev/null +++ b/src/appendix/appendix-iv-rust-in-the-background.md @@ -0,0 +1,38 @@ +### Appendix IV. Rust in the background + +As with any (new) language, there's no point in replacing every existing technology written before, with a new implementation written in Rust. While at times there are benefits such as with [ripgrep](https://github.com/BurntSushi/ripgrep) instead of grep, this is not a generally useful strategy not a desired one. + +There's also a great modern alternative to Makefiles, as much as love as we have for it. It's named 'just' +and you can find it at , basically 'Make' with variables + more. + +- In [Appendix II.](/appendix/appendix-ii-webassembly-wasm.md) we already saw that Rust can be compiled to WASM, and as such you can build an entire WebApp in Rust. However instead of replacing your entire WebApp, it is also just as well possible that you only replace the components of your App where it makes sense, e.g. where you need to do a lot of computations; +- In [Appendix III.](/appendix/appendix-iii-native-apps.md) we learned about Tauri to build native apps with Rust, and also here noted that it can be done while at the same time building your core frontend logic in the frameworks you are used to; + +At times however you might be able to incorporate the benefits of Rust in your existing benefits without having to expose the language to anyone: + +- [FNM](https://github.com/Schniz/fnm) is a replacement for NVM. While the latter is more powerful the first is a lot faster, which speeds up terminal start up times by a lot, just to give one benefit; +- [Deno](https://deno.land/) can be used as a replacement for NodeJS, and can not only run javascript but also typescript (for which you would otherwise use something like ts-node). It is not a 1-to-1 replacement, and it will require some effort, but it is already today a faster and more secure alternative; +- [SWC](https://swc.rs/) is a speedy light alternative to babel, with the first outperforming the last with its eyes closed and 1 foot still in the bed; + +These give just a small taste of what Rust can mean for Web developers even if they do not know or use Rust themselves directly. + +In fact some thing most Rust users will be users that do not even know they are using Rust. This is not only True +for the Javacript world but for many others as well, such as Python for example. + +- [Pydantic](https://github.com/pydantic/pydantic) is a library for Data validation using Python type hints. +- [Ruff](https://github.com/astral-sh/ruff) is An extremely fast Python linter, written in Rust. + +Python web developers can also make use of Rust to write their Python web services, without having to know Rust: + +- Granian (): + - A Rust HTTP server for Python applications (written on top of Hyper); + - Supports ASGI/3, RSGI and WSGI interface applications; + - Example usage: run your FastAPI web service :) +- Robyn (): + - A High-Performance, Community-Driven, and Innovator Friendly Web Framework with a Rust runtime. + - In contrast to `Granian` this does mean you need to write your service using the Robyn way to do things, + so not possible to use an existing service built with FastAPI. + +And plenty more will follow surely. + +A language is a tool, but a tool is not to be applied to any problem. Rust has its advantages and use cases, it would be foolish not to use it where desirable. diff --git a/src/appendix/appendix-ix-shipping-rust.md b/src/appendix/appendix-ix-shipping-rust.md new file mode 100644 index 0000000..eefb6b3 --- /dev/null +++ b/src/appendix/appendix-ix-shipping-rust.md @@ -0,0 +1,20 @@ +### Appendix IX. Shipping Rust + +Shipping Rust does not have to be different from shipping code in other languages. +So all the knowledge you have or will learn about the Cloud, Docker, Bare Metal, Vms, +Lambda functions, WASM workers, containers, and whatever else also can be applied here. + +If you however find cloud platforms like AWS or GCloud a bit dounting (or have choice stress), +and find deploying to your own VPS or VM a bit too barebones, you might find some of the following +solutions to be helpful, specifically with the goal of shipping rust code such as a web service: + +- : allows you to ship rust code fairly painlessly by using docker containers; +- has a pretty unique approach by letting you deploy your Rust code directly, without containers, + and by adding your stack dependencies (e.g. database needs) as macros to your Rust `main.rs` code; +- Using you can ship your Rust code to Cloudflare's workers platform; +- is another similar cloud platform that also allows you to ship Rust (WASM) workers; + +If you want to ship on a more standard cloud platform such as _AWS_ +you can learn to do so as part of practicing Rust using "[4. Study using the "Zero to Production in Rust" book](#4-study-using-the-zero-to-production-in-rust-book)". + +Finally, in the spirit of KISS, nothing wrong with deploying like this: . diff --git a/src/appendix/appendix-v-python--javascript-developers.md b/src/appendix/appendix-v-python--javascript-developers.md new file mode 100644 index 0000000..cffae32 --- /dev/null +++ b/src/appendix/appendix-v-python--javascript-developers.md @@ -0,0 +1,16 @@ +### Appendix V. Python / Javascript Developers + +In case you come from Python or Javascript you can alternatively replace the first four steps of this learning guide with a single book. [Rust Web Programming](https://www.packtpub.com/product/rust-web-programming-second-edition/9781803234694) (Packt Publishing) aims to get web developers (including Python developers) started with Rust and has a very pragmatic approach. + +Given how important Async is in our work environment it is still worth to go through section [(3) "Learn Async Rust"](/guide/learn-async-rust.md) to make sure you do really grasp that very well. It is also where a lot of your Rust knowledge starts to come together, so if you get that you know you're on the right track. + +Should you after completing this book (even if partly) want to have some more hands on experience you can opt to never the less do section (4) as well and go through [the "Zero to Production in Rust" book](/guide/study-using-the-zero-to-production-in-rust-book.md) + +However, in case you are confident you did get all the foundational concepts of Rust and want to just develop stuff already and get it "into your fingers" you might want to opt to after this (and before jumping onto section (5)) read ["Rust In Action"](https://www.manning.com/books/rust-in-action) first. It gives a lot of fun things to build. Alternatively you can check the "Learn More Rust: Extra" part of [section (2) Learn more Rust](/guide/learn-more-rust.md), where we also go over many ideas for you to get more experience and help you solidify your Rust knowledge. + +The "Rust in Action" book can also be seen as yet another alternative all together, as it is also aimed at introducing Rust to people who never did any Systems programming, So you could also do it instead of the Rust Web Programming book. + +Do you ever want to develop something using both Rust and Python? + +- Check out the pyo3 project: +- You might also like the following resource in your learning journey of it: diff --git a/src/appendix/appendix-vi-more-material.md b/src/appendix/appendix-vi-more-material.md new file mode 100644 index 0000000..bf7cdab --- /dev/null +++ b/src/appendix/appendix-vi-more-material.md @@ -0,0 +1,70 @@ +### Appendix VI. More Material + +Learning to master a language has a beginning but it doesn't have an ending. You'll want to continue to learn, teach others and keep up to date. In this appendix you'll find material to help you with all this and more. + +#### Keep up to date + +Official Blogs: + +- [The Rust Programming Language Blog](https://blog.rust-lang.org/) + - e.g. in October of 2022 GAT's (Generic Associated Types) were finally stabilised, after 6+ years of work: [Generic associated types to be stable in Rust 1.65 — Rust Blog](https://blog.rust-lang.org/2022/10/28/gats-stabilization.html) + - [The "Inside Rust" Blog](https://blog.rust-lang.org/inside-rust/index.html) + +Conferences: + +- RustConf#2022: + +Podcasts: + +- Rustacean Station is a pretty great podcast with very interesting guests and even more interesting knowledge to share. Listen to it, you won't regret: +- In order to learn Rust you can also listen to the New Rustacean podcast, which is a podcast about learning Rust: + - It no longer airs, but its content remains useful and available + +Actuality: + +- ["This week in Rust"](https://this-week-in-rust.org/) is a weekly newsletter helping you stay up to date with Rust from the lazy comfort of your Mailbox. Easy. They can also be read online in case you prefer a browser instead or do not want to subscribe for w/e reason. + - Blog articles from the community get shared here as well, some accessible to new comers to Rust, others a bit more advanced + - They also share VOD's of recent conferences, e.g. the issue in which they share the rust talks from [FOSDEM 2023: This Week in Rust 481 · This Week in Rust](https://this-week-in-rust.org/blog/2023/02/08/this-week-in-rust-481/) +- ["Rust Magazine"](https://rustmagazine.org/): an online magazine dedicated to Rust + +#### Lists + +community curated crate lists: + +- [Crate List - Blessed.rs](https://blessed.rs/crates) + +#### Read + +Free Rust Resources that we haven't mentioned yet, but are great to read at one point or another: + +- The Rust Performance Book: +- Rust Fuzz Book (Fuzz Testing): +- Idiomatic solutions to common programming tasks: +- The little book of Rust books: [Unofficial Rust Books - The Little Book of Rust Books](https://lborb.github.io/book/unofficial.html) (which we also already linked in an earlier section) + +If you learn by doing and haven't gotten enough from the resources we linked already in "Learn more Rust", here are some more tips: + +- Implement a Redis client and server using Tokio, a very well documented and excellent guide on how to write Asynchronous code in Rust: - for learning purposes only +- If you want to improve your borrowing and reference skills, implementing a Linked List data structure might be for you: +- Or perhaps you want to write your own OS in Rust: + +A blog you might want to RSS subscribe to is Amos's his blog which is always fun to read, be it sometimes a bit heavy: + +A nice reference sheet if you need one can be found at: + +#### Educational + +- Crust of Rust video series by "Jon Gjengset", for those that want to see an experienced Rust Developer work through problems: [Crust of Rust](https://www.youtube.com/playlist?list=PLqbS7AVVErFiWDOAVrPt7aYmnuuOLYvOa) + - You can combine it while learning a bit about networking and implement TCP in Rust yourself: +- If you like to learn by watching you can find a Rust streaming list at +- Interesting youtube channel with a lot of great stuff to learn about Rust: +- If any of the basic (textual) learning resources from the actual learning journey didn't quite work for you, you might find a video course more useful. If so, here are two of them: + - [Ultimate Rust Crash Course](https://www.udemy.com/course/ultimate-rust-crash-course/) + - [Ultimate Rust 2: Intermediate Concepts](https://www.udemy.com/course/ultimate-rust-2/) +- If you need inspiration on things you can build with Rust to get the language in your fingers as well as learn how software that you use is implemented, you might want to check out: +- Learn Full Stack Rust Interactively: [Rust Insight! - an interactive book for practicing Rust on the laptop](https://rustinsight.com/) (early access) +- A big index of many more learning resources, named aptly "How to learn Modern Rust — A Guide to the adventurer": + - Do not take the list as-is and use mostly as inspiration. No need to really do all on that list, but if you need more learning resources, there is plenty of good content and inspiration in there! +- Black Hat Rust book: (could be nice for inspiration on some hands-on experience while becoming more familiar with Rust) +- If you want to test your Rust concept skills you might also enjoy taking [the Rust Quiz](https://dtolnay.github.io/rust-quiz/). The more answers you have wrong the better, as it means you'll learn new things from the explanation :) +- If you want to learn by doing by contributing to an existing Rust OSS project (including the Rust language and tooling) you can try to find a mentor to help you for free online in achieving this, by going to Awesome Rust Mentors: diff --git a/src/appendix/appendix-vii-community-chat.md b/src/appendix/appendix-vii-community-chat.md new file mode 100644 index 0000000..e834c2b --- /dev/null +++ b/src/appendix/appendix-vii-community-chat.md @@ -0,0 +1,11 @@ +### Appendix VII. Community Chat + +Learning from and working with a community is one of the many perks of Rust, which is rightfully known for its warm, inclusive and charming community. Always open and friendly to others. + +Here are some chat servers you can join to interact with this fantastic community. All of them are great places to meet other Rust developers, find help, share news or a project and also to give back to the community yourself: + +- Discord chat server for the Tokio ecosystem and its community: ; +- Discord chat server for the Rust community in general (has a great channel for beginners to find help, and in a very fast manner): ; +- zulip chat server for Rust, great for core work and advanced purposes: . + +There are others of course but these are the ones which are both active, inclusive, friendly and known to the authors of this guide as being a great place to be and be part of. diff --git a/src/appendix/appendix-viii-debugging-rust.md b/src/appendix/appendix-viii-debugging-rust.md new file mode 100644 index 0000000..ea8fa1a --- /dev/null +++ b/src/appendix/appendix-viii-debugging-rust.md @@ -0,0 +1,28 @@ +### Appendix VIII. Debugging Rust + +Debugging Rust code can be seen on three different levels: + +1. Write Rustic code, making full use of the language and its expressive type system; +2. Have good logging and metrics in place for your production infrastructure; +3. Know your way around a debugger. + +Underappreciated is point (1). Ensuring that impossible state and behavior is in fact impossible +at compile team and thus guaranteed by the compiler is a big class of errors that you simply +can no longer make and thus never have to debug. Using maker types and enums can help you a lot here. + +Rust is also a typed language so ensuring to use the proper types and use them consistently, +will also help avoid a big category of bugs. Similarly, you probably do not really ever want to +unwrap/expect any of your library code and only do so at the very top level, as to avoid nasty edge cases at runtime. + +That being said, sometimes things do go wrong. And debugging in production is not always fun. +In fact, trying to reproduce rare scenarios locally is even less fun. For that you really +want to ensure you know the right tools and crates to help you deal with point (2). + +- If you use [Tokio](https://tokio.rs) then the [`tracing` crate](https://tracing.rs/tracing/) and its mini ecosystem will be your friend, to help you define logs, metrics and more. + - The more data you have for your production infrastructure the easier it should be to spot potential issues that you didn't foresee but that you do clearly see in your logs and/or metrics; + - If you really want to dive deep and also learn about its macros, a blog article like might help you get into that; + - A blog article like might help you get started with Tracing in Rust, + and introduce you to "Open Telemetry" in general. +- If you do not use _Tokio_, then a crate like [log](https://crates.io/crates/log) is your best bet, and it will ensure that no matter what application makes use of your crate, will be able to consume your logs the way they want :) + +Finally when shit really hits the fan, and you do not see what's wrong from metrics and logs (alone), you might need to grab a debugger. The book might be able to give you a good starting point. Articles such as might help you get started on debugging in case you are using VSCode for Rust, which is what plenty of people seem to use these days. There's also a Gist about it for VSCode at . diff --git a/src/guide/a-note-about-the-remaining-part-of-this-guide.md b/src/guide/a-note-about-the-remaining-part-of-this-guide.md new file mode 100644 index 0000000..7a66421 --- /dev/null +++ b/src/guide/a-note-about-the-remaining-part-of-this-guide.md @@ -0,0 +1,5 @@ +## A Note About the remaining part of this guide + +The next sections are all optional and are not required to really be productive in Rust. Some of it are alternative resources or extra content to learn from. Others is just miscellaneous content that is not really required to be productive in Rust, but might be interesting to you. + +This guide is either way not meant to be read in a single session or series. Take it as yours and just use it as part of your learning journey. Take your time as learning Rust isn't easy, but it is a very rewarding one once you did climb the mountain and are dancing with a double rainbow in the background. diff --git a/src/guide/contribute-an-advanced-feature-to-an-existing-project-or-start-a-project-from-scratch.md b/src/guide/contribute-an-advanced-feature-to-an-existing-project-or-start-a-project-from-scratch.md new file mode 100644 index 0000000..ebb2dec --- /dev/null +++ b/src/guide/contribute-an-advanced-feature-to-an-existing-project-or-start-a-project-from-scratch.md @@ -0,0 +1,13 @@ +## Contribute an advanced feature to an existing project or start a project from scratch + +Start a project for yourself, your dog, your organization or mother. This might be a microservice, library or small tool. Everything is possible. + +Another option is to contribute to an open source project that you like or may want to strongly depend upon in the future. + +See [section (5) about your first contribution](/guide/contribute-for-the-first-time-to-an-existing-project.md) for some inspiration on where to start. + +> As it is assumed that at this point you are doing intermediate level work in Rust +> it will be the case that sooner or later you'll need to debug. Or perhaps you are about +> to deploy your own small project to production. In any case, you'll need to know how to +> debug Rust applications. You can read all about this and tracing in +> [Appendix VIII. Debugging Rust](/appendix/appendix-viii-debugging-rust.md). \ No newline at end of file diff --git a/src/guide/contribute-for-the-first-time-to-an-existing-project.md b/src/guide/contribute-for-the-first-time-to-an-existing-project.md new file mode 100644 index 0000000..5d4633b --- /dev/null +++ b/src/guide/contribute-for-the-first-time-to-an-existing-project.md @@ -0,0 +1,11 @@ +## Contribute for the first time to an existing project + +Contribute to an open source project that you like or may want to strongly depend upon in the future. + +Many projects have a `good first issue` label, which is a good place to start. You can also look for issues that are labeled `help wanted` or `easy`. + +There's also the Rust Mentorship program, which pairs up new contributors with experienced Rustaceans. You can find more information about it at: + +In [The weekly Rust Newsletter](https://this-week-in-rust.org/) you can find a list of projects that are looking for contributors. + +If you are a seasoned programmer already you might also opt to already start making your own new project or porting a scoped project from another language to Rust. diff --git a/src/guide/learn-async-rust/README.md b/src/guide/learn-async-rust/README.md new file mode 100644 index 0000000..5819b76 --- /dev/null +++ b/src/guide/learn-async-rust/README.md @@ -0,0 +1,48 @@ +## Learn Async Rust + +There is no standard / official Asynchronous runtime. This in contrast to actual CPU threads [which you can create from within the std library](https://doc.rust-lang.org/std/thread/fn.spawn.html). + +The most popular and recommended by many Async Runtime is [the Tokio runtime](https://tokio.rs/). Which brings us to the next chapter: + +- To start with your Async Learning Journey you might want to start with: [Getting Started - Asynchronous Programming in Rust](https://rust-lang.github.io/async-book/); +- Afterwards you can finally start going through the Tokio [learning journey Tutorial](https://tokio.rs/tokio/tutorial) + +Please also join the Tokio Discord community as part of your async Journey, a place where you can ask any questions you want as well: . This server also has individual channels for the different projects in the Tokio ecosystem such as Hyper, Axum, Tower and more. The maintainers of the different projects are also very active in the server and are happy to help you out, but of course please do not take this for granted. Be respectful and if possible contribute back to the community as well. + +The following article is a very nice introduction to Rust async: . + +Extra Learning Resources: + +- ; +- : great article to make you think about why Async rust might feel so wrong. + - A big problem is that most people use Tokio in multithreade mode which puts extra restrictions (Send + 'Static), + which makes Async feel extra difficult. + - It's also important that people, next to having experience with Tokio and getting a good understanding of Async rust and all it entails, + to also discover, play and use other async runtimes. + - is a great alternative Async runtime that you might want to try out; +- Learn more about Async Rust and what the current situation is/was in 2023: + +As an extra, and perhaps slighty sidetracked, you may also want to read and develop alongside the following articles: + +- [The HTTP crash course nobody asked for](https://fasterthanli.me/articles/the-http-crash-course-nobody-asked-for) +- [Understanding Rust futures by going way too deep](https://fasterthanli.me/articles/understanding-rust-futures-by-going-way-too-deep) +- To get to get a deeper understanding about the concepts of pinning and the like you might find the following articles helpful: + - [Put a pin on That](https://archive.is/pHfCn) + - This article refers also to [Pin, Unpin and why Rust neeeds them](https://archive.is/LH91o) + - as well as [Pin and Suffering](https://archive.is/32RlT) + - All of the above are great articles to get you quickly up to speeds with the concept, and helpful as a repeater or because you hvae no desire or time to read some of the books that talk about this topic and that I recommend in other parts of this guide; + +In order to help you understand how Async code works (e.g. what about the Async keyword and How do futures really work. And how do you define traits with futures. And How do you implement them), you might want to read through the articles linked in the [Tower](#tower) section, as seeing how to implement your own _Tower_ middleware might answer many of such questions. Gaining a deeper theoretical but still pragmatic enough understanding behind it is probably better done by reading some of the books listed in this guide. + +> ⓘ Note: Tokio also provides support to [the new Linux kernel io_uring concept](https://unixism.net/loti/), a new powerful way to allow async programming on Linux. Support for it can be found at: [GitHub - tokio-rs/tokio-uring: An io_uring backed runtime for Rust](https://github.com/tokio-rs/tokio-uring) +> +> Synacktiv made an IO network scanner using io_uring as can be seen at [GitHub - synacktiv/io_uring_scanner: io_uring based network scanner written in Rust](https://github.com/synacktiv/io_uring_scanner), using tokio's low level userspace bindings to io_uring. + +To get a better idea about how futures work and the executor which polls them, you might want to read this article: . + +The blog series as found at can be another great reference to help you understand the entire `async/await` part of Rust: + +- [part 1: why doesn’t my task do anything if I don’t await it?](https://hegdenu.net/posts/understanding-async-await-1/) +- [part 2: how does a pending future get woken?](https://hegdenu.net/posts/understanding-async-await-2/) +- [part 3: why shouldn’t I hold a mutex guard across an await point?](https://hegdenu.net/posts/understanding-async-await-3/) +- [part 4: why would I ever want to write a future manually?](https://hegdenu.net/posts/understanding-async-await-4/#why-would-i-ever-want-to-write-a-future-manually) diff --git a/src/guide/learn-async-rust/questions.md b/src/guide/learn-async-rust/questions.md new file mode 100644 index 0000000..a3b082b --- /dev/null +++ b/src/guide/learn-async-rust/questions.md @@ -0,0 +1,17 @@ +## Learn Async Rust: Questions + +Questions you should be able to answer at the end of this step: + +1. How does Async programming work in Rust, if you didn't understand this already? +2. What types of concurrent programming does Rust support? How many are there in general? +3. What are Futures and how do they work? What function they have? How do they affect you? +4. What is Send and Sync? What is it used for? How does it affect you? +5. What are good use cases of Async code? What kind of tasks aren't a good fit for this? +6. What are Async Executors? What are Async Runtimes? +7. What is Tokio? How do you use it? What does it give you? +8. What are some other libraries in the Tokio ecosystem? +9. What can you build with Tokio? +10. Why would you use Tokio? +11. How do you achieve Async Rust programming with only standard library (stdlib) code? +12. Why does Rust not bundle an Async runtime? +13. What is parallel programming? How do you do it in Rust? How does it relate to Async programming? diff --git a/src/guide/learn-async-rust/rust-atomics-and-locs.md b/src/guide/learn-async-rust/rust-atomics-and-locs.md new file mode 100644 index 0000000..75c6e08 --- /dev/null +++ b/src/guide/learn-async-rust/rust-atomics-and-locs.md @@ -0,0 +1,36 @@ +### Rust Atomics and Locks + +Understanding concurrency, the primitives used to do so safely and how it all works "under the hood" (e.g. the OS level) is not critical but it will help you big time the rest of your Async professional career. + +The book "[Rust Atomics and Locks](https://marabos.nl/atomics/)" by O'Reilly is an amazingly good book by Mara Bos, an important Rust Contributor. Going through the book will take you some time despite its smaller size, but doing so is very rewarding. As with any technical book it is best to read this book as well as do its exercises and apply its knowledge using one program or another. Learn, Apply, Repeat. Play with it, Understand it. + +This book is so good, that even Go, Python or JS developers that will never ever touch Rust, might want to learn Rust just to understand the knowledge that can be found in this Gem of a book. Read it. You won't regret it. + +As it is more advanced knowledge it can however be seen as "Extra", so in case you are in a hurry to finish [section (3) of the Rust track](#3-learn-async-rust), feel free to skip it. But even if so, keep its existence in mind and come back to it perhaps when you start to get yourself into trouble. + +> FYI: if you ever write real-world production low level sync/atomic/concurrent code, +> you might want to check out Loom, as it will help you test that code better then possible with regular tests: +> . + +### Rust Atomics and Locs: Questions + +Questions you should be able to answer at the end of this extra step: + +1. What primitives are there in general to achieve concurrency? +2. What primitives does the OS give you? +3. What is the difference between threads and async programming? +4. Why is async programming faster? +5. When would you use threads? When would you use async programming? +6. What's a Mutex? How could you implement one? +7. What's a Conditional Variable? How could you implement one? +8. What's a Signal? How could you implement one? +9. What's a Channel? How do you implement it? What types of channels are there? +10. What is Reordering? How can we deal with this? How does it affect us? +11. How can we efficiently make a thread go to "Sleep" and have it woken up again? +12. What's a Spin Lock? How do we build one? +13. What's an atomic? What kind of atomics are there? How do they work under the hood? +14. How does Rust achieve thread safety? +15. What's Memory Ordering? What's the Memory Model? What types are there? Which ones can you use? +16. What is Acquire and Release? What is this an example of? +17. When we talk about a "happens-before relationship". What do we mean with it? Why is it important? +18. What is caching in context of your CPU? How does it affect us? What can we do about it? diff --git a/src/guide/learn-async-rust/threading.md b/src/guide/learn-async-rust/threading.md new file mode 100644 index 0000000..75c2ede --- /dev/null +++ b/src/guide/learn-async-rust/threading.md @@ -0,0 +1,8 @@ +### Threading + +Please do remember that Async programming is only beneficial to optimize the idle time of your threads away. +For tasks where you already near 100% utilize your threads (e.g. computation heavy algorithms) something +like async will not help you and will in fact make your codebase a lot more complex and difficult to reason about. + +Should you have computation-heavy algorithms which you want to parallelize you can achieve that by making use +of [threading](https://doc.rust-lang.org/std/thread/) alone. A crate such as might help you a lot with this as well. diff --git a/src/guide/learn-async-rust/tower.md b/src/guide/learn-async-rust/tower.md new file mode 100644 index 0000000..d453136 --- /dev/null +++ b/src/guide/learn-async-rust/tower.md @@ -0,0 +1,18 @@ +### Tower + +Once you step into the world of Async Rust, Tokio and Web Services you'll sooner or later come across [Tower](https://github.com/tower-rs/tower), in a similar fashion as [Serde](https://serde.rs/) blew your mind away for your serialization needs. Yes it did, you can admit it, this is a safe space. + +> ⓘ Tower is a library of modular and reusable components for building robust networking clients and servers. + +With [Tower](https://github.com/tower-rs/tower) everything is a service. A service takes in a request and outputs either an error or a response. +What the actual types for these request-response pairs are, is up to you and depend mostly on the layer it is used. + +In tower it is typical that a service wraps another service, called "layers", as such all your services and middleware will stack on top of each other, +like a... _tower_. + +- if you are new to Tower, you can start learning how to use it by building your own tower middleware from scratch by following the guide at: ; + - if you are not convinced on the usefulness of Tower, you can perhaps read [the "inventing your own Service trait" guide](https://tokio.rs/blog/2021-05-14-inventing-the-service-trait). + +If you want to get an idea of how `Tower` might look like in a Rust ecosystem since 2024, +you can enjoy this future today already at . +Have fun not requiring to implement futures by hand. diff --git a/src/guide/learn-more-rust/README.md b/src/guide/learn-more-rust/README.md new file mode 100644 index 0000000..32f601b --- /dev/null +++ b/src/guide/learn-more-rust/README.md @@ -0,0 +1,4 @@ +## Learn more Rust + +- [Introduction - The Cargo Book](https://doc.rust-lang.org/cargo/index.html): Cargo is the Rust package manager. Cargo downloads your Rust package's dependencies, compiles your packages, makes distributable packages, and uploads them to crates.io: [Rust Package Registry](http://crates.io/), the Rust community's package registry; +- [Getting started - Command Line Applications in Rust](https://rust-cli.github.io/book/index.html): Gives you another practical approach in your Rust Learning, by specifically learning how to write CLI applications in it; diff --git a/src/guide/learn-more-rust/extra.md b/src/guide/learn-more-rust/extra.md new file mode 100644 index 0000000..7de35c7 --- /dev/null +++ b/src/guide/learn-more-rust/extra.md @@ -0,0 +1,64 @@ +## Learn More Rust: Extra + +Once you went through the resources in the previous two chapters you might want to start working on a real project to start applying and solidifying your knowledge. A classic way to do this is by porting a small specialized codebase from one language to Rust, keeping in mind to not 1-to-1 map the lines of code but to instead focus on porting the logic with the "Rust way to do things" in mind. + +Should you want some inspiration or a more guided approach, here are some resources that could help you out with this extra optional, but recommended step: + +- [Command-Line Rust](https://www.oreilly.com/library/view/command-line-rust/9781098109424/): build a cli tool such as grep in rust, using test driven development (TDD), all to learn Rust +- [Rust Application Books - The Little Book of Rust Books](https://lborb.github.io/book/applications.html): lists a lot of different books, including ones that allow you to develop small projects using Rust, usually in a well guided fashion; + - You might find an interesting companion article as it gives some (common) ideas that you can apply to the CLI tool you're building; + - [Introduction - PNGme: An Intermediate Rust Project](https://picklenerd.github.io/pngme_book/introduction.html) is an especially fun small project. It allows you to apply the knowledge that you learned above in a very narrow program, that is for once not network related. At the end you'll have a cli tool that allows you to encode and decode "hidden" messages in a PNG image; +- [Introduction - MacroKata](https://tfpk.github.io/macrokata/index.html): Macro's are in general not very covered in the resources above, as it is not that common that you have to write your own macros. They can however be convenient in certain situations. This book can be seen as a bootstrap tutorial to get you started with one kind of Rust macros. + - If you are interested in (also) learning procedural macros you can perhaps consult the following resources: + - [GitHub - dtolnay/proc-macro-workshop: Learn to write Rust procedural macros [Rust Latam conference, Montevideo Uruguay, March 2019]](https://github.com/dtolnay/proc-macro-workshop) + - [Procedural Macros in Rust (part 1)](https://www.youtube.com/watch?v=geovSK3wMB8) + - Check out "[Diesel is a Safe, Extensible ORM and Query Builder for Rust](https://diesel.rs/)" if you want to see a very cool example of macros (besides all the derives, formatting and printing you might already have been doing) + - [json in serde_json - Rust](https://docs.rs/serde_json/latest/serde_json/macro.json.html) is another neat example as it allows you to quickly define a Json value directly in Rust + - Taking a couple of hours is also a life well spent reading through this codebase as it will teach you a lot of nice things about Rust, especially given how simple and scoped the problem of json serialization is. It will really show you and teach you how serde works and why it works; + - Most web frameworks (if not all) in Rust also heavily make use of Macro's to give you a very neat and clean API + - And of course do not forget to consult the "classic" macro Rust book: [The Little Book of Rust Macros](https://danielkeep.github.io/tlborm/book/index.html) + - If you want to get a quick intro and overview of Macros this video can help a lot as well: [Rust's Witchcraft](https://www.youtube.com/watch?v=MWRPYBoCEaY) + +If you have a lot of free time at your hand and you want to build something really cool that is totally useless, here are some more ideas: + +- Build your own Gameboy (classic) emulator: [Introduction - DMG-01: How to Emulate a Game Boy](https://rylev.github.io/DMG-01/public/book/introduction.html) +- Build your own CHIP-8 (8-bit computer) interpreter: [Cowgod's Chip-8 Technical Reference](http://devernay.free.fr/hacks/chip8/C8TECH10.HTM) (no Rust guidance, directly from the CHIP-8 specification instead, you can do it, I believe in you) +- Build your own Ray Tracer (not a Rust tutorial, but can easily be implemented in Rust as well): [Ray Tracing in One Weekend Series](https://raytracing.github.io/) (fun if you always had the dream to start dabbling into the world of Graphics Programming) + - might be a useful blog series if you want a more guided approach on how you might make a Ray Tracer in Rust; + - is an interesting article in this area as well, where it introduces you to a language called PO; + +Seriously though, do not consider the above recommended or mandatory in any way. If you however really like to develop stuff and you do like to do it extensively in your free time, then, and only then, I do believe that the above are a great way to really solidify your current Rust knowledge and give yourself a great (pragmatic) foundation. + +At this point you might also be ready to start reading alternative — community driven — learning resources on foundational Rust knowledge. With such content you do however always need to be careful as they might contain mistakes, not well rounded or closed opinions. An example of possible valuable learning resources are the following blog series about the Rust type system: + +- part 1 (): ownership and move semantics, aliasing and mutation, lifetime and region based resource management; +- part 2 (/): type as sets, algebraic data types, patterns in Rust using Algebraic types, traits, generic associated types (GAT), operator overloading, use cases; +- part 3 (/): container types, interior mutability, concurrency, deadlocks without threads. + +More parts to come as well. + +For the brave among you with the time for it, learn to build your own Operating System (OS) using Rust: ### Code like a pro in Rust + +At this point of your Rust learning journey you've come a far way already, relatively speaking. Perhaps you want to shortcut, at least for now. + +If so, [the still to be published "Code like a pro in Rust" book](https://www.manning.com/books/code-like-a-pro-in-rust) might be enough for you to quickly get from beginner to advanced Rust programmer. + +### A Crust of Rust + +Once you get at this point you are around the level of a beginner or intermediate Rust programmer. At this point you could already start to tackle stuff like ["Rust for Rustaceans" of step (6)](/guide/study-using-the-rust-for-rustaceans-idiomatic-programming-for-experienced-developers-book.md). However it might be a bit much. + +Therefore while you go through the next couple of sections it could be helpful to now and then (e.g. while washing dishes or instead of Netflix) an education Rust code video. In the appendix at the bottom of this page there a couple of such suggestions. + +Particular to this context you might want to save [the "Crust of Rust" playlist](https://www.youtube.com/playlist?list=PLqbS7AVVErFiWDOAVrPt7aYmnuuOLYvOa). Each video will go over a specific topic, e.g. Lifetimes, macros, Atomics, … No need to watch them one by one, feel free to jump to them in whatever orders and only those that interest you (which is the same tip that I can give for the "Rust for Rustaceans" book). + +### API Design + +Designing APIs is a big part of being a Rust programmer, any programmer really. Once you start to get comfortable enough in Rust or start building your own public crate, it is a topic you'll want to invest in. + +A good starting point is the [API Guidelines](https://rust-lang.github.io/api-guidelines/about.html) which are a set of guidelines that are meant to help you design good APIs. They are not meant to be followed blindly, but rather to be used as a reference to help you make the right decisions. + +A next and continuous step is to read blog posts and watch videos about API design. The Rust newsletter often has an article listed in its weekly edition. But other platforms such as HackerNews will have interesting Rust articles pop up as well. is for example a great article talking about one might to give errors as much love as the other parts of the API, and also talks about why crates like `thiserror` might not be that great. All in all, similar to other parts of your continuous Rust learning journey, you'll want to remain critical and open to new ideas and see what works for you and what not. + +If you are however still in the camp of `thiserror`, you might be able to make good use of blog posts such as that guide you through adding instrumentation to your Axum based web service, +using `thiserror` among other excellent crates such as `tracing`. A great read, especially if you're not that experienced with instrumentation +that goes beyon the basic single line logs. diff --git a/src/guide/learn-more-rust/questions.md b/src/guide/learn-more-rust/questions.md new file mode 100644 index 0000000..1a8eee9 --- /dev/null +++ b/src/guide/learn-more-rust/questions.md @@ -0,0 +1,15 @@ +## Learn More Rust: Questions + +Questions you should be able to answer at the end of this step: + +1. Make sure to be able to answer all questions of step (1). +2. What is cargo and why does it exist? +3. What kind of extensions exist for Cargo, how do we install them, how do we use them and what are some commonly used ones? +4. What is the Cargo.toml file? +5. What is the Cargo.lock file? +6. What are build scripts? Why do we use these? How do we use these? +7. How can we build code? How do we test code? +8. How can we check code without building the final binaries? +9. How do we make a simple CLI application? How do we pass arguments and flags? How do we handle signals? +10. How can we structure our code and package(s)? +11. What does public and private mean in the context of Rust? At what scope do these operate? diff --git a/src/guide/learn-rust/README.md b/src/guide/learn-rust/README.md new file mode 100644 index 0000000..9b4fafa --- /dev/null +++ b/src/guide/learn-rust/README.md @@ -0,0 +1,29 @@ +## Learn Rust + +In case you're new to the language we suggest you to take a look at [Learn Rust](https://www.rust-lang.org/learn) (free): + +- [The Rust Programming Language - The Rust Programming Language](https://doc.rust-lang.org/book/) gives you a very nice overview; + - There are plenty of exercises in the book and at the end of your learning journey you'll get to [build your own multi-threaded web server](https://doc.rust-lang.org/book/ch20-00-final-project-a-web-server.html)! +- [GitHub - rust-lang/rustlings](https://github.com/rust-lang/rustlings): Small exercises to get you used to reading and writing Rust code! is an alternative more pragmatic approach on learning the language; +- [Introduction - Rust By Example](https://doc.rust-lang.org/stable/rust-by-example/) is there for people who like learning from real-world examples; +- is yet another alternative, this time offered by Microsoft, + which seems very similar to the rust book, but more pragmatic tones and you can earn XP! + +Sooner or later you might also need help for a project you work on or simply to learn a concept you do not really understand. Not everybody has a senior or friend around that can help them out with this. For all of this and more you want to probably join one or multiple of the community chat servers listed in [Appendix VII. Community Chat](/appendix/appendix-vii-community-chat.md). + +> ⓘ **Hardcore** alternative +> +> [Programming Rust, 2nd Edition](https://www.oreilly.com/library/view/programming-rust-2nd/9781492052586/) (O'Reilly Publishing) is a big book and will take you some time to get through. It is not for the faint of heart. However… If you do choose for this route as an alternative to [(1) Learn Rust](/guide/learn-rust/index.html), you will absolutely not regret it. In fact, your entire rest of the Journey will be a breeze. +> +> The "Programming Rust, 2nd Edition" book is a gem and in case you can handle big dry Technical books such as these it is one that will give you just as much love back as the energy that you put into it. Take your time, get through it, play with it, and enjoy. In fact, it can be easily paired with Rustlings by doing the exercises linked to the content you're reading. Rust by Example can also be added on top of that to see some more code related to the stuff you're learning. +> +> Soak it in. It's a hardcore alternative, but if you're up for it, it's there for you to grab. +> +> If you've never done any Systems programming before, this will be an especially helpful book given it will explain a lot of the magic you've encountered in your very protected professional life so far. You're welcome. + +### Alternative or Companion resources + +[Welcome to Comprehensive Rust 🦀 - Comprehensive Rust 🦀](https://google.github.io/comprehensive-rust/): a small bootcamp course by Google focused on Android Engineers. Most of it is however applicable to anyone coming to Rust from another language and could be a great alternative or companion for some of the resources above. + +[The "Effective Rust" book](https://www.lurklurk.org/effective-rust/) is an excellent book that might just as well be official Rust material, and +recommended for all Rust learners. So once you think you understand the content of "the Rust book" and the like, you probably want to start reading "Effective Rust", you won't regret it. diff --git a/src/guide/learn-rust/questions.md b/src/guide/learn-rust/questions.md new file mode 100644 index 0000000..ada437a --- /dev/null +++ b/src/guide/learn-rust/questions.md @@ -0,0 +1,32 @@ +## Learn Rust: Questions + +Questions you should be able to answer at the end of this step: + +1. Rust is a Memory-Safe language. How? Why? In what way is this different from other Memory Safe languages such as Go? +2. Rust is a performant language. Why can it claim this. How? +3. How do you structure data in Rust? +4. Is data passed by Reference or value in Rust? And what does it mean? +5. Is data mutable or immutable by default? How do we make it the other way? +6. What are traits and how are these related to the data models that you structure in Rust? +7. How can you extend the behavior of external types? +8. Can you extend behavior of external types using external traits? Why or why not? +9. What is a constant? Where can we define these? +10. What is a static variable? How is it different from a constant? What's special about mutable variables? +11. How does Rust support Async Rust? How do you use it? What are Futures? +12. How do you achieve parallel programming in Rust? +13. What's the difference between async programming and parallel programming? How are they related? +14. What is the borrow checker? What is ownership? How are these concepts related? +15. Data can be moved and it can also be dropped. What do we mean with this? How do we have control over this? +16. How do we achieve shared mutable references to the same data? How can this be done safe? +17. What are lifetimes? How do they work? Can you give some examples of where these are used? +18. What are generics? Why do we use them? +19. What are Rust Macros? When do we use these? What type of Macros are there? +20. How do you build Rust projects? +21. How do we use dependencies of other developers into our projects? And how do we call such dependencies? +22. What are sum types? What are product types? +23. What is an Enum in Rust and how can we use it? How can we define it? +24. What is pattern matching in Rust? How do we do it? How is it more powerful than a switch? +25. How do we write tests in Rust? What kind of tests are there? +26. What are closures and how are they related to functions? What do they have in common? How do they differ? +27. What kind of smart pointers does the Rust std library provide you? What are their use cases, differences, and so on? +28. What is unsafe Rust? How do we use it? When do we use it? What guarantees do we still get, even when using unsafe Rust? diff --git a/src/guide/next-steps.md b/src/guide/next-steps.md new file mode 100644 index 0000000..ae1dcbb --- /dev/null +++ b/src/guide/next-steps.md @@ -0,0 +1,26 @@ +## Next Steps + +If you have completed all the steps above, you have done more then enough and can call yourself a Rustacean. You can now start to contribute to the Rust ecosystem and help others to learn Rust. Perhaps more importantly, you have all the knowledge you need to build your own projects in Rust. + +What you'll build depends on your interest or perhaps in the type of industry or company you're working in. + +- If you're doing full stack development you can get inspired on what's next by checking out [WASM Learning Resources Appendix](/appendix/appendix-ii-webassembly-wasm.md#wasm-learning-resources); + - For all your web dev needs you might also get inspired on what frameworks to use by checking out a website such as ; + - By coincidence, some of the books and articles listed in this guide also teach you a lot about web development, so if you did indeed complete these guide you're really already well on your way to becoming a full stack developer in Rust, or backend, whatever floats your boat; +- Some call WASM (on the server side) the next thing after docker containers. So perhaps even as a "pure" backend developer you might want to check out [that _same_ appendix](/appendix/appendix-ii-webassembly-wasm.md#wasm-learning-resources) to help you get started; +- If you're a game developer (or inspiring to be) you can check out resources such as to figure out what Rust technologies are out there in the ecosystem to help you build the next fantastic game; + - If you're a game developer you might also want to check out the [Rust GameDev Working Group](https://gamedev.rs/) (they also have a monthly news letter); + - You could also subscribe to the a podcast about GameDev in Rust called [Rust GameDev Podcast](https://rustgamedev.com/); +- If you want to develop Operating Systems I already listed some resources to help you get started with that. + - Once (and if) Rust is accepted as a second language (next to C) to develop patches for the Linux kernel you can also start contributing to the Linux kernel in Rust. Future dreams; + - Or you might want to apply to Google and help build [their Fuchsia OS](https://fuchsia.dev/) in Rust. Have fun; + - It's open source so nobody can stop you to contribute it either way, well except them I guess; +- If you want to develop blockchain technology... Well, not going to guide you in that one, there's a running joke that it's hard to find a job in Rust that's not blockchain tech, so, you should have no problem finding a job in that field if that's what you want to do; + - Ok, ok. Here also a list for you folks: +- If you want to develop embedded systems, you can check out the [Rust Embedded Working Groups's Blog](https://blog.rust-embedded.org/). There are also plenty of companies who sometimes appear in articles or podcasts listed in [the More Material appendix](#appendix-vi-more-material), so you can also check that out for yourself. + - A podcast episode about the embedded WG can be found at: + - You can interact with the WG using the matrix chat: +- If you are interested in using Rust for Data Engineering then could be a great start; +- Related to the previous, if you want to use ML from within Rust (or together with it), you might find the following list a great resource: + +There's a lot more of course. You probably know best where you're going. A lot of exciting stuff is happening. Plenty of conferences (e.g. Rust Conf) to help you get inspired on it if you're not already. And of course, plenty of people to help you out if you get stuck. So, good luck and have fun! diff --git a/src/guide/study-using-the-rust-for-rustaceans-idiomatic-programming-for-experienced-developers-book.md b/src/guide/study-using-the-rust-for-rustaceans-idiomatic-programming-for-experienced-developers-book.md new file mode 100644 index 0000000..7df17f9 --- /dev/null +++ b/src/guide/study-using-the-rust-for-rustaceans-idiomatic-programming-for-experienced-developers-book.md @@ -0,0 +1,27 @@ +## Study using the "Rust for Rustaceans: Idiomatic Programming for Experienced Developers" book + +> 🔗 + +Go through the entire book, getting a deep(er) understanding of the advanced concepts and inner workings of them. + +At the end of the book you should be able to present your own GitHub or GitLab hosted projected based on the exercises and projects of the books, where you applied all your knowledge and also put in something of yourself in it. + +Questions you should be able to answer at the end of this step: + +1. Be able to answer all questions from previous sections, in full confidence and in a lot more depth than you could do before. +2. How is memory laid out for your Rust Data structures? Can you control it? If so, how? +3. Explain in full detail so someone new to Rust can understand it what borrowing and lifetimes are, how do they work, why are they important, how do they affect us, how do we encounter it, why do we use it? +4. What primitive types are there in Rust and how are they laid out in memory? +5. What is the Orphan rule? Why is it important? +6. What is polling in the context of Asynchronous programming? +7. List some additional testing tools beyond unit tests? Why does each one of them matter? +8. What is Pin and Unpin? + - Note: Crust of Rust also has a great video about it should you need some more explanations about this tricky concept; +9. Why is Asynchronous programming more complicated than parallel programming? +10. How can you test your Asynchronous code? And because it is Rust, what kind of Asynchronous problems do we not need to test if we structure our code right? And why not? +11. In the context of concurrent programming, what are actors? + - Bonus question: why do some people see this as the future? +12. What is FFI? Why do we use it? +13. What is Rust without the STD? How do we use it and why? +14. What are some common patterns found in the wild and that are discussed in the book? +15. How can you continue to learn Rust? diff --git a/src/guide/study-using-the-zero-to-production-in-rust-book.md b/src/guide/study-using-the-zero-to-production-in-rust-book.md new file mode 100644 index 0000000..0d07417 --- /dev/null +++ b/src/guide/study-using-the-zero-to-production-in-rust-book.md @@ -0,0 +1,43 @@ +## Study using the "Zero to Production in Rust" book + +> 🔗 + +Go through the entire book, filling any gaps you might still have and do all the exercises as well. + +At the end of the book you should be able to present your own GitHub or GitLab hosted projected based on the exercises and projects of the books, where you applied all your knowledge and also put in something of yourself in it. + +> ⓘ Backend frameworks like [Rocket](https://rocket.rs/) and [Actix](https://actix.rs/) are pretty commonly used in books. However know that [the Axum framework](https://docs.rs/axum/latest/axum/) is currently probably your best if you need to choose a backend framework for your next or current Rust project. +> +> Learning Axum in specific could be done by following tutorials +> such as , which seem pretty complete and focussed. +> +> Given how much Axum is built with [Tower in mind, you probably also want to learn that](#tower). + +> There's also a "Crust of Rust" episode, by Jon Gjengset, about "decrusting" +> Axum — and by extension _Tower_ — available at . + +Questions you should be able to answer at the end of this step: + +1. How can we write a Full stack app in Rust? +2. How can we deploy and host a Full stack Rust app in the cloud? +3. How can we add telemetry? +4. How can we interact with Databases using Rust? +5. How can we debug production-quality Rust applications? +6. How can we test Rust applications? +7. How do we make Async applications in Rust? +8. How do we achieve TLS capabilities with Rust? +9. How do we make a web server with Rust? +10. The book uses Actix. What are some alternatives these days? + +### Alternatives + +The goal of hands-on learning with "Zero to Production" is mostly to help you get started writing some +actual Rust projects, there are however also plenty of alternatives to achieve the same. + +- is an interactive book to help you practice Rust by doing projects; +- is a similar concept, which also has a discord and a bit more variety in projects; +- most Rust conferences also have workshops, free or paid, to help you get into Rust or tackle more advanced concepts; +- Shuttle, which allows you to build and ship Rust code, also has a series of tutorials to create, build and ship all kind of projects, + available at ; +- is a paid platform (with very limited free tier) is a platform to help you build projects like your own + Redis, Git, Grep, Docker and more. And that all using Rust (among other languages available); diff --git a/src/intro/README.md b/src/intro/README.md new file mode 100644 index 0000000..fc2030a --- /dev/null +++ b/src/intro/README.md @@ -0,0 +1,24 @@ +[![Repository Banner Image](banner.png)](https://rust-lang.guide) + +[![GitHub Repo stars](https://img.shields.io/github/stars/plabayo/learn-rust-101?style=social)](https://github.com/plabayo/learn-rust-101) [![GitHub](https://img.shields.io/github/license/plabayo/learn-rust-101)](https://github.com/plabayo/learn-rust-101/blob/main/LICENSE) [![available to hire](https://img.shields.io/badge/Glen-available%20to%20hire%20as%20consultant-green)](mailto:glen@plabayo.tech) + +[![Github Sponsors Badge](https://img.shields.io/badge/sponsor-30363D?style=for-the-badge&logo=GitHub-Sponsors&logoColor=#EA4AAA)](https://github.com/sponsors/plabayo) [![Buy Me A Coffee Badge](https://img.shields.io/badge/Buy%20Me%20a%20Coffee-ffdd00?style=for-the-badge&logo=buy-me-a-coffee&logoColor=black)](https://www.buymeacoffee.com/plabayo) + + +[rust]: https://www.rust-lang.org/ + +> ⓘ A guide to aid you in your journey of becoming a Rustacean (Rust developer). See the [Contributing](https://github.com/plabayo/learn-rust-101/blob/main/CONTRIBUTING.md) and [Code of Conduct](https://github.com/plabayo/learn-rust-101/blob/main/CODE_OF_CONDUCT.md) for more information about how to contribute to this repository. + +## Disclaimer + +This guide is made by [Glen De Cauwsemaecker](https://www.glendc.com/) and is in no way endorsed nor affiliated with the Rust foundation. Rust & Cargo are registered trademarks of the Rust foundation. + +## Sharing is caring + +This guide is free and will remain gratis available to share for all who are interested or until the overlords at GitHub pull it down. + +🗞 This guide was featured [on the front page of HackerNews on the 8th of April 2023]() and in [the weekly edition of the Rust newsletter on the 12th of April 2023](https://this-week-in-rust.org/blog/2023/04/12/this-week-in-rust-490/). + +## Sponsors + +Support this project by becoming a [sponsor](https://github.com/sponsors/plabayo). diff --git a/src/intro/about.md b/src/intro/about.md new file mode 100644 index 0000000..3fe0d8b --- /dev/null +++ b/src/intro/about.md @@ -0,0 +1,35 @@ +## About + +[Glen De Cauwsemaecker](https://www.glendc.com/) created this Educational track to help you get started with [Rust][rust] from an absolute beginner all the way until you're an expert in it. He is open to mentor people, lead workshops and more. If you're a team lead that wants to introduce Rust to their team, feel free to talk to him. Glen started with Rust around 2015, when Rust was still unstable and fast moving. Coming from a C++ background in a system programming job the benefits were immediately clear to him. In the meanwhile things have changed a lot and many companies have been starting to adopt Rust in their toolset: + +- Amazon Web Services (AWS) has used Rust since 2017 for its serverless computing offerings, AWS Lambda and AWS Fargate. With that, Rust has gained further inroads. The company has written the Bottlerocket OS and the AWS Nitro System to deliver its Elastic Compute Cloud (EC2) service. +- Cloudflare develops many of its services, including its public DNS, serverless computing, and packet inspection offerings with Rust. +- Dropbox rebuilt its backend warehouse, which manages exabytes of storage, with Rust. +- Google develops parts of Android, such as its Bluetooth module, with Rust. Rust is also used for the crosvm component of Chrome OS and plays an important role in Google's new operating system, Fuchsia. +- Facebook uses Rust to power Facebook's web, mobile, and API services, as well as parts of HHVM, the HipHop virtual machine used by the Hack programming language. +- Microsoft writes components of its Azure platform including a security daemon for its Internet of Things (IoT) service in Rust. +- Mozilla uses Rust to enhance the Firefox web browser, which contains 15 million lines of code. Mozilla's first two Rust-in-Firefox projects, its MP4 metadata parser and text encoder/decoder, led to overall performance and stability improvements. +- GitHub's npm, Inc., uses Rust to deliver "upwards of 1.3 billion package downloads per day." +- Oracle developed a container runtime with Rust to overcome problems with the Go reference implementation. +- Samsung, via its subsidiary SmartThings, uses Rust in its Hub, which is the firmware backend for its Internet of Things (IoT) service. +- [The U.S. Department of Commerce's National Institute of Standards and Technology (NIST) has added Rust to its list of "Safer Languages" as part of its Software Assurance Metrics and Tool Evaluation (SAMATE)](https://foundation.rust-lang.org/news/rust-identified-as-safer-coding-tool-by-nist/). + +Google also has a nice article about Facts and Debunked Myths about Rust which you can find at (2022). + +The language and its ecosystem have also very matured. Concepts like Async have also landed and Async runtimes such as Tokio have become stable and can be used without fear. While it was harder to convince companies to jump on the Rust wagon in the past, by now it should be a lot easier to sell. Is it one language to replace them all? Of course not, but neither should it be overlooked. Are you not sure how Rust might benefit your team for one thing or another? Contact [Glen](https://www.glendc.com/) and figure it out together. + +If you are a bit of a history nerd you might also enjoy: + +- this article: [How Rust went from a side project to the world's most-loved programming language](https://www.technologyreview.com/2023/02/14/1067869/rust-worlds-fastest-growing-programming-language/) +- or this podcast: [History of Rust with Ben Striegel — Rustacean Station](https://rustacean-station.org/episode/042-ben-striegel/) + +There's a [last section on the end of the Rust learning content](/appendix/appendix-vi-more-material.md). +This one contains useful references and sources that you can check as part of your +continuous journey as a capable Rust developer. + +In case you are a Python or Javascript developer you might find the [Appendix V. Python / Javascript developers](/appendix/appendix-v-python--javascript-developers.md) section useful. + +Not convinced yet? Read here what others have to say about Rust: + + +[rust]: https://www.rust-lang.org/ diff --git a/img/banner.png b/src/intro/banner.png similarity index 100% rename from img/banner.png rename to src/intro/banner.png diff --git a/src/intro/learning-rust.md b/src/intro/learning-rust.md new file mode 100644 index 0000000..9cc6497 --- /dev/null +++ b/src/intro/learning-rust.md @@ -0,0 +1,37 @@ +## Rust 101 Course + +The origins of this guide can be found in the preparation of a semester long course I gave to a group of employees at [OTA Insight Ltd.](https://www.otainsight.com/). The recordings of this course are available on YouTube at: . The videos are however not of the highest quality, especially given the many better resources out there. + +## Learning Rust + +Becoming proficient in Rust requires the fulfillment of three pillars: + +- Pillar I: Learn Rust and get your foundations right + - [Learn Rust](/guide/learn-rust/index.html) + - [Learn More Rust](/guide/learn-more-rust.md) + - [Learn Async Rust](/guide/learn-async-rus.mdt) + - [Study using the "Rust for Rustaceans: Idiomatic Programming for Experienced Developers" book](/guide/study-using-the-rust-for-rustaceans-idiomatic-programming-for-experienced-developers-book.md) +- Pillar II: Develop with Rust (Practical Experience) + - [Study using the "Zero to Production in Rust" book](/guide/study-using-the-zero-to-production-in-rust-book.md) + - [Contribute for the first time to an existing project](/guide/contribute-for-the-first-time-to-an-existing-project.md) + - [Contribute an advanced feature to an existing project or start a project from scratch](/guide/contribute-an-advanced-feature-to-an-existing-project-or-start-a-project-from-scratch.md) +- Pillar III: Be part of the Rust Ecosystem: + - [Next Steps](/guide/next-steps.md) + +What steps of each pillar you do is not of too much problem, do whatever feels best for you. +You can of course complete all steps, and do them in the order as given, but most likely +you probably want to use this learning guide more as a reference and for inspiration, +rather then to follow it word by word. + +The above paths are just a suggestion and also should make clear that there are many ways and approaches to using this guide. +Most important is that you do enjoy the journey and that you learn consistently (e.g. ~ X hours per week). How you'll walk the path and how often you revisit things will depend on your learning style and capabilities. There are however no wrong ways to go. E.g. maybe you want to dive into some code yourself as soon as possible and only then will start covering foundations. Or perhaps you first wanna feel very comfortable to only then start really coding yourself once you think you understand the foundations well. All up to you really. + +Only thing I would really want to hammer on is to do a lot of coding yourself. The best way to learn is to do. So don't be afraid to make mistakes and to try things out. You'll learn a lot more that way. It will be a very confronting journey but it will be worth it. If all you do is read and read you'll never really get a feel for the language and you'll never really get a feel for what you can do with it. So please, do a lot of coding yourself. Plus at times we can trick our brain into thinking we understand something when we don't. + +Also even if you start to reach advanced topics (e.g. Rust for Rustaceans), it is still very important to keep doing the basics. You'll be surprised how quickly you can forget things. So keep doing the basics and keep doing the advanced topics. It is a never ending journey. + +You'll notice when reading this guide that there are often alternatives mentioned or several layers of difficulty. With this in mind it might very well be your choice to go through a section shallow to start, going through the basic/foundational material, to then come back to it after having gone through other sections already with more experience under your belt. At this point you might have more confidence to get to the more advanced material of the section or have gained the background or mindset to understand that content and get more out of it. The spatial repetition as a result is on top of this all an excellent way to slowly but surely mold your grey mass into the desired shape. + +In case you are not planning to work on a project anytime soon that requires Async programming. Feel free to skip [that section](/guide/learn-async-rust.md) for the time being should it be the case. For now just know that official Async support in Rust exists and that it has an important place within the Rust ecosystem. You can always come (back) to it at a future point when you do decide or realize that strong foundations in this section can help out. + +If you ever feel stuck, or want a guide, teacher or mentor. Feel free to reach out to Glen at [glen@plabayo.tech](mailto:glen@plabayo.tech) to book a 1-on-1 session or a workshop for your organization. It can be a one time thing or we can meet regularly to help you along the way. diff --git a/src/intro/prologue.md b/src/intro/prologue.md new file mode 100644 index 0000000..f13f877 --- /dev/null +++ b/src/intro/prologue.md @@ -0,0 +1,11 @@ +## Prologue + +[Rust][rust] is a modern systems programming language with safety in mind as one of its core goals and strengths. Systems programming is programming within a resource constrained environment. However, as a lot of our services run now in paid-for-usage cloud environments, we can also consider them as resource constrained environments. This is why Rust is a great fit for more use cases than people might realize. + +As it is a modern language and has taken the lessons from many other languages before it, it is also surprisingly pleasant to use once you get the hang of it. Its type system also allows expressive code that can help you exclude a great categories of bugs beyond the benefits that static typing can bring. + +The goal of this guide is to introduce Rust to you as an individual or an entire organization. Should this not be sufficient you can also contact me for 1-on-1 coaching or workshops for your organization, by emailing me at [glen@plabayo.tech](mailto:glen@plabayo.tech). More information on Glen can be found at . + +This guide is fully open source and the complete source code can be found at . If you find any errors or have any suggestions, please open an issue or a pull request. If you want to contribute to this guide, please read the [Contributing Guidelines](https://github.com/plabayo/learn-rust-101/blob/main/CONTRIBUTING.md). This guide is licensed under the [MIT License](https://github.com/plabayo/learn-rust-101/blob/main/LICENSE) and developed with love by [Plabayo](https://plabayo.tech/). + +[rust]: https://www.rust-lang.org/ diff --git a/theme/favicon.png b/theme/favicon.png new file mode 100644 index 0000000000000000000000000000000000000000..17f7684c79d4962f554eb88a827ff692a17a40ad GIT binary patch literal 5283 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 literal 0 HcmV?d00001