doc: intro / conclusion / fixups

- General Introduction / Conclusion - Generally, be more specific about the difference between packages and crates.
canardleteer · Dec 10, 2023 · 1e5507f · 1e5507f
1 parent edc6189
commit 1e5507f
Show file tree

Hide file tree

Showing 12 changed files with 64 additions and 19 deletions.
diff --git a/book/src/00-00-intro.md b/book/src/00-00-intro.md
@@ -0,0 +1,16 @@
+# Introduction
+
+I wrote this as a quick guide for folks who are choosing to, or being asked to:
+
+- Work with Rust repositories.
+- Align development practices around Rust repositories.
+- In some way incorporate Rust in their day to day development considerations.
+
+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
+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.
diff --git a/book/src/01-00-first-steps.md b/book/src/01-00-first-steps.md
@@ -8,16 +8,18 @@ git clone https://github.com/canardleteer/quickly-explore-rs.git
 
 ## Cargo
 
-- `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.
-
+- `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?
   - This sometimes fails for people. There's enough info in the shell script
     to manually do it.
 
+- Poke around a little bit.
+
 ```text
 # Take a look at what ya got:
 rustup show

diff --git a/book/src/03-00-this-repo.md b/book/src/03-00-this-repo.md
@@ -9,7 +9,7 @@ cargo new quickly-explore-rs
 It made a few files:
 
 - `Cargo.toml`
-  - Which defines your dependencies and a few other things.
+  - Which defines your package's dependencies and a few other things.
 - `.gitignore`
   - Which ignores the `target` directory, which is your build output.
 - `src/main.rs`
@@ -20,15 +20,15 @@ Files that may get generated for you as you poke around:
 - `target/*`
   - Your build directory.
 - `Cargo.lock`
-  - Dependency reification. [Documentation](https://doc.rust-lang.org/cargo/guide/cargo-toml-vs-cargo-lock.html)
+  - 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 as generated.**
+  - **Even though this repository is an application, we are not commiting it, so it remains closer to "as generated."**
 
-`cargo` won't make:
+`cargo` won't make the following files present in this repository:
 
 - `README.md`
 - `book/`
 - `rust-toolchain.toml`
 - `.github/`
 
-Those have been added after the initial buildout, for documentation & pinning purposes.
+Those have been added after the initial buildout, for documentation, publishing & pinning purposes.
diff --git a/book/src/06-02-toolchain.md b/book/src/06-02-toolchain.md
@@ -8,5 +8,5 @@ An example would be:
 ```toml
 [toolchain]
 profile = "default"
-channel = "1.72.1"
+channel = "1.74.0"
 ```
diff --git a/book/src/06-03-workspaces.md b/book/src/06-03-workspaces.md
@@ -3,4 +3,8 @@
 It's worth knowing about Rust Workspaces, and you can
 [learn about them here](https://doc.rust-lang.org/book/ch14-03-cargo-workspaces.html).
 
-- If you find yourself wanting more "crates" but want to be in a single repository, this is generally what you want.
+- If you find yourself wanting to work on more "packages," but remain in a
+  single repository, this is generally what you want.
+- These are things that generally "all change together at once."
+- These can be very useful while gradually separating isolated components,
+  without forcing it all to happen at once.
diff --git a/book/src/07-00-ecosystem.md b/book/src/07-00-ecosystem.md
@@ -7,6 +7,12 @@ The root level place folks head to for the Rust Ecosystem is:
   - It gets much more complex when dealing with private/internal crate repositories.
 - You will add things here to your `Cargo.toml` file under `[dependencies]`
 - Documentation, will be published to [docs.rs](https://docs.rs/)
+- **crates** in general are versioned and compiled libraries/executables,
+  built from a **package** repository.
+  - It's usually okay to interchange the term "crate" and "package," but they do
+    have specific meaning in some contexts.
+  - Once published to a public place like `crates.io`, a crate can be redacted,
+    but are otherwise immutable.
 
 `cargo` itself, has it's own ecosystem of tools, like:
 

diff --git a/book/src/07-01-whats-out-there.md b/book/src/07-01-whats-out-there.md
@@ -4,22 +4,22 @@
 
 - CLI Arg parsing: [clap](https://crates.io/crates/clap)
 - Serialization / Deserialization: [serde](https://crates.io/crates/serde)
-- [Awesome Rust](https://github.com/rust-unofficial/awesome-rust) is a curated list of useful crates.
+- [Awesome Rust](https://github.com/rust-unofficial/awesome-rust) is a curated list of useful packages.
 - Asyncronous Rust: [async-book](https://rust-lang.github.io/async-book/)
   - I mostly use [tokio](https://tokio.rs/), but there is more than one `async` runtime available.
     - Even for microcontrollers, [embassy](https://github.com/embassy-rs/embassy) is an example.
   - gRPC Services/Clients: [tonic](https://github.com/hyperium/tonic) (with [prost](https://github.com/tokio-rs/prost) for protobuf)
   - REST Services: [hyper](https://hyper.rs/)... Likley something built on top of `hyper`.
-  - HTTP Service Calls: [reqwest](https://github.com/seanmonstar/reqwest), but likley a client autogenerated via an OpenAPI crate (there are a few).
-  - ["Are we web yet?"](https://www.arewewebyet.org/) is a website that generally contains a curated list of traditional service crates.
+  - HTTP Service Calls: [reqwest](https://github.com/seanmonstar/reqwest), but likley a client autogenerated via an OpenAPI package (there are a few).
+  - ["Are we web yet?"](https://www.arewewebyet.org/) is a website that generally contains a curated list of traditional service packages.
     - I personally don't use this list much, but it's useful to see what's out there.
   - [tokio-console](https://github.com/tokio-rs/console) is a good thing to know about, if you use `tokio`.
 
 - Kubernetes:
   - Kubernetes management (from Deployment, through Operators & Controllers to Schedulers): [kube.rs](https://kube.rs/)
 
 - Tracing / Logging
-  - Start by learning the [log](https://github.com/rust-lang/log) crate with `env_logger`.
-  - Then learn about Tokio's [tracing](https://github.com/tokio-rs/tracing) crate.
+  - Start by learning the [log](https://github.com/rust-lang/log) package with `env_logger`.
+  - Then learn about Tokio's [tracing](https://github.com/tokio-rs/tracing) package.
     - Then, like myself, patiently await `tracing v0.2.x`
     - Once you learn how Context propagation works in Rust, `tracing` can be hooked into observability stacks via layering, but it's worth learning `tracing` for just `async` Rust first.
diff --git a/book/src/07-03-benchmarking.md b/book/src/07-03-benchmarking.md
@@ -1,6 +1,6 @@
 # Benchmarking
 
-- I don't think Rust has "full support" for benchmarks without additional crates (yet).
+- I don't think Rust has "full support" for benchmarks without additional packages (yet).
 - Benchmark tests (via the `#[bench]` macro) are a thing in Nightly Rust, these are good for simple things.
 - I use [criterion.rs](https://github.com/bheisler/criterion.rs) for non-trivial benchmarking.
 - But there is more available, and you can learn about all of this from the [Rust Performance Book](https://nnethercote.github.io/perf-book/benchmarking.html).
diff --git a/book/src/10-01-cargo-add.md b/book/src/10-01-cargo-add.md
@@ -1,10 +1,12 @@
 # Add a crate
 
-First, let's add the extremely useful `clap` library to our `Cargo.toml`. Start by checking out the [crate page](https://crates.io/crates/clap).
+First, let's add the extremely useful `clap` library to our `Cargo.toml`. Start
+by checking out the [crates.io page](https://crates.io/crates/clap).
 
 I am pinning the version, to `4.4.11`, and adding 2 Features: `derive` and `env`.
 
-- "Features" for crates are important to know about, but I'm not going to cover them here. You can [read up on them](https://doc.rust-lang.org/cargo/reference/features.html).
+- "Features" for crates/packages are important to know about, but I'm not going to cover
+them here. You can [read up on them](https://doc.rust-lang.org/cargo/reference/features.html).
 
 ```shell
 -> cargo add [email protected] --features derive,env

diff --git a/book/src/10-05-cargo-clippy.md b/book/src/10-05-cargo-clippy.md
@@ -26,7 +26,7 @@ There are 4 other options, which would be to disable linting of that specific ru
 - That line
 - That function
 - That module
-- The whole crate
+- The whole package
 
 But I won't go into that. The linter isn't always right, but often is. You
 have many options that don't involve disabling the linter completely. Don't

diff --git a/book/src/11-00-conclusion.md b/book/src/11-00-conclusion.md
@@ -0,0 +1,13 @@
+# Conclusion
+
+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.
+- 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
+  the box.
+- Are curious maybe? Looking to go back and learn more about some of the
+  features skimmed over?
diff --git a/book/src/SUMMARY.md b/book/src/SUMMARY.md
@@ -1,5 +1,6 @@
 # Summary
 
+- [Introduction](./00-00-intro.md)
 - [First Steps](./01-00-first-steps.md)
 - [VSCode](./02-00-vscode.md)
 - [This Repository](./03-00-this-repo.md)
@@ -23,3 +24,4 @@
   - [Run the new version](./10-03-cargo-run.md)
   - [Format the changed code](./10-04-cargo-fmt.md)
   - [Lint the changed code](./10-05-cargo-clippy.md)
+- [Conclusion](./11-00-conclusion.md)