From c2c462d40e65e056ec3dd7463207a38c92eebba1 Mon Sep 17 00:00:00 2001 From: canardleteer Date: Mon, 15 Apr 2024 19:37:42 -0700 Subject: [PATCH] doc: address various feedback notes received --- README.md | 2 +- book/src/00-00-intro.md | 14 +++++++++++++- book/src/01-00-first-steps.md | 30 ++++++++++++++++++++++-------- book/src/02-00-vscode.md | 17 ++++++++++++++++- book/src/03-00-this-repo.md | 4 ++-- book/src/06-04-macros.md | 2 +- book/src/10-03-cargo-run.md | 4 ++-- book/src/11-00-conclusion.md | 2 +- 8 files changed, 58 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 01259c3..87b1a9f 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Quickly Explore The Rust Toolbox -- The guide to accompany this repository, is now hosted on Gitlab Pages: +- The guide to accompany this repository, is now hosted on GitHub Pages: - [https://canardleteer.github.io/quickly-explore-rs/](https://canardleteer.github.io/quickly-explore-rs/) - Assuming you have `mdbook` installed, you can view it locally via: diff --git a/book/src/00-00-intro.md b/book/src/00-00-intro.md index 41c6fd9..1201864 100644 --- a/book/src/00-00-intro.md +++ b/book/src/00-00-intro.md @@ -10,7 +10,19 @@ There is no expectation that you "want" to do any of this, and it's not my goal to make you want to. The goal here, is to provide a quick tour of what exists in the Rust Ecosystem. -**I am not intending to teach people how to write Rust.** Where possible, I do +*I am not intending to teach people how to write Rust.* Where possible, I do point to far better resources on that subject than I would be able to write. The Rust ecosystem has been good to me, and I recommend you give it a shot. + +- **For developers coming from C or C++**, you should **prepare to learn to trust + your compiler warnings by default again** while learning Rust. + - There will come a day when you know Rust better than the Rust compiler does, + but it's probably not going to be Day 1. + +- **For developers who don't naturally start with + [Test-driven Development](https://en.wikipedia.org/wiki/Test-driven_development)**, + I encourage you to prepare yourself to engage with the test system earlier, + rather than later. + - The testing framework is already setup for you, and extremely easy to use. + - The benchmark tooling is very easy to access (and will soon be built in). diff --git a/book/src/01-00-first-steps.md b/book/src/01-00-first-steps.md index 81a2ace..2105e1e 100644 --- a/book/src/01-00-first-steps.md +++ b/book/src/01-00-first-steps.md @@ -1,24 +1,23 @@ # First Steps +## Clone This Repository + - The expectation, is that you have [the repository that hosts this book](https://github.com/canardleteer/quickly-explore-rs) open and available for reference. ```shell git clone https://github.com/canardleteer/quickly-explore-rs.git ``` -## Cargo +## Install Rust -- `cargo` is the general **package manager** for the Rust ecosystem, and your general "entrypoint" into Rust. - - The overall [Cargo documentation](https://doc.rust-lang.org/cargo/getting-started/installation.html) is going to be better than mine. This is just a quick tour. - - In practice, calling the Rust compiler (`rustc`) directly, is rare. - Start by going to [rustup.rs](https://rustup.rs/) to download the installer. - You are welcome to audit the shell script beforehand, since I don't - recommend randomly piping curl to a shell, but that seems to be the - way people do things now? + recommend randomly piping curl to a shell (but that seems to be the + way people do things now?) - This sometimes fails for people. There's enough info in the shell script to manually do it. -- Poke around a little bit. + - Poke around a little bit. ```text # Take a look at what ya got: @@ -34,7 +33,22 @@ rustup component add rustfmt rustup component add clippy ``` -**You are now setup with everything you should need.** +## Cargo + +- `cargo` is the general **package manager** for the Rust ecosystem, and your general "entrypoint" into Rust. + - It is also how you launch compiling your code (which is a package, or collection of packages). + - The overall [Cargo documentation](https://doc.rust-lang.org/cargo/getting-started/installation.html) is going to be better than mine. This is just a quick tour. + - In practice, calling the Rust compiler (`rustc`) directly, is rare. + +```text +# What version did ya get? +cargo --version + +# What can cargo do? +cargo --list +``` + +**You are now generally setup with everything you should need.** If you want to: diff --git a/book/src/02-00-vscode.md b/book/src/02-00-vscode.md index f0b4461..fc1ad59 100644 --- a/book/src/02-00-vscode.md +++ b/book/src/02-00-vscode.md @@ -8,4 +8,19 @@ If you open this repository in VSCode, you will probably want to install the fol And possibly whatever else comes recommended. -VSCode is fairly common as a Rust IDE, but you are of course welcome to choose whatever you like. +VSCode is fairly common as a Rust IDE, but you are of course welcome to choose +whatever you like... + +## If you don't want to use VSCode + +I fully support this decision. + +I hear the `emacs` experience is great! + +I caution you, that as far as I know, neither Rust Rover, nor Sublime implement +the [Language Server Protocol](https://langserver.org/) out of the box. You +**definitely** want to be setup with it for a smooth "start learning" experience. + +- It is up to you, if learning how to add LSP support to the IDE of your own + choosing, for a language you're just learning, is something you want to do + right now. diff --git a/book/src/03-00-this-repo.md b/book/src/03-00-this-repo.md index 124475a..e1389d7 100644 --- a/book/src/03-00-this-repo.md +++ b/book/src/03-00-this-repo.md @@ -22,7 +22,7 @@ Files that may get generated for you as you poke around: - `Cargo.lock` - Dependency reification lock file - [documentation](https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html) - If you're authoring an application, yes you commit it to your source tree. If you're authoring a library, no, you don't commit it. - - **Even though this repository is an application, we are not commiting it, so it remains closer to "as generated."** + - **Even though this repository is an application, we are not committing it, so it remains closer to "as generated."** `cargo` won't make the following files present in this repository: @@ -31,4 +31,4 @@ Files that may get generated for you as you poke around: - `rust-toolchain.toml` - `.github/` -Those have been added after the initial buildout, for documentation, publishing & pinning purposes. +Those have been added after the initial build-out, for documentation, publishing & pinning purposes. diff --git a/book/src/06-04-macros.md b/book/src/06-04-macros.md index 164af85..19ae123 100644 --- a/book/src/06-04-macros.md +++ b/book/src/06-04-macros.md @@ -1,6 +1,6 @@ # Macros -The macro sytax in Rust is both extremely powerful and useful, but can appear +The macro syntax in Rust is both extremely powerful and useful, but can appear to be a bit arcane and "meta." They are not like `C/C++` macros. It will be awhile before you understand why and where to use macros, and that's before you understand how to. All that is okay. diff --git a/book/src/10-03-cargo-run.md b/book/src/10-03-cargo-run.md index a90228e..4fedfe7 100644 --- a/book/src/10-03-cargo-run.md +++ b/book/src/10-03-cargo-run.md @@ -1,6 +1,6 @@ # Run the new version -You can declare a whole lot more with `clap`, like commands, subcommands, etc. But we're not going to do any of that. +You can declare a whole lot more with `clap`, like commands, sub-commands, etc. But we're not going to do any of that. - Build it: @@ -20,7 +20,7 @@ Options: -V, --version Print version ``` -Wow, we got a whole lot out of the box from that, and in general those add ons do what you expect them to. +Wow, we got a whole lot out of the box from that, and in general those add-ons do what you expect them to. - Let's try it two ways: diff --git a/book/src/11-00-conclusion.md b/book/src/11-00-conclusion.md index 58a013b..c12b5e8 100644 --- a/book/src/11-00-conclusion.md +++ b/book/src/11-00-conclusion.md @@ -4,7 +4,7 @@ Hopefully, you've somewhat learned how to: - Can build most Rust repositories from source. - Generally know how to interact with plain Rust codebases. -- Are not afriad of what's going on in a Rust repository. +- Are not afraid of what's going on in a Rust repository. - Know, in general, where to find packages, and can loosely equate them to another language's packages. - Know what kind of build / testing / dependency tooling is available out of